MergeTaJson is an OCL operator for EAL actions that imports JSON into an existing model object by using a ViewModel as the mapping template.

Syntax

object.MergeTaJson(viewmodelname, json)

• object is the model object to update.
• viewmodelname identifies the ViewModel that defines the JSON-to-model mapping.
• json is the JSON string to import.

The operator returns a string containing the Merge/Apply log. Capture or inspect this result when you need to diagnose an import.

Map JSON fields with a ViewModel

The ViewModel passed to MergeTaJson is the mapping template. It is not rendered for this operation. You can therefore create a small dedicated ViewModel that contains only the fields that an import may update.

For each ViewModel column, the left side defines the JSON key and the right side identifies the attribute on the target object. For example, this column maps the JSON key author_name to the author attribute of the receiving object:

author_name : self.author

With that mapping, this JSON:

{
  "author_name": "Buyondo"
}

updates self.author to Buyondo. The JSON key does not need to have the same name as the model attribute.

Update selected fields

Use a ViewModel template that exposes only the fields you intend to import. A JSON payload containing a mapped field updates that field on the receiving object; this makes the operator suitable for a targeted update.

For example, the following action expression updates the author of the current root article using the ArticlesJsonTemplate mapping:

vCurrent_Root.MergeTaJson(Articles1.ViewModels.ArticlesJsonTemplate,'{
"author_name": "Buyondo"
}'
)

In this example, the template maps author_name to the article's author attribute. Fields that are not part of this JSON update are not the purpose of this operation.

Copy mapped values from another object

You can combine MergeTaJson with AsTaJson to transfer values between objects through the same ViewModel template. This ensures that the export and import use the same field names and mapping.

For example, place the following expression in the Expression After Modal OK slot of an action that opens an article seeker. After the user selects an article, the selected article is exported as JSON and merged into the currently open article:

vCurrent_Article.MergeTaJson(
  Articles1.ViewModels.ArticlesJsonTemplate,
  vModalResult_vCurrent_Articles1.AsTaJson(Articles1.ViewModels.ArticlesJsonTemplate, false)
)

Here:

• vModalResult_vCurrent_Articles1 is the article selected in the modal seeker.
• AsTaJson(..., false) creates JSON based on ArticlesJsonTemplate.
• vCurrent_Article receives the mapped values.

Import nested objects and associations

MergeTaJson can also import a JSON object hierarchy when the ViewModel contains nested ViewModel classes and associations. The root object must be supplied to the ViewModel class; the JSON then updates the hierarchy below that root according to the ViewModel structure.

The import recognizes the following ViewModel conventions:

Convention	Purpose during import
<ViewModelColumn>_AddNew action	Creates an object needed for an association named by the ViewModel column. The action must return the created object and must add that object to the association. If no such action is found, the import uses type information to create the object.
vImportKey:string variable	Receives the import key before an object is created. An _AddNew action can use it to find an existing object instead of creating a new one.
Delete action in a nesting	Is used, when present, to delete an object that is missing from the input when merge mode is not in effect.
CleanUpAction on the root ViewModel class	Runs after the import finishes. Prepare it as a column for an action in the ViewModel Editor.

Handle large existing collections

By default, updating a many association can load all existing objects in that association so the import can locate objects by the IDs in the JSON. For a large dataset, this can be slow and consume too much server memory.

To control that lookup, add an action named <ViewModelColumn>_Lookup. The import calls this action and expects it to populate the many association. Before the call, vImportKey contains a comma-separated list of keys from the JSON. Use a collection variable as the expression of the many association, and let the lookup action populate that variable with the matching existing objects.

For the complete JSON hierarchy rules, association behavior, and JSON generation options, see Documentation:Tajson.

Check the import log

Both MergeTaJson and ApplyTaJson return a potentially large log string. Use the returned value when validating an import or investigating unexpected mapped values.

vImportLog := vCurrent_Root.MergeTaJson(
  Articles1.ViewModels.ArticlesJsonTemplate,
  '{
    "author_name": "Buyondo"
  }'
)

See also

• Documentation:Tajson
• Documentation:EAL
• Learn OCL