Import Sets

NOTE: See ServiceNow wiki: import sets for information on creating import set tables in the ServiceNow database.

Contents

1 Roles
2 Using import sets in Apps
- 2.1 Import set mapping example
3 Transform scripts
4 Copy all values
5 Copy Null values
6 Attachments and signatures
7 Audit history records
8 Errors
- 8.1 Import set errors
- 8.2 Transform map errors

Roles

If the user does not have administrative privileges, the following role is required before the user can insert records into import sets:

import_transformer

Using import sets in Apps

The use of import sets in Mobile Reach Apps depends on the task performed by your App.

Write-only: The App creates new records only. Records are not downloaded and displayed on the device. When the new records are uploaded to the ServiceNow database, they are written to an import set. After upload, all additional transactions depend on the configuration of the import set in ServiceNow.
In this situation, use the import set table created in ServiceNow in your App as you would any database table. No additional configuration is required.
Read from a table and write to an import set: The App downloads records from a database table to the device, but writes new or updated records to an import set. New records are inserted into the import set table. Changes to a record are inserted into the import set along with any ‘coalesce’ values from the original record, which allows the import set to update the correct base table records.
In this situation, add the following attribute to the TABLE entry for the base table in the ServiceNow.xml file:

importset="<value>"

This attribute causes the Gateway to map the database table to the import set. The Gateway creates a record in the import set. Transform map(s) in the ServiceNow database then create/update the record(s) in the base table(s).

NOTE: If you are using multiple tables, you must combine the tables into a view and map that view to the import set.

Import set mapping example

You have two base tables (test_table_1 and test_table_2) in the ServiceNow database with a reference link between them. The tables are combined into a view (test_view).

An import set table (import_set_table) and two transform maps are created in the ServiceNow database. Each transform map associates fields from import_set_table to fields in one of the base tables.

The ServiceNow.xml file is used to create a link between test_view and import_set_table.

test_view displays in the Form dropdown lists in AppStudio and is used when configuring the App, just as any view would be. When a new/updated record is uploaded from the device, the Gateway uses the values configured in the ServiceNow.xml file to send values to import_set_table, which then uses the transform maps to update the correct fields in test_table_1 and test_table_2.

Map the import set to the table or view used in your App by adding attributes to the TABLE entry in the ServiceNow.xml file:
<TABLE name="test_view" importset="import_set_table"/>

Transform scripts

If you are using transform scripts to perform the transform operation, mapping between the import set and the base tables must be explicitly configured with FIELD entries in the ServiceNow.xml file.

The following example maps fields test_assetid and test_ownedby in view test_view to fields assetid and owner in import set import_set_table. Field test_assetid is a coalesce field.

<TABLE name="test_view" importset="import_set_table">

      <FIELD name="test_assetid" writename="assetid" coalesce="1"/>

      <FIELD name="test_ownedby" writename="owner"/>

</TABLE>

Copy all values

By default, only new records or changed values in existing records are copied from import sets to the base tables. To copy all values in an existing record, instead of just the changed values, add the following attribute to the TABLE element for the import set table in the ServiceNow.xml file:
importsetcopyall="1"
Example:

<TABLE name="u_import_copy" importset="u_import_copy_set" importsetcopyall="1"/>

Copy Null values

If your import set App changes one or more fields from having a value to being blank, you must configure your ServiceNow.xml file to copy the blank values to the base table.

The simplest and recommended method is to add the importsetcopyall="1" as described above.

If you don’t want to copy all values, perform the following to copy the null values:

Add an onBefore script to your transform map that calls the following:
new MRSupport().FixNull (source);
For any reference or choice field that will be set to NULL:
- Remove the field from the transform map.
- In the transform map script, add a line that will map the NULL value.
  target.<field name in base table> = MRSupport.FixNullRef (source,'<field name in import set table>');
  In this example, u_user is the field name in the base table and u_u1 is the field name in the import set table.
  
  target.u_user = MRSupport.FixNullRef (source,'u_u1');
- In the ServiceNow.xml file, add a writename attribute to the FIELD that will be changed to the null value.
  <FIELD name='u_user' writename='u_u1'/>

Attachments and signatures

Attachments and signatures can be used with import set records. Configuration varies, depending on the method used to process the import sets.

Read from a table and write to an import set: If your App reads from a database table and writes to an import set, additional configuration to support attachments and signatures with import sets is not necessary. Configure your App with the same methods that would be used to read and write directly to the base table. See Attachments and Signatures for more information.
Write-only: If your App only writes records directly to an import set, in addition to the usual configuratation requirements for Attachments and Signatures, add the following attributes to the TABLE element for the import set table in your ServiceNow.xml file.
- attach_table: Name of the base table where the attachments will be sent
- attach_key: Name of the field in the import set record that contains the sys_id of the base table record that will receive the attachments

Audit history records

To get audit history records when using import sets, check the Run Business Rules checkbox in the ServiceNow database. See this ServiceNow community thread for more information.

Errors

Errors can occur at two points when uploading new or changed records to an import set:

When the record is inserted into the import set
When the record is processed by the transform map

Import set errors

Errors that occurs when a record is inserted into an import set are processed like errors that occur when inserting a record into a database table. The record is flagged with an error icon (), and the text of the error is displayed on the error message tab in the RecView. The record does not insert into the table.

Transform map errors

Errors can be generated by the transform map after the record has been inserted into the import set table. When a transform map error occurs, the record will display in the import set table, but an error message will be generated by the transform map. The text in the error message can be configured in the transform map script.

The Mobile Reach Gateway reports the transform map error as a failed insert on the client device. The record will be flagged as an error with the icon, but the error message will show the text contained in the transform map script.