To illustrate the procedure to create a basic ServiceNow connection, the following example is used.
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:
- 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:
- In the Create pane, click the ServiceNow connection
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.
- When you are ready, close the settings window.
Defining mappings
After the connection has been created, one or more mappings must be defined.
- In the connection view, select the ServiceNow connection object, and then click
The new mapping is placed in the connection object. to add a mapping. - Name the mapping. Give it a name that reflects the information that is exchanged.
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.
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.
- 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. - Click in the title bar of the table, and then click
- 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.
- 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. - Optional: In Query you can enter a query to specify a constraint on the records to be retrieved.
- 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.
- 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.
to set the ServiceNow table properties. - 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.
- 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. - Make each column in the table represent a table column in ServiceNow:
- Select a column, and click
- 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. - When you are ready, close the properties window.
- Select a column, and click
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.
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:
- 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. - 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:
- Click the object type, and then click the
- On the General tab next to Include children, click the check mark
- Click the object type, and then click the
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).
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.
- 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:
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.
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.
- Select the meta-element or a property in the meta-element, and draw a mapping relation
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.
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 lay out the mapping relations.
control on a selected relation toCreating link relations
Metaobjects and metarelations are connected via a link relation.
For the example connection, link relations between the metaobjects and the metarelation are created.
- Select the metaobject that must be linked to the "from" connector (endpoint) of the metarelation, and draw a link relation
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.
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.
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".
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:
- Select a mapping relation, and then click
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.- When you are ready, close the settings window. Your ServiceNow connection is now completed.
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.