Skip to main content
Language Selector

  1. Other Languages

    (machine translation)

Planview Customer Success Center

barometerIT-to-ServiceNow Adapter

  1. Last updated
  2. Save as PDF

Introduction

What is the ServiceNow Adapter?

The barometerIT to ServiceNow Adapter is a real-time synchronization from barometerIT to ServiceNow. (The adapter is presently unidirectional.)

The adapter includes two major feature sets:

  • a one-time bulk-load to bootstrap an implementation
  • an ongoing, event-driven, real-time ("as it happens") synchronization of fine-grained changes

Implementation occurs in three steps:

  1. Setup involves some relatively light-weight configuration.
  2. Once setup is complete, the data from barometerIT is bulk-loaded into your ServiceNow instance.
  3. After the initial bulk load, all changes to entities in barometerIT will be reflected in ServiceNow in real time.

Any barometerIT Catalog is eligible to be synchronized. Furthermore, the adapter publishes:

  • standard fields (e.g. System Type or Capability Domain)
  • custom fields

With respect to relationships:

  • Any relationship between two Catalogs is eligible to be synchronized.

Concepts

The barometerIT-to-ServiceNow Adapter is a module hosted by barometerIT in the barometerIT cloud environments. It is an internal event-listener that knows how to prepare payloads to send to ServiceNow, and how to connect to ServiceNow endpoints. Keep in mind that this adapter knows how to do half the job of preparing data for ServiceNow. It is expected that you will do some setup in ServiceNow in order to get that data into your (likely customized) tables.

The adapter works according to the same principles as Webhooks (another integration facility in barometerIT). Webhooks are a common "HTTP callback" integration convention. General documentation on this paradigm is easy to find (via Internet search).

As with Webhook behavior, the adapter makes HTTP calls as a reaction to certain events in barometerIT. Your "callback" for these events is a RESTful HTTP endpoint on your ServiceNow instance. The adapter uses ServiceNow's REST API services to synchronize barometerIT entities into ServiceNow. 

Once the payload of a barometerIT call hits your ServiceNow endpoint, the data is first staged in ServiceNow Import Sets. Then one or more ServiceNow Transform Maps are used to copy the imported rows from the Import Sets to the Configuration Item tables. (It is common for ServiceNow customers to customize their own implementations. Therefore we expect that much of the inbound data my be written to non-standard schemas.)

In barometerIT, some users may not have rights to edit entities, only to propose changes which would later be approved by a different user. The adapter will always push actual or approved changes to entities in barometerIT, but may optionally configured to also push proposed changes.

Barometer Setup

Create the Endpoint in barometerIT

  1. Obtain the URL for your ServiceNow instance. In the ServiceNow console, open the REST API Explorer and note the URL
  2. Sign into barometerIT using a user that has the Settings Administrator Role.
  3. Create a new Endpoint for the ServiceNow Adapter.
  4. Enter the URL from step 1 for Endpoint URL.
  5. Select the Entity Types to be synced with ServiceNow.
  6. Select the Relationship Types to be synced with ServiceNow.
  7. Choose Yes or No for Synchronize Proposed Changes depending on whether the adapter should send proposed changes to ServiceNow.
  8. Choose Yes or No for Handle Connections as Relationships depending on whether the adapter should treat Connections as relationships in ServiceNow (see Handle Connections as Relationships below).
  9. Chose Yes or No for Send relationships when entities become workflowed depending on whether the adapter should send an entity along with all of its relationships or just the entity upon the event of it being workflowed. [This feature will be available in release 86.]
  10. (Optional) Enter the Fieldset BN and Field BN obtained below (in Create a Custom Field in barometerIT).
  11. Select Basic for Auth Type.
  12. Enter the username and password for the ServiceNow import user created above.
  13. Select Yes for Enabled.

Screen Shot 2018-12-03 at 3.15.09 PM.png

Create a Custom Field in barometerIT (optional)

For each entity synchronized to ServiceNow, barometerIT can store the ServiceNow unique identifier (sys_id) for that record. The result is that all records representing entity updates and relationships pushed to ServiceNow will have the sys_id as part of the request. To enable sys_ids to be pushed across, follow these steps:

  1. Create a Custom Field called ServiceNow ID of type Text and display type Text Box. Copy the Barometer Number of the field (it's the 12-character text at the end of the URL) and enter it into the Fieldset BN field in the adapter configuration.
  2. Create a Fieldset called ServiceNow and add the field ServiceNow ID. Copy the Barometer Number of the fieldset (again the 12-character text at the end of the URL) and enter it into the Field BN field in the adapter configuration.
  3. Go to Field Set Locations and add Fieldset ServiceNow to every entity that is being synced with ServiceNow.

ServiceNow Setup

Create a user for the import

In ServiceNow, create a user for the import and assign the "import_admin" and "asset" roles to the user.

Identify the ServiceNow tables that correspond to barometerIT Catalogs

All Catalogs may be synchronized from barometerIT to ServiceNow:

  • Actor
  • Capability
  • Company
  • Connection
  • Data
  • Demand
  • Deployment
  • Market
  • Organization
  • Person
  • Product
  • Skill
  • Strategy
  • System
  • Technology

In addition, relationships between any two Catalogs may be synchronized from barometerIT to ServiceNow.

A typical mapping from barometerIT to ServiceNow would look like:

  • System → Application (cmdb_ci_appl)
  • Capability → Business Service (cmdb_ci_service)
  • Technology → Software Model (cmdb_software_product_model)

Relationships (aka "associations") between barometerIT objects are synchronized to create relationships in ServiceNow:

  • System-System relationship → CI Relationship (cmdb_rel_ci)

Identify the barometerIT fields to write to ServiceNow

All built-in fields can be mapped to ServiceNow tables. To see the list of fields and their field IDs exported, click View ServiceNow request fields at the bottom of the ServiceNow Adapter Endpoint configuration screen in barometerIT.

           

NOTE

For mapped barometerIT custom fields, the names of the columns in the ServiceNow import sets will correspond to the Field Ids of those custom fields. However, ServiceNow does not handle all special characters as expected, and it also truncates column names that are longer than 30 characters. For this reason, it's recommended to keep barometerIT custom field Field IDs shorter than 30 characters and avoid special characters.

           

Create new columns in the ServiceNow tables

In the ServiceNow console, create new columns as needed. For example, to map Capability Type to a column that does not already exist, open System Definition - Tables, find the cmdb_ci_service table, and create a new column called "Barometer Type".

 

Screen Shot 2018-11-14 at 1.51.13 PM.png

Note that each object in barometerIT has a unique identifier, called a "Barometer Number" (aka "BN"). To enable the ServiceNow adapter to update records, you must ensure that each table in ServiceNow has a column for the Barometer Number (of type String and max length 12).

For example, create the following columns:

  • In Application (cmdb_ci_appl), create "Barometer Unique Identifier"
  • In Business Service (cmdb_ci_service), create "Barometer Unique Identifier"
  • In Software Model (cmdb_software_product_model), create "Barometer Unique Identifier"

Create Import Sets in ServiceNow

Import Set Names

Import Sets used by barometerIT in ServiceNow must have specific names. To see the names used in your configuration, click View ServiceNow request fields at the bottom of the ServiceNow Adapter Endpoint configuration screen.

Import Sets for Catalogs must have the name u_barometer_[catalog]_import. For example, to import Systems, create an Import Set with name u_barometer_system_import.

Import Sets for Relationships must have the name u_barometer_[catalog1]_[catalog2]_import. For example, to import System-Capability relationships, create an Import Set with the name u_barometer_system_capability_import.

Import Sets for proposed changes, if those changes are imported, must look like those for approved changes, with the term "proposed" after "barometer". For example, to import proposed changes for Systems, create an Import Set with the name u_barometer_proposed_system_import, and to import proposed System-Capability relationships, create an Import Set with the name u_barometer_proposed_system_capability_import.

Create the CSV files

To create an Import Set, you must first create a CSV text file that contains the barometerIT field IDs to be mapped as column headers. The CSV file contains only one entry that lists the column names separated by commas.

For example, for importing Systems, you would create a file called systems.csv that contains something like the following row:

bn,acronym,contentstatus,core,createdate,description,domain,lastupdatedate,lifecyclestate,name,systempriority,releasedate,sunsetdate,systemtype,systemversion,barometerdeleted

           

NOTE

Each CSV file for a Catalog import file must contain a column called bn. Also, to handle events where entities or relationships are deleted in barometerIT, each CSV file must contain a column called barometerdeleted.

           

The file for the Relationship Import (for example, relationships.csv) must contain the following row:

parent,child,relationshiptype,qualifier,barometerdeleted

Files for Import Sets for proposed changes should contain a row with the following fields:

bn,fieldname,fromvalue,tovalue,proposedchangebn,baromterdeleted

The file for the Proposed Relationship Import must contain the following row:

parent,child,type,relationshiptype,qualifier,proposedchangebn,barometerdeleted

Create Import Sets

Create the Import Sets in ServiceNow for each entity type and relationship type to be synchronized. For example:

  • Barometer System Import (u_barometer_system_import)
  • Barometer Capability Import (u_barometer_capability_import)
  • Barometer Technology Import (u_barometer_technology_import)
  • Barometer System System Import (u_barometer_system_system_import)

           

NOTE

You must use these exact names for the import sets.

           

If the adapter is also configured to send proposed changes, those changes will go into different import sets. For example:

  • Barometer Proposed System Import (u_proposed_barometer_system_import)
  • Barometer Proposed Capability Import (u_proposed_barometer_capability_import)
  • Barometer Proposed Technology Import (u_proposed_barometer_technology_import)
  • Barometer Proposed System System Import (u_proposed_barometer_system_system_import)

           

NOTE

You must use these exact names for the import sets.

           

In the ServiceNow console,

  1. Go to System Import Sets - Load Data.
  2. For Import set table selection, choose Create table.
  3. For Label, enter the name of the Import Set, for example, Barometer System Import.
  4. For Source of the Import, choose File.
  5. Click the Choose File button and then select the CSV file that corresponds to the import set (for example, systems.csv).
  6. For Sheet number and Header row, enter 1.
  7. Click Submit.
  8. Repeat these steps for each of the remaining tables listed above.

Handle Connections as Relationships

In barometerIT, Connections are represented as top-level entities, like Systems and Capabilities. Connections describe an online communication between one to many source and target endpoints, which can be Systems or Companies.

Some users of the ServiceNow Adapter may model these connections as Relationships in ServiceNow. For example, a Connection in barometerIT with three source Systems and four target Systems may be represented as twelve System-System relationships in ServiceNow.

To configure the Adapter to handle Connections in this way, click Handle Connections as Relationships in the Adapter Endpoint configuration screen.

With this checkbox checked, and the corresponding Relationship Types chosen, the adapter will send requests to the corresponding relationship import set (barometer_system_system_import, barometer_system_company_import, and barometer_company_company_import).

 

Create Transform Maps in ServiceNow

Create the Transform Maps for each of the entity types to be synchronized. For example:

Transform map Source table Target table
Barometer System Transform Barometer System Import Application [cmdb_ci_appl]
Barometer Capability Transform Barometer Capability Import Business Service (cmdb_ci_service)
Barometer Technology Transform Barometer Technology Import Software Model (cmdb_software_product_model)
Barometer System System Transform Barometer System System Import CI Relationship [cmdb_rel_ci]

 

  1. In the ServiceNow console, go to System Import Sets - Create Transform Map.
  2. For Name, enter the name listed above (e.g. Barometer System Transform).
  3. For Source Table, enter the name of the import table created in the previous step (e.g. Barometer System Import).
  4. For Target Table, choose the ServiceNow table to map to. For example, for Barometer System Transform, choose Application [cmdb_ci_appl].
  5. Click Submit.

Map the fields in the transform maps

For each of the transform maps created above, you must map the fields.

  1. In the ServiceNow console, go to System Import Sets - Transform Maps.
  2. Open a transform map (e.g. Barometer System Transform).
  3. Click Mapping Assist.
  4. Map each field in the import set to a field in the target table. For example, for Barometer System Transform, map description to Description.

  5. For date and time fields, change the "Date Format" as follows:

    • Date/Time : yyyy-MM-dd HH:mm:ss z
    • Date: yyyy-MM-dd
    • Time: HH:mm:ss
       
  6. For the Barometer System, Capability, and Technology Transform Maps:
    1. Make sure that the bn field is mapped to the unique identifier field (for example, Barometer Unique Identifier) created above.
    2. Enable Coalesce for the mapping by clicking on u_bn in the Field Maps, then click the Coalesce checkbox and click the Update button.

  7. For the Barometer Association Transform map, create the following maps:

    • parent → parent
    • child → child

Handle relationship type and qualifier for associations

Associations in barometerIT can have a relationship type and/or a qualifier which, if present, will be pushed into the import set. These can be mapped to the ServiceNow relationship type in a script. For example, the relationship type "HAS_CHILD" could be mapped to the ServiceNow relationship type "Contains::Contained by".

Bulk Load

Once the endpoint is saved, contact barometerIT operations (support@barometerit.com) to schedule a one-time load of existing data from barometerIT to ServiceNow. After that process is complete, from henceforward all changes will be synchronized in real time.

Testing

As with all integrations, barometerIT requires that customer integrators first test in the STAGE environment. Every tenant has a barometerIT STAGE instance which nearly mirrors the production environment. The STAGE environment is made available for integration testing. Of course, this will likely require a "stage" instance of ServiceNow on your end. We expect most customers will have that already for exactly these kinds of cases. (We know from our own experience that ServiceNow makes these easy to obtain for development purposes.)