Interfaces require a fixed data structure. This article describes the structure of the JSON format.

Data structure for synchronizing with an external application

The data structure used to upload element data is similar for both the custom interface configured with a power user (via upload) and the custom interface configured with an external application (via API request). The code below describes the structure needed to upload data to Relatics:

{
   "TypeElementPlural": [
      {
         "@externalid": "Unique value",
         "PropertyName": "Value",
         "PropertyName": Number,
         ...
         "RelationName": [
            {"@id": "element ID"},
            {"@id": "element ID"},
            ...
         ]
      },
      ...
   ]
}

Notes:

• The italic texts should be replaced by data representing your SE model in Relatics.
• Every JSON object in “TypeElementPlural” needs a JSON property “@externalid” that should be populated with a unique value. Relatics stores these values in a system property for the corresponding elements. When an update is presented, Relatics uses the “@externalid” to determine if an element needs to be created, updated, or deleted.
• The JSON property “@externalid” allows a value with a maximum length of 450 characters.
• The values of the JSON properties ​​must follow the same rules that manual entry enforces, specific to the property type in which the information is stored.
• Dates must be structured as strings like “YYYY-MM-DD”, where YYYY corresponds to the year, MM corresponds to the month, and DD corresponds to the day.
• The decimal sign of number values has to be a point.
• Relations are always stored as an array, even if the cardinality of the relation is configured as single.
• Characters that are not letters or numbers in JSON names are escaped. See the section below for further details.
• Elements not supplied in the request body will be deleted.

Example of the JSON data:

{
   "Persons": [
      {
         "@externalid": "43530759",
         "First_x0020_name": "Ace",
         "Last_x0020_name": "Whitney",
         "Date_x0020_of_x0020_birth": "1980-04-09",
         "works_x0020_for": [
            {"@id": "ORG-1"}
         ]
      },
      {
         "@externalid": "d390874b",
         "First_x0020_name": "Diogo",
         "Last_x0020_name": "Goldsmith",
         "Date_x0020_of_x0020_birth": "1964-11-23",
         "works_x0020_for": [
            {"@id": "ORG-7"}
         ]
      }
   ]
}

Data structure for providing data to an external application

The Providing method should be used to retrieve data from Relatics by an external application. The code below shows the structure that Relatics returns:

{
   "TypeElementPlural": [
      {
         "@Id": "Relatics id",
         "@DisplayName": "Value"
      },
      ...
   ]
}

Notes:

• The response is limited to the ID and display name of the elements.
• Characters that are not letters or numbers in JSON names are escaped. See the section below for further details.

Example of the JSON data:

{
   "Persons": [
      {
         "@Id": "PER-1",
         "@DisplayName": "Konnor Carney"
      },
      {
         "@Id": "PER-6",
         "@DisplayName": "Ace Whitney"
      }
   ]
}

Escape non-letter or number characters

When one of the following characters is used in the TypeElementPlural, PropertyName, or RolName, the representing escape characters must replace this character: