Support

Skip to end of metadata
Go to start of metadata

Expand/Collapse All

To illustrate the procedure to create a basic ServiceNow connection, the following example is used.

Example

You want to exchange model information between Enterprise Studio and ServiceNow about projects (modeled as work packages), their start and end date, and the managers (modeled as business actors) of the projects.

To realize the information exchange, the following connection can be created:


The following is done to create the connection:

  • Add a ServiceNow connection as basis for the mapping.
  • Define a mapping with two linked tables.
  • Define the ServiceNow tables and their columns by configuring the mapping tables. One table for the work packages with their start date, end date, and manager, and one table for the business actors.
  • Define the model data on the Enterprise Studio side by adding metaobjects and their properties.
  • Map the model data from the tool side to the ServiceNow table by creating relations between the model elements and the mapping tables, including a connection between the two mapping tables.

  • Specify the mapping properties for import and/or export.

There is no prescribed order in which the table and the meta-elements of a mapping should be configured to create the mapping. The preferred order may depend on what you want to use the connection for.

If you use it for import, you may prefer to start with the table, since you have ServiceNow tables as starting point. If you want to export, you may prefer to start with the model data from the tool side by adding the meta-elements.


On this page:


Adding a connection

To add a new ServiceNow connection to your Connection model, follow these steps:

  1. In the Create pane, click the ServiceNow connection , click in the open connection view, and type the name of the new connection.



  2. Select the connection object, and then click  to set the connection properties. Options with a check mark  are activated, options with a cross  are deactivated. Click the check mark or cross to change the status.



     Model context

    Select the model (element) in the model package hierarchy that should act as root for looking up and creating objects in the context of this connection.

     Server URL

    Enter the URL of the REST API of your ServiceNow instance.

     Enable delete setting

    If activated, the Remove setting at the mapping relation properties for import and export will be enabled. By default, this setting is disabled to prevent users from accidentally activating it. If the setting is activated, elements that no longer exist on one side of a mapping can be deleted on the other side during import or export.

     Logging

    If activated, a log file with feedback about the export or import is created. The log file will be placed in the specified log file location.

     Log file location

    Specify the location where the log file must be stored. A log file is only generated if the Logging option is activated.

     Validate before import

    By default, the connection is first validated before the import is executed, to ensure that the connection is correct and that the right data is imported. If a connection has already been validated and has not been changed after that, the option can be deactivated to speed up the import.

     Validate before export

    By default, the connection is first validated before the export is executed, to ensure that the connection is correct and that the right data is exported. If a connection has already been validated and has not been changed after that, the option can be deactivated to speed up the export.

     Dry run

    If activated, a dry run of the import or export will be performed rather than the actual import or export, meaning that no actual changes will be made. The dry run report provides an overview of the changes that will take place in an actual import or export.

     Dry run report location

    Specify the location where the dry run report must be stored. A report is only generated if the Dry run option is activated.

  3. When you are ready, close the settings window.

Defining mappings

After the connection has been created, one or more mappings must be defined.

  1. In the connection view, select the ServiceNow connection object, and then click  to add a mapping.

    The new mapping is placed in the connection object.

  2. Name the mapping. Give it a name that reflects the information that is exchanged.

Example

For the example connection, the result is a connection with one mapping: 


Configuring tables

Next step is configuring the tables to correctly represent the ServiceNow tables you want import data from or export data to. Do this for each mapping you have added, and for each table in a mapping.

Example

For the example connection, two tables are configured in the mapping. Two tables are needed because the managers of the projects cannot directly be mapped between the metaobject representing the projects (work packages) in the model, and the managers in the ServiceNow table because of a type difference. Therefore, an additional table is needed for the mapping to connect the data. This will become clear later on in the process.

  1. Double-click the mapping. A new diagram opens containing one empty mapping table.



    One table represents one ServiceNow table.

    To add additional tables, click  in the Create pane, and then click in the diagram.

  2. Click in the title bar of the table, and then click  to set the ServiceNow table properties.



    1. In Server URL, enter the URL of your ServiceNow instance. The Table API URL is already filled. It is the path name to access the table API. Change it only if needed.

    2. Type the internal name of the ServiceNow table in Table name, or type its display name in Table label, and then click the check mark next to the box to locate the table on the server.

      If you have not previously activated the option to remember your credentials since opening the model package, a window appears first, asking for your credentials for ServiceNow. Enter your credentials and click OK.

      If the check mark turns green, the column is found, and the other value will be filled too. If not, the check mark turns red. Check for the correct table name, change it if needed and click the check mark again.

    3. Optional: In Query you can enter a query to specify a constraint on the records to be retrieved.

    4. Optional: During an import or export, records are transferred in batches of 200 at a time, until all records have been transferred. This number is the default Pagination limit. Usually, you will not need to change this value, but for performance reasons you can enter a lower number, in order to decrease the size of the batches.

    5. Close the settings window when you are ready.

    Once the settings have been specified, a URL is generated and displayed in URL in the table properties window. It can be clicked to retrieve the contents of the ServiceNow table and view it.

  3. Determine the number of needed columns for the ServiceNow table, and add additional columns. To do this, select a table column, and then click the plus sign on the left or right side to add a column to the left or the right.



    The total number of columns must equal the number of relations you want to create between the model data and the mapping table. In the end each table column must have a mapping relation attached.

  4. Make each column in the table represent a table column in ServiceNow:

    1. Select a column, and click . The Column properties window appears.



    2. Type the internal name of the ServiceNow table column in Column name, or type the display name in Column label, and then click the check mark next to the box to locate the table column on the server.

      Type       is automatically set after locating the table. It is the data type of the column.

    3. When you are ready, close the properties window.

Example

For the example connection, the result of configuring tables is a table "BiZZ Projects" with 5 columns, and a table "BIZZ Actors" with two columns. The "manager" column in the "BiZZ Projects" table will be used to connect both tables. 


Adding metaobjects and metarelations

Next step is adding metaobjects and metarelations to define the model data from Enterprise Studio that must be mapped to the ServiceNow tables. Usually, one metaobject or metarelation is added per table. 

After adding the meta-elements, properties may need to be added to the meta-elements if the mapping tables contain defined properties.

Example

For the example connection, one metaobject is added to the "BiZZ Projects" table, and one metaobject to the "BiZZ Actors" table. One metarelation is added that will be used in the connection between both tables.

Additionally, properties are added to both metaobjects because both associated tables have defined properties.

Adding a meta-element

To add a metaobject or metarelation to a mapping, follow these steps:

  1. In the model browser, select a model object or relation of the type you want to add to the mapping, and drag it onto the diagram. It can be any object or relation.

    A metaobject or metarelation is placed on the diagram. It has the name of the element type of the selected element. In the figure below a metaobject representing work packages is added by dragging a work package.



    Alternatively you can add a meta-element by using the Create pane or the quick-create pop-up window.

  2. Only for metaobjects, optional: By default, any children of an object of the selected object type will automatically be included in an import or export. If you do not want any child elements to be included, do as follows:

    1. Click the object type, and then click the  control.

    2. On the General tab next to Include children, click the check mark  to deactivate the option. The check mark will turn into a red cross.

Adding meta-element properties

If one or more columns in the table represent object or relation properties, these properties also need to be added to the metaobject or metarelation in order to be mapped to the table columns.

An attribute that contains object references or a collection of object references cannot be mapped directly onto a table column. The type of object that is referred to should be modeled as well in a separate table (or metaobject).

Example

In case of the example connection, properties are added to both metaobjects to be mapped onto the table columns.

The "manager" attribute of a work package cannot directly be mapped onto the "manager"column of the "BiZZ Projects" table. Therefore, no property is added to the "Work package" metaobject to map to the "manager" column. The "manager" column will later on be mapped onto the "BiZZ Actors" table via the metarelation.

To add a property to a meta-element, do as follows:

  • Select the meta-element, and then click the control of the type of property you want to add. If needed, add multiple properties.

attribute 

Add an attribute. In the selection window that appears, select one or more attributes and click OK. Example:



metric 

Add a metric. Metrics are used to describe numerical properties of objects. In contrast to attributes metrics can be added to a model, whereas attributes have to be introduced in the tool configuration. 

In the selection window that appears, select a metric from the model package and click OK. Example:



metadata

Add metadata. Two types of metadata are available: ID and type name of the element. Metadata can be exported and can (only) be used for matching during import. This is because type name and ID cannot be changed for existing objects. For more information about using metadata as property, see Using metadata as meta-element property.

In the metadata selection window, select the desired metadata type, and click OK. Example:



tag

Add a tagged value. A tagged value represents some data that is linked (tagged) to an object. Tagged values are meant for advanced usage such as complex viewpoints (scripts) or complex import scenarios, but can also be used for properties that are not of interest to the end-user, but which are used for matching existing elements from earlier imports or exports. A typical example is the ServiceNow sys_id.

Tagged values should typically not be used to model properties of an object, metrics and attributes are used for this. More information about using tagged values can be found in the BiZZdesign Scripting Reference.

After clicking the control, type the name of the tag, and click OK. Example:


Example

For the example connection, adding metaobjects and metarelations and adding properties to them has resulted in the following:


Creating relations between the mapping elements

Now, relations must be created between the model data and the tables in the diagram for the actual mapping of the data. The mapping relation is used for this.

The link relation is used for connecting metarelations and metaobjects. The reference relation is used for modeling object references.

Which relations you need to create, depends on your mapping. In the end, each column in each mapping table must have a relation attached.

Creating mapping relations

In a mapping, the meta-element is linked to the table column representing the element type, and the meta-element properties are linked to the columns representing the properties.

Example

For the example connection, mapping relations between the mapping tables and their associated metaobject and its properties are created, and a mapping relation between the metarelation and the reference relation.

To create a mapping relation, do as follows:

  • Select the meta-element or a property in the meta-element, and draw a mapping relation  to the table column representing the element type or property.


Create a mapping relation for all meta-elements and properties in each mapping. Make sure that in the end each table column or cell has a mapping relation attached.

Example

For the example connection, the mapping relation from the metarelation cannot be drawn yet. Since the metarelation needs to be connected with the reference relation between the tables, an object reference needs to be created first. After that the mapping relation can be added.


Relation lines are automatically laid out optimally when connecting the components. That is default behavior for modeling a mapping. In case a relation does not have the optimal layout, use the  control on a selected relation to lay out the mapping relations.

Creating link relations

Metaobjects and metarelations are connected via a link relation. 

Example

For the example connection, link relations between the metaobjects and the metarelation are created.

To create a link relation, do as follows:

  • Select the metaobject that must be linked to the "from" connector (endpoint) of the metarelation, and draw a link relation  between the metaobject and the metarelation connector.



Do the same for the other metaobject and the "to" connector of the metarelation.

Modeling object references

Only if you have multiple tables in your connection, you need to model object references in order to connect data from the different tables. This is done by creating reference relations.

Example

For the example connection, a reference needs to be created between the "manager" column of the "BiZZ Projects" table and the "BiZZ Actors" table, because in ServiceNow the corresponding column "manager" is a reference to a different table ("BiZZ Actors"), which contains information that is mapped onto a business actor. Both references should be modeled explicitly with a reference relation.

To create a reference relation, do as follows:

  • Select the table column with the reference that must mapped onto the other table, and draw a reference relation  between the column and the other table.

    To see if a table column represents a reference, click the column, and open its properties window. The property Internal type must be "Reference".

Example

For the example connection, the result of creating the different relations looks as follows. Take note that the "manager" column of table "BiZZ Projects" is now also mapped to the assignment metarelation using a mapping relation. It could only be done after the object reference had been created. 


Organizing the mapping

Your mapping may not look as organized as the example above; the relations and connectors are probably positioned differently.

In order to make your mapping look more organized, reposition one or more relations in the mapping and relocate the "from" and "to" connectors of the metarelation.

Specifying mapping properties for import and export

Once mapping relations have been created, their properties must be specified for import and/or export. For each mapping relation in your connection mapping(s), specify the mapping properties that are relevant to your use of the connection. 

Depending on what you are going to use the connection for, specify the settings for import or export, or for both. Below are examples of the import and export options for a mapping relation. Which options are available in the window depends on the mapping relation.


 

Import options


Export options


To specify the properties for a mapping relation, follow these steps:

  1. Select a mapping relation, and then click  on the relation line. The settings window pops up.

  2. Click the Import tab or the Export tab to specify the settings.

    The presence of an option in a mapping relation and its default setting depends on the components the mapping relation is attached to.

     Use for identification

    If activated, the element type or property attached to the mapping relation is used to identify the related object on import or export. If attached to an element type, identification is done on the element's name. In case of a property, it is the property's value. This implies that the value of this type or property cannot be changed on import/export. 

    If activated for import, a dot  is shown at the end of the mapping relation at the side of the meta-element or property. If activated for export, a dot is shown at the side of the ServiceNow column.

    If deactivated, there is no matching, so the value can change on import/export. If replacement has been deactivated (Replace option), and the Add option has been activated, and there is no matching, export will create duplicate records in the ServiceNow table. Import will create duplicate objects in your model.

     Add

    If activated, a new model object is created if no match is found on import or export. Deactivate this option, if you do not want this to happen.

     Replace

    If activated for import, the value of the property in the model may be replaced by the imported value. If activated for export, the value of the property in the ServiceNow table may be replaced by the exported value. Deactivate the option if replacement of a value is not allowed.

     Remove

    Can only be activated if Enable delete setting at the general connection settings has been activated.

    In a mapping relation between a meta-element and a table column: if activated, the relation will be removed if the import or export does not define a relation between two endpoints. If deactivated, the relation will not be removed.

    In a mapping relation between a meta-element property and a table column: if activated, non-mandatory values will be reset (made "undefined") during import if the associated cells in the ServiceNow table are empty.

     Model context for looking up objects

    By default, the model context specified at the general connection settings is searched to find a match for imported objects and relations. If you want to use a different model context for this mapping, click in the box and select the model (element) in the model package that should be searched. This context overrides the general connection setting.

     Model context for creating objects

    By default, the model context specified at the general connection settings is used to create objects that could not be matched on import (Add option). If you want to use a different model context for this mapping, click in the box and select the model (element) in the model package that should be used. This context overrides the general connection setting.

     Model context containing objects to export

    By default, objects from the model context specified at the general connection settings are exported. If you want to use a different model context for this mapping, click in the box and select the model (element) that should be used for exporting objects. This context overrides the general connection setting.

     Import display value

    When importing data, both the display values and actual values for the entire data set are fetched. By default, only the actual values are imported into the model in Enterprise Studio. Select this option if you also want to import the display value.

     Export default values

    Objects, relations have a default name when added to the model. Element properties also have a default value. If the option is activated, elements without a user-defined name, or properties without a user-defined value will be exported. If deactivated, default names and values will not be exported.

     Mapping script

    If you have a mapping script available for processing imported or exported values, you can specify it here. Click in the box and select the script. Upon import/export, the mapping script is invoked to process the imported/exported values. This script should be defined as a viewpoint.

     Synchronize 'sys_id' property

    This option is only available for export on a tagged value property of a metaobject.

    ServiceNow automatically creates sys ID's for the records in its tables. For a successful export of model information from Enterprise Studio to ServiceNow, the objects in your model will also need these sys ID's. They can be provided by ServiceNow via the option. Activating the option can be useful in the following situations:

    • Matching objects is unsuccessful upon export, but the objects are added to ServiceNow (Add option activated). Activate the option to make sure that next time matching will succeed. If activated, the sys ID's created by ServiceNow will be added to your model upon export, so that next time identification of the objects can be successful based on the sys ID's. If deactivated, the objects will not be exported.
    • Matching is successful, but the sys ID is not part of the identifying criteria for export (option Use for identification is deactivated). If you activate the option, the sys ID's from ServiceNow will be added to your model, and the records in ServiceNow will be updated. If deactivated, the records in ServiceNow will not be updated.
  3. When you are ready, close the settings window. Your ServiceNow connection is now completed.

Example

The end result of the example connection shows that two mapping relations are used for identification, for import as well as export, indicated by the dots at both ends of the mapping relation lines.