XML format for providing and synchronizing data using interfaces

XML format for providing and synchronizing data using interfaces

Interfaces require a fixed data structure. This article describes the structure of the xml 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:

<elements>
    <Type_element_plural>
        <Type_element_name externalid="value">
            <Property_name>value</Property_name>
            <Property_name>value</Property_name>
            ...
            <Role_name>
                <Target_Type_element_name id="element ID" />
                <Target_Type_element_name id="element ID" />
                ...
            </Role_name>
        </Type_element_name>
        ...
    </Type_element_plural>
</elements>

Notes:

  • The italic texts should be replaced by data representing your SE model in Relatics.
  • Every XML element <Type_element_name> must contain the XML attribute “externalid” which should be populated with a unique value. When an update is presented, Relatics uses the “externalid” to determine if an element needs to be created, updated, or deleted.
  • The attribute “externalid” allows a value with a maximum length of 450 characters.
  • The values of the XML 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.
  • Be mindful of the cardinality when providing elements for a relation.
  • Characters in XML element names that are not letters or numbers must be escaped. See the section below for further details.
  • Elements not supplied in the request body will be deleted.

Example:

<elements>
    <persons>
        <person externalid="43530759">
            <first_x0020_name>Ace</first_x0020_name>
            <last_x0020_name>Whitney</last_x0020_name>
            <date_x0020_of_x0020_birth>1980-04-09</date_x0020_of_x0020_birth>
            <works_x0020_for>
               <organization id="ORG-1" />
            </works_x0020_for>
        </person>
        <person externalid="d390874b">
            <first_x0020_name>Diogo</first_x0020_name>
            <last_x0020_name>Goldsmith</last_x0020_name>
            <date_x0020_of_x0020_birth>1964-11-23</date_x0020_of_x0020_birth>
            <works_x0020_for>
                <organization id="ORG-7" />
            </works_x0020_for>
        </person>
    </persons>
</elements>

Data structure for providing data to an external application

The providing method is used to retrieve data from Relatics by an external application. The code below shows the structure that Relatics returns.

<elements>
    <Type_element_plural>
        <Type_element_name id="element ID" displayname="Value" />
        <Type_element_name id="element ID" displayname="Value" />
        ...
    </Type_element_plural>
</elements>

Notes:

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

Example:

<elements>
    <documents_x0020__x0028_external_x0029_>
        <document_x0020__x0028_external_x0029_ id="DOC-2" displayname="file_example_XLS_10.xls" />
        <document_x0020__x0028_external_x0029_ id="DOC-3" displayname="file_sample_500kB.rtf" />
        <document_x0020__x0028_external_x0029_ id="DOC-4" displayname="file_example_JPG_1MB.jpg" />
    </documents_x0020__x0028_external_x0029_>
</elements>

Escape non-letter or number characters

When one of the following characters is used in the Type_element_plural, Type_element_name, Property_name, or Role_name, the representing escape characters must replace this character:

Character Escape character
& _x0026_
_x002D_
( _x0028_
) _x0029_
, _x002C_
[space] _x0020_

Request a demo

Fill in our form and one of our colleagues will contact you as soon as possible to schedule a demo.

Please enable JavaScript in your browser to complete this form.
Please enable JavaScript in your browser to complete this form.

Download the whitepaper

Please enable JavaScript in your browser to complete this form.
Addresss

Get in touch

Fill in our form and one of the Relatics members will contact you as soon as possible. Do you prefer contact by phone? Please call us at +31 180 413 047.
Please enable JavaScript in your browser to complete this form.