Push Integration Mechanism

The components responsible for the ServiceNow integration are bundled in the ServiceNow Integration package, SNOWGenericAdapter.zip.

The adapter receives the CI and relationship data sent from UCMDB server and transfers this data to ServiceNow using either SOAP or JSONv2 connector. For more details about the connectors, see Connectors.

The ServiceNow enhanced generic adapter can push the CIs and relations both directly or via import sets. However, since the ServiceNow coalescing (CI Reconciliation) mechanism is not available for the direct table approach import sets are the preferred way of pushing data to ServiceNow. The information about the ServiceNow tables to insert the data into as well as the record fields to insert into the tables is specified in mapping files.

Consider the following example from the mapping file:

<target_entities>
    <source_instance query-name="SNOW Windows Push 1.0" root-element-name="Root">
        <target_entity name="ucmdb_integ_ci_win_server">
            <target_mapping datatype="STRING" name="correlation_id" value="Root['global_id']"/>
            <target_mapping datatype="STRING" name="name" value="Root['display_label']"/>
            ...
            <for-each-source-entity count-index="i" source-entities="Root.FileSystem">
                <target_entity name="ucmdb_integ_ci_file_system">
                    <target_mapping datatype="STRING" name="correlation_id" value="Root.FileSystem[i]['global_id']"/>
                    <target_mapping datatype="STRING" name="name" value="Root.FileSystem[i]['display_label']"/>
                    <target_mapping datatype="STRING" name="computer" value="Root['global_id']"/>
                </target_entity>
            </for-each-source-entity>
        </target_entity>
        ...
    </source_instance>
</target_entities>

In this example the adapter will insert a record with the fields name and correlation_id into the staging table ucmdb_integ_ci_win_server.

Note that when pushing data to ServiceNow via import sets, there are some mandatory fields that need to be specified on both CIs and relations:

1. Each CI must have the correlation_id (or custom ServiceNow field) property set. The reconciliation is done on this field on ServiceNow side. If it does not have this property set, then it is ignored by the push job. See CI Reconciliation. Furthermore, this field needs to be set to UCMDB CI global_id.
2. Each child CI must have the corresponding ServiceNow child-parent relation field set to the parent UCMDB CI global_id. When we do that the adapter finds this field in the push job and replaces its value with ServiceNow parent CI sys_id before it sends it to ServiceNow. In the example above the child entity ucmdb_integ_ci_file_system has the computer field set to the global_id value of the parent entity ucmdb_integ_ci_win_server.

3. Each relation must have parent and child properties set. If it does not have these properties set, then it is ignored by the push job. See CI Reconciliation.

4. While the mapping is done from UCMDB CI to ServiceNow staging table, the deleted UCMDB CIs need to be deleted from ServiceNow target table. The adapter tries to find the staging table to target table mapping in ServiceNowConfig.xml Configuration, so the additional mapping needs to be defined there.

The integration mechanism is explained in Developer Reference section of the UCMDB Help.