Configuring the updater file for generated endpoints

An updater file contains an updaters section that lists one or more API resources. For each resource, the following attributes are specified:

• The schemaDefinition that defines the structure of the resource
  • This references a schema declared in a schema.json file.
• The data model entity that serves as the root for mapping information for this resource.
• A list of properties
  • Each property includes a path attribute. This defines, for each resource property, the data model entity property into which the resource field property is to be written.
  • Depending on the nature of the property, there may be additional attributes.

For example, the following is a portion of the updater for the base configuration Activity resource:

"Activity": {
  "schemaDefinition": "Activity",
  "root": "entity.Activity",
  "properties": {
    "description": {
      "path": "Activity.Description"
    },
    "mandatory": {
      "path": "Activity.Mandatory"
    },
    ...

Note the following:

• This resource is defined in the schema who name is Activity (This schema is defined in some other schema.json file.)
• The root for the resource mapping is entity.Activity.
• For each instance of the resource:
  • The value of the description property is written to the Activity entity's Description field.
  • The value of the mandatory property is written to the Activity entity's Mandatory field.

Note that there may be properties that appear in the mapping file but not the updater file. This typically occurs with properties that are read-only. For example, the Activity entity has a closeDate property, which the application sets when the activity is closed. This property appears in the mapping file, as it can be read. But it does not appear it the updater file because it cannot be written to.

The base configuration includes a set of API-specific extension updater files. The purpose of these files is to define updater information for custom resources for a given API. These files are named using the pattern <API>_ext-1.0.updater.json, where <API> is the internal name of the API. For example, the common_ext-1.0.updater.json file is used to define updater information for custom resources in the Common API. You can access extension mapping files in Studio through the integration -> mappers -> ext -> <API>.v1 node.

When you generate endpoints for a custom entity, the REST endpoint generator adds the following code to the relevant extension updater file:

    "<resourceName>": {
      "schemaDefinition": "<schemaNameForResource>",
      "root": "entity.<customEntity>",
      // TODO RestEndpointGenerator : Add updater properties here
      "properties": { }
    }

    "CustomEntityExt": {
      "schemaDefinition": "CustomEntityExt",
      "root": "entity.CustomEntity_Ext",
      // TODO RestEndpointGenerator : Add updater properties here
      "properties": { }
    }

Note that the REST endpoint generator does not provide any properties information. This is because the only field that gets added to the schema definition files is the id field. This field is not writeable, so it is not added to the updater.

The developer is responsible for:

• Deciding which fields from the custom entity must be available for POSTs and PATCHes
• Adding updater information for those fields.

For example, suppose the CustomEntity_Ext entity included three fields:

• CustomDescription (a string)
• IsActive (a boolean)
• ExpirationDate (a datetime)

The developer decides CustomDescription and IsActive must be available to POSTs and PATCHes. The developer would need to add the code shown below in bold.

    "CustomEntityExt": {
      "schemaDefinition": "CustomEntityExt",
      "root": "entity.CustomEntity_Ext",
      // TODO RestEndpointGenerator : Add updater properties here
      "properties": {
        "customDescription": {
          "path": "CustomEntity_Ext.CustomDescription"
        },
        "isActive": {
          "path": "CustomEntity_Ext.IsActive"
        }
      }
    }

The developer decides ExpirationDate must not be available to POSTs and PATCHes. The field may appear in the schema and mapper, as it may be available for GETs. But it is omitted from the updater as it is not available to POSTs or PATCHes.