Upsert Truth Records

This task will insert or update records in the truth table (as seen on the 'Data' tab) to an XML file. The truth table maps the ID numbers of records imported using Zynk between two systems. The 'Internal ID' is usually the ID of the record in Sage, and the external ID is the ID of the matching record from an external system such as a website or e-commerce platform. Note: the truth table is automatically populated when importing data into Sage, so this task is only required when not importing data into Sage.

For more detailed information on the truth table please visit the Truth Database page.

Settings

Collection

Optional
The XPath query to use to access the collection value of each record. This should be relative to the query used in the XPath setting.

If left blank, the collection specified in the Default Collection setting will be used instead.

The value will be used for matching existing truth records. When creating a new truth record, the value will be written to the collection field.

External ID

Required
The XPath query to use to access the external ID value of each record. This should be relative to the query used in the XPath setting.

Depending on the Match On setting, this value will either be used for matching existing truth records, or will be written to the external ID field when creating or updating the truth record.

Internal ID

Required
The XPath query to use to access the internal ID value of each record. This should be relative to the query used in the XPath setting.

Depending on the Match On setting, this value will either be used for matching existing truth records, or will be written to the internal ID field when creating or updating the truth record.

Truth Record ID

Dependant
The XPath query to use to access the truth record ID value for each record. This should be relative to the query used in the XPath setting.

This setting is required when the Match On setting is set to 'Truth Record ID'. In this scenario, the value will be used to find the truth record to update.

Type

Optional
The XPath query to use to access the type value of each record. This should be relative to the query used in the XPath setting.

If left blank, the type specified in the Default Type setting will be used instead.

The value will be used for matching existing truth records. When creating a new truth record, the value will be written to the type field.

XPath

Required
The XPath query to use to access each record in the input file.

Default Collection

Optional
The default collection value to use when matching existing and creating new truth of records. This setting is blank by default, which means the task will match truth records where the collection field is empty.

This value will be overridden if the Collection setting is used, and a matching value is found in the input file.

Default Type

Required
The type of records to create/update in the truth table. Defaults to 'Zynk.Connect.Objects.Contact'.

This value will be overridden if the Type setting is used, and a matching value is found in the input file.

Input File

Required
The XML file containing the data to insert or update in the truth table. The data can be stored in any format, the task will read the internal and external IDs based on the XPath settings.

Match On

Required
Select the field to use to match existing truth records. The following options are available:

  • InternalId - Match records based on the value in the InternalId field in the Truth Database and the value obtained via the Internal ID setting. If a match is found, the external ID of existing record will be updated. If not, a new truth record will be created.
  • ExternalId - Match records based on the value in the ExternalId field in the Truth Database and the value obtained via the External ID setting. If a match is found, the internal ID of existing record will be updated. If not, a new truth record will be created.
  • TruthRecordId - Match records based on the value in the Id field in the Truth Database and the value obtained via the Truth Record ID setting. When this option is selected, you can only update existing truth records. Both the internal ID and external ID will be updated.

Workflow ID

Optional
The ID of the workflow to export truth records for. You can view the ID of a workflow from the 'Properties' tab, under 'Workflow Settings'.

If left blank, the task will create/update truth records for the workflow it belongs to.

Zynk Settings

See Common Task Settings

Examples

Sample input file, showing a customer:

<?xml version="1.0"?>
<Customers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Customer>
        <id>1</id>
        <firstname>John</firstname>
        <lastname>Smith</lastname>
        <account_ref>JOHN001</account_ref>
        <email>[email protected]</email>
        <default_billing_address>
            <company>Zynk Software</company>
            <street1>Nelson House</street1>
            <street2>Fleming Business Centre</street2>
            <city>Jesmond</city>
            <region>Tyne and Wear</region>
            <country_id>GB</country_id>
            <postcode>NE2 3AE</postcode>
        </default_billing_address>
    </Customer>
</Customers>

Based on this file, the tasks settings would be set as follows: