Configuring Organization Sync and Device Sync for the CMDB SyncPack

Download this manual as a PDF file 

This section describes the how to configure and run Organization Sync and Device Sync in the "ServiceNow CMDB" SyncPack.

For more information about the other syncs in this SyncPack, see Configuring Additional Syncs for the CMDB SyncPack.

Creating and Aligning a Configuration Object

A configuration object supplies the login credentials and other required information needed to execute the steps for an application in PowerFlow. The Configurations page () of the PowerFlow user interface lists all available configuration objects for that system.

You can create as many configuration objects as you need. A PowerFlow application can only use one configuration object at a time, but you can use (or "align") the same configuration object with multiple applications.

To use this SyncPack, you will need to create one or more configuration objects in the PowerFlow user interface and align that configuration object to the applications that let you sync data between SL1 and ServiceNow.

Depending on your SL1 and ServiceNow environments, you might be able to use the same configuration object with other ServiceNow SyncPacks.

When either multiple SL1 stacks or multiple ServiceNow systems are involved with PowerFlow, you should create an individual configuration object for each SL1 stack or ServiceNow system. Next, create an individual schedule for each configuration object. Each schedule should use a configuration object that is specific to that single SL1 stack or ServiceNow system. Creating copies of a PowerFlow application from a SyncPack for the purpose of distinguishing between domains is not supported, and will result in issues on upgrades.

Creating a Configuration Object

For this SyncPack, you can make a copy of the "ServiceNow SyncPack" configuration object, which is the sample configuration file that was installed with the "ServiceNow Base" SyncPack.

The "ServiceNow SyncPack" configuration object contains all of the required variables. Make a copy of the configuration object and update the variables from that object to match your SL1 and ServiceNow settings.

To create a configuration object based on the "ServiceNow SyncPack" configuration object:

  1. In the PowerFlow user interface, go to the Configurations page ().
  2. For the "ServiceNow SyncPack" configuration object, click the Actions button () and select Edit. The Configuration pane appears.

    Click Toggle JSON Editor to show the JSON code. Click the button again to see the fields.

  1. Click Copy as. The Create Configuration pane appears.

    This step is required. Do not use the original configuration object to run PowerFlow applications.

  2. Complete the following fields:

  • Friendly Name. Name of the configuration object that will display on the Configurations page.
  • Description. A brief description of the configuration object.
  • Author. User or organization that created the configuration object.
  • Version. Version of the configuration object.
  1. In the Configuration Data field, include the required block of code to ensure that the applications aligned to this configuration object do not fail:

      {
        "encrypted": false,
        "name": "sl1_db_host",
        "value": "${config.sl1_host}"
      },

    For example:

      {
        "encrypted": false,
        "name": "sl1_db_host",
        "value": "10.2.11.42"
      },
  1. In the Configuration Data Values field, update the default variable definitions to match your PowerFlow configuration.

    The region value is a user-defined variable that identifies your SL1 instance within ServiceNow.

  1. To create a configuration variable in the JSON Editor, define the following keys:
  • encrypted. Specifies whether the value will appear in plain text or encrypted in this JSON file. If you set this to "true", when the value is uploaded, PowerFlow encrypts the value of the variable. The plain text value cannot be retrieved again by an end user. The encryption key is unique to each PowerFlow system. The value is followed by a comma.
  • name. Specifies the name of the configuration file, without the JSON suffix. This value appears in the user interface. The value is surrounded by double-quotes and followed by a comma.
  • value. Specifies the value to assign to the variable. The value is surrounded by double-quotes and followed by a comma.
  1. Click Save. You can now align this configuration object with one or more applications.

Aligning a Configuration Object

Before you can run the applications in this SyncPack, you must first "align" a configuration object with the application you want to use.

To align a configuration object with an application:

  1. From the Applications page of the PowerFlow user interface, open the relevant application and click Configure. The Configurations pane for that application appears.
  2. From the Configurations drop-down, select the configuration object you want to use.
  3. Click Save to align that configuration with the application.
  4. Repeat this process for every other application you want to use.

The values for the parameters that display in the Configuration pane with a padlock icon () are populated by the values in the configuration object.

Syncing Organizations

An Organization Sync uses the "Sync Organizations from SL1 to ServiceNow" application to sync organizations from SL1 with ServiceNow companies. In this context, sync means that if you update a company in ServiceNow, the Organization Sync process will update the SL1 organization with that information, and vice versa.

If your ServiceNow environment is domain-separated, where the data, processes, and administrative tasks have been organized into logical groupings called domains, then the first sync you should run on a new PowerFlow system is an Organization Sync. For more information, see For Domain-separated ServiceNow Environments Only.

If you are using SL1 as your "source of truth", you are not required to configure and run an Organization Sync. However, if you want to filter by organization or company (using the use the org_filters option) with any of the other syncs in this SyncPack, such as Device Sync, File System Sync, and Interface Sync, you will need to run the Organization Sync as documented in the steps below.

For Domain-separated ServiceNow Environments Only

If your ServiceNow environment is domain-separated, where the data, processes, and administrative tasks have been organized into logical groupings called domains, then the first sync you need to run on a new PowerFlow system is an Organization Sync.

Starting with version 3.5.0 of this SyncPack, the following fields are no longer being used on the Company table (core_company) in ServiceNow:

  • SL1 Monitored
  • SL1 Region
  • SL1 ID

The ScienceLogic-specific information was moved to an application-specific table (x_sclo_scilogic_organizations) to track which Organization goes with any specific Company.

Creating new records is currently only available with the x_sclo_scilogic.admin role.

If you get an error message stating that a device or CI has no domain_sys_id value, that means that the company for that CI has no domain.

Considerations for Version 3.5.x of the SyncPack

If ServiceNow is set as the Source of Truth in the PowerFlow Organization Sync application, you must manually create the linking records in ServiceNow. If ScienceLogic is set as the Source of Truth, then you can skip these sections and go to Configuring Organization Sync.

Version 3.5 introduced linking records (using the x_sclo_scilogic_organizations table), which enabled a many-to-one relationship between multiple SL1 organizations to a single ServiceNow company.

A linking record in ServiceNow lets you set up the following configurations:

  • Tracking the relationship of a single ServiceNow company with a single SL1 organization in multiple SL1 databases.
  • Matching multiple SL1 organizations (in multiple SL1 systems) to the same ServiceNow company.
  • Importing a ServiceNow company into SL1 as an SL1 organization.

Aligning multiple SL1 organizations from the same SL1 system to a single ServiceNow company is not supported at this time.

For more information about creating linking records, see Creating a Linking Record when ServiceNow is the Source of Truth.

Upgrading to Version 3.5.x

If you are upgrading to version 3.5.x from an older version and you want to sync multiple SL1 organizations to a single ServiceNow company, you need to determine if the organizations already exist in the multiple SL1 systems that you want to sync to the single company in ServiceNow:

  • If the SL1 organizations already exist, you will need to create a linking record tied to the company with the region value for each SL1 stack, plus the native key, the SL1 id, and monitored = True.
  • If the SL1 organizations do not currently exist and you want the Organization Sync to create the organizations in SL1 (using the Create_Missing option in the Configuration pane), the linking records tied to the companies only need the region and monitored = True.

ScienceLogic highly recommends that you complete the upgrade steps on a development instance and test the syncs first before you implement the updates in a production environment.

To upgrade to version 3.5.x of the "ServiceNow CMDB" SyncPack:

  1. In PowerFlow, install the latest version of the following SyncPacks:
  • ServiceNow CMDB SyncPack
  • ServiceNow Base SyncPack
  • Base Steps SyncPack
  1. After you install the SyncPacks, click the Actions button (), select Change active version, and select the most recent version of each SyncPack.
  2. Download the most recent version of the "ScienceLogic SL1: CMDB & Incident Automation ServiceNow" scoped application from the ServiceNow Store at https://store.servicenow.com. For more information, see Installing the "ScienceLogic SL1: CMDB & Incident Automation" Application in ServiceNow.

    You can verify the version number on the Dependencies for SL1 PowerFlow SyncPacks page, in the Supported "Scoped Application" Version column for the SyncPack.

  3. If your ServiceNow instance is domain-separated, download and install the domain separation update set, "ScienceLogic Domain Separation (Global) 1.0.67.xml" from ServiceNow. For more information, see Installing the ScienceLogic Domain Separation (Global) Update Set in ServiceNow.

  4. Create linking records on the Organization Source table (x_sclo_scilogic_organizations) corresponding to existing records on the core_company table. For more information, see Creating a Linking Record.

    To assist in the migration, you can use the "ScienceLogic ServiceNow Integration (v1.0.76)+ (Organization migration)" fix script (Org Sync migration.xml). You shold only run this script once, upon initial upgrade. Ask your ScienceLogic contact for access to this script.

  5. In the "Sync Organizations from SL1 to ServiceNow" application, make sure that the Source_of_Truth option on the Configuration pane is set to ServiceNow.

Creating a Linking Record when ServiceNow is the Source of Truth

Before running the "Sync Organizations from SL1 to ServiceNow" application for the first time in a domain-separated environment, you will need to create a linking record in ServiceNow.

You should also create a linking record if you select ServiceNow as the "source of truth" on the Configuration page of the "Sync Organizations from SL1 to ServiceNow" application, even if your ServiceNow instance is not domain-separated.

A linking record in ServiceNow lets you set up the following configurations:

  • Tracking the relationship of a single SL1 organization with a single ServiceNow company in multiple SL1 databases.
  • Matching multiple SL1 organizations (in multiple SL1 systems) to the same ServiceNow company.
  • Importing a ServiceNow company into SL1 as an SL1 organization.

ScienceLogic highly recommends that you try out this feature in a test environment before pushing to production.

If you set up an Organization Sync with a version of this SyncPack earlier than version 3.5.0, you will need to create a linking record when you upgrade to version 3.5.0 or later. The linking record is only required when you upgrade if you use ServiceNow as the source of truth.

To create a linking record:

  1. In ServiceNow, navigate to ScienceLogic > Supporting Imports > Organization Source.

  2. Click New. A new record appears.

  3. Complete the following required fields:

    • Region. Set this value to match the region value in the configuration object aligned with the "Sync Organizations from SL1 to ServiceNow" application in the PowerFlow user interface.

    • Company. You would only need to use this field if you either want SL1 to create the organization or you want to link a specific SL1 organization with a specific ServiceNow company. To do this, search for the name of the ServiceNow company you want to link to (or have SL1 create). Otherwise, you can leave this field blank.

      Because this a document field, you must click the magnifying class icon to add the Company [core_company] table in the Table name field, and then click the magnifying class icon to locate a company from the Document field:

    • Monitored. Set to True (checked).

  1. On the new record, the following fields are not required, or they are required under specific conditions:

    • native key. This key is a unique identifier for an SL1 organization, from a specific SL1 database. Use the following format:

      <region>+ORG+<roa_id>

      where:

      • <region> is the region value in the configuration object aligned with the "Sync Organizations from SL1 to ServiceNow" application. This value should match the value in the Region field, above.

      • <roa_id> is the value for that organization in the ID column of the Organizations page () in SL1. This value should match the value in the ID field, above.

      For example: ScienceLogic+ORG+2.

    • ID. Use this field only if you want to link a specific SL1 organization with a specific ServiceNow company. To do this, locate the value for that organization in the ID column of the Organizations page () in SL1. Otherwise, you can leave this field blank.

  2. Repeat steps 2-4 to create a linking record for every instance where you want to track the relationship of a single organization with a single company in multiple SL1 databases.
  3. Go to the Configuring Organization Sync topic to run the "Sync Organizations from SL1 to ServiceNow" application. Make sure that the Source_of _Truth field on the Configuration pane is set to ServiceNow.

For Case Integration ServiceNow Environments Only

Add the following roles to the Integration user so that user can interact with the "ScienceLogic SL1: Customer Service Management Integration" Application in ServiceNow.

  • x_sclo_case_mgmt.admin. Provides user rights to interact with the scoped application tables and modules in ServiceNow.
  • import_transformer. Provides user rights to manage import set transform maps, run transforms, and access responses.

If your ServiceNow environment is using the Case Integration module and you intend to use customer_account records, you will need to add additional rights to the Integration user. These rights allow the Integration user to read the table fields:

  • sn_customerservice.customer_data_viewer

You will need to add cross-scoped access for read-only to the customer_account table as well. ScienceLogic recommends that you use ServiceNow as the source of truth for Organizations (Companies). For more information, see Allowing Cross-Scoped Access in ServiceNow.

Configuring Organization Sync

Organization Sync uses the "Sync Organizations from SL1 to ServiceNow" application to pull organizations from SL1 and sync them with ServiceNow companies.

If you are using SL1 as your "source of truth", you are not required to configure and run an Organization Sync. However, if you want to filter by organization or company (using the use the org_filters option) with any of the other syncs in this SyncPack, such as Device Sync, File System Sync, and Interface Sync, you will need to run the Organization Sync as documented in the steps below.

To sync SL1 organizations with ServiceNow companies:

  1. In the PowerFlow user interface, go to the Applications page and select the "Sync Organizations from SL1 to ServiceNow" application. The Application page for that application appears.

  2. Click Configure. The Configuration pane appears:

  1. Complete the following fields, as needed:

  • Configuration. Select the configuration object with the relevant SL1 and ServiceNow credentials to align with this application. You cannot edit fields that are populated by the configuration object. Required.

    The region field is populated by the configuration object you aligned with this application. The region value must match the value in the SL1 Region field in ServiceNow. If you need to update this value, you will need to define the region variable in the configuration object that is aligned with this application, or align a different configuration object that has the correct region value.

  • read_timeout. Specify the maximum amount of time in seconds that the application should wait for a response before timing out.

  • snow_chunk_size. Specify the number of organizations to include in each chunk sent to ServiceNow when you run this application.

  • verify_snow_ssl. Toggle on (blue) this option to enable verification of the SSL certification when you run this application.

  • Update_Name. This option addresses the situation where PowerFlow finds a match with an organization and a company, but the names do not match. This option updates a company or organization name based on your selection in the Source_of_Truth field, below. For example, if you selected ScienceLogic as the source of truth, PowerFlow uses the company name from ScienceLogic as the updated name. By default, this option is not selected.

  • Create_Missing. Select this option if you want PowerFlow to create a new organization or company if that record is missing, based on your selection in the Source_of_Truth field. By default, this option is not selected.

    Starting with version 3.5.0 of this SyncPack, the Domain Separation parameter was removed from the Configuration pane. Domain separation is still supported, but this parameter no longer needs to be selected.

  • Source_of_Truth. Select whether you want to use data from ServiceNow or ScienceLogic as the "source of truth" when this application encounters duplicate data or data collisions. In most situations, the source of truth would be the application where you initially configured and created the companies or organizations:

  • If you select ServiceNow, you must specify the values in the SL1 Monitored and SL1 Region fields in ServiceNow. Because these fields do not display by default on the Companies page in ServiceNow, navigate to the Companies page in ServiceNow, click the Update Personalized List icon (), and add the SL1 Monitored and SL1 Region columns to that page. Also, if your ServiceNow configuration uses domain separation, you must select ServiceNow as the source of truth.
  • If you select ScienceLogic, you do not need to do anything else related to this field.
  1. In the Attribute Mappings section, click the Edit button to view and edit the mappings for any other organization attributes, such as additional address or contact information. These mappings will sync between SL1 (the first column) and ServiceNow (the second column). A set of organization attributes are already mapped by default.

    You can use Jinja2 Templates in fields that are aligned with the "Source of Truth" you selected (SL1 or ServiceNow). For more information, see Using a Jinja2 Template.

    When an attribute value is "0" in SL1, the corresponding field in ServiceNow might display as empty.

  2. Click Save. The Configuration pane automatically closes after this message appears.

  3. Click Run to run the application.

  4. When the application completes, open the Step Log and review the log messages for the "Process Organizations" step to see if any company or organization records were created. As needed, select the other steps to review the logs on the Step Log for those steps.

    Any SL1 organization that is synced to a ServiceNow Company will have the crm_id field on the Properties tab for that organization populated with the ServiceNow Company sys_id variable.

ScienceLogic recommends that you schedule an Organization Sync to run at least once a week. For more information, see Scheduling PowerFlow Applications.

Syncing Devices from SL1 to ServiceNow

The "Sync Devices from SL1 to ServiceNow" application syncs devices and virtual device relationships from SL1 to ServiceNow. You can also sync devices based on organization and collector group.

The Device Sync process use rules or "mappings" that you can define in the "Sync Devices from SL1 to ServiceNow" application. These mappings connect an SL1 device class to a ServiceNow CI class, which determines the CI class that ServiceNow uses when creating the CI in ServiceNow.

For more information about building service rules (containment rules and hosting rules) for devices and CIs, see Configuring Service Rules for Device Sync.

The "Sync Devices from SL1 to ServiceNow" application can also collect manufacturer and model attributes from asset records aligned with devices in SL1 and sync that information with ServiceNow. PowerFlow only populates the manufacturer and model attributes if the values exist in ServiceNow CIs; PowerFlow does not create new manufacturer values in ServiceNow. The "Sync Devices from SL1 to ServiceNow" application uses the sys_id field as a reference when syncing manufacturer and model information between SL1 and ServiceNow. For more information, see Device Attribute Mappings.

Merged Devices in SL1

When the "Sync Devices from SL1 to ServiceNow" application encounters a merged device in SL1, it splits the record into two objects to allow for correct default relationships in ServiceNow.

Starting with version 3.2.0 of this SyncPack, the "Sync Devices from SL1 to ServiceNow" application syncs both the physical and the component device in SL1 to ServiceNow. When a merged device is encountered in SL1, the "Sync Devices" application splits the device in PowerFlow and creates two CIs in ServiceNow. This action does not impact the source device record in SL1.

In ServiceNow, the physical CI includes the relevant asset information. A relationship also exists between the physical CI and the virtual CI. The asset information is directly copied between both CIs, so the data will essentially be duplicated across both devices, and the data will be submitted to two separate tables. The sl1_url will also be the same on both devices, so that both CIs will point to the same device in SL1.

Using Other Data Sources with Merged Devices

If you have other data sources syncing into the ServiceNow CMDB and you have merged devices in SL1, ScienceLogic recommends caution when integrating to the CMDB.

Also, ScienceLogic recommends that you ensure that configuration of the Identification and Reconciliation (IRE) within ServiceNow affects all data sources that are integrating into it. In the case of ScienceLogic, this is most apparent when syncing merged devices. Modifications to the IRE to handle merged devices affects all other data sources that sync to those specific class tables. It is your responsibility to understand each data source, how that data source integrates with the ServiceNow CMDB, and how to leverage that knowledge to understand the impact IRE changes may have.

ScienceLogic cannot be held responsible for any duplicate, lost, or incorrect CI information as a result of merged devices when multiple data sources are involved. This scenario will also affect your Support SLAs, as this practice deviates from recommended best practices.

For more information about the ServiceNow Identification and Reconciliation module, see the ServiceNow documentation: https://docs.servicenow.com/bundle/orlando-servicenow-platform/page/product/configuration-management/concept/c_CompsandProcessIDandReconcil.html.

Common Fields Used by Device Sync

The "Sync Devices from SL1 to ServiceNow" application uses the following ServiceNow fields to determine which devices to sync from SL1 to ServiceNow:

  • SL1 Monitored. This field displays a Boolean (true or false) value that is impacted by whether the device is in SL1 or not. The device being found in ServiceNow depends on the SL1 Monitored field. The device being found in SL1 depends on the class mappings defined in the "Sync Devices from SL1 to ServiceNow" application.
    • If the CI is in ServiceNow and the device is in SL1 , the SL1 Monitored flag is set to true.
    • If the CI is in ServiceNow but the device is not in SL1, the SL1 Monitored field is set to false. Anything pulled from ServiceNow (everything that is monitored: true and matches the region) that does not have a matching device pulled from SL1 gets marked as monitored: false.
  • SL1 Region. This field represents an ID for the SL1 instance or instances being synced to the ServiceNow instance. The SL1 Region field is determined by the user when configuring the IS applications. In a multi-SL1 environment, ScienceLogic recommends that you make the SL1 Region field descriptive so the ServiceNow user knows from which SL1 stack the CI originated.
    • If the SL1 Region field is defined as an identifier by the CI class, ServiceNow will create new CI records with the new SL1 Region value, and the user must manually delete the duplicate CIs in the old SL1 Region field.

    • If the SL1 Region field is not defined as an identifier by the CI class, ServiceNow will not treat these devices as new CIs, and the SL1 Region field will be automatically updated.

      Changing the SL1 Region value after an initial run of the "Sync Devices from SL1 to ServiceNow" application will have differing results depending on the service rules defined in ServiceNow that dictate reconciliation of the CI. If you change the SL1 Region value, you will ll need to run "Sync Devices from SL1 to ServiceNow" twice: once to align the CIs with the new region, and a second time to enable PowerFlow to re-cache the newly updated CIs in the region.

  • SL1 ID or sl1_id. This field represents the value of the object from SL1 that is being synced. Do not use sl1_id as a CI Identifier.

Running a Device Sync

To perform a Device Sync between SL1 and ServiceNow, run the following applications in the PowerFlow user interface, in the specified order:

  • Cache ServiceNow Companies, CIs and SL1 Orgs, Device Classes. Reads all existing SL1 device classes and ServiceNow CI classes and caches them for the Device Sync. This application uses this data to populate the mappings drop-down values in the "Sync Devices from SL1 to ServiceNow" application. Before version 3.5.0 of this SyncPack, this application was named "Cache ServiceNow CIs and SL1 Device Classes".
  • Generate Required CI Relations for ServiceNow. Determines if you are missing any class mappings or service rules that might be required in ServiceNow.
  • Sync Devices from SL1 to ServiceNow. Syncs devices and virtual device relationships from SL1 to ServiceNow.

The speed of ServiceNow processing is reduced by ServiceNow errors generated when consuming payloads. If you experience slow processing or "maximum execution time exceeded" messages, you must review and address any ServiceNow errors reported to resolve. If there are significant ServiceNow errors in Device Sync, those errors will also impact Interface sync processing. When running dependent syncs at large scale, such as Interface Sync and Device Sync, ScienceLogic recommends that you run them serially, not at the same time. Running both syncs at the same time will greatly hinder ServiceNow processing and scalability.

To sync SL1 devices with ServiceNow:

  1. In the PowerFlow user interface, select the "Cache ServiceNow CIs and SL1 Orgs, Device Classes" application from the Applications page, click Configure, align a configuration object, and then click Run.

    If you change any of the containment rules or hosting rules in ServiceNow, you will need to run "Cache ServiceNow CIs and SL1 Orgs, Device Classes" again. For more information, see Configuring Service Rules for Device Sync.

  2. Select the "Generate Required CI Relations for ServiceNow" application from the Applications page, click Configure, align a configuration object, and then click Run.

    PowerFlow uses the Device Class mappings you are going to configure in step 6, so you do not need to set up any mappings on the Configuration pane for the "Generate Required CI Relations for ServiceNow" application. Any mappings you add to this application will overwrite mappings in the "Sync Devices from SL1 to ServiceNow" application.

  3. When the "Generate Required CI Relations for ServiceNow" application completes, review the log information in the Step Log for the "Pull and Process Relations" step. You should see a log message stating that no missing relations were found. For more information, see Log Messages for the "Generate Required CI Relations for ServiceNow" Application.

    If needed, address any missing class mappings or service rules. For more information on service rules, see Creating a ServiceNow Update Set.

  4. Select the "Sync Devices from SL1 to ServiceNow" application from the Applications page and click Configure. The Configuration pane appears:

  1. Complete the following fields, as needed:
  • Configuration. Select the configuration object with the relevant SL1 and ServiceNow credentials to align with this application. You cannot edit fields that are populated by the configuration object. Required.

    The region field (along with other fields related to user names and passwords) is populated by the configuration object you aligned with this application, using the Configuration field. The region value on this pane must match the value in the SL1 Region field in ServiceNow. If you need to update this value, you will need to define the region variable in the configuration object aligned with this application, or align a different configuration object that has the correct region value.

  • read_timeout. Specify the maximum amount of time in seconds that the application should wait for a HTTP Read response before timing out. The default is 300 seconds.
  • Include_Orgs. If you want to include a specific set of SL1 Organizations in the device sync, add the Organization IDs from the SL1 Organizations page () in this field, separated by commas. If this field is enabled, PowerFlow will pull only the Organizations listed in this field; PowerFlow does not pull all Organizations and then drop those not on the list. Leave this field empty to sync all SL1 Organizations. Optional.
  • Include_CUGs. If you want to include SL1 Collector Groups (CUGs) in the device sync, add the Collector Group IDs from SL1 in this field, separated by commas. Leave this field empty to sync all SL1 Collector Groups. Optional.

    A misconfiguration in the Include Orgs field or the Include_CUGs fields might change the monitoring flag for one or more devices. In other words, a misconfiguration in this field could switch the SL1 Monitored flag from "true" to "false", removing that device or devices from the device sync.

  • sl1_chunk_size. Specify the number of devices to pull from SL1 in each chunk. The default is 500 devices per chunk.
  • snow_request_limit. Specify the number of CIs fetched from ServiceNow in each request. The default is 500 objects per chunk.
  • selected_devices. If you want to sync a sub-set of all discovered devices, type a comma-separated list of the Device IDs from SL1 for only the devices that you want to sync. Leave this field empty to sync all SL1 devices.
  • sl1_url_override. Update this field if you want to use an URL that is different from the standard SL1 URL that gets sent to the ServiceNow CI record. Optional.
  • excluded_devices. Type a list of comma-separated device names or device IDs for any devices that you want to exclude from the device sync. A device on the excluded list will still be queried, but it will be dropped during the PowerFlow sync process. Optional.
  • cache_lookup_chunk_size. Specify the number of CI correlation documents to pull from the PowerFlow cache in a chunk. The default is 1000 documents per chunk.
  • discovery_source. Specify the ServiceNow Discovery source. The default is "Other Automated".
  • snow_batch_size. Specify the total number of CIs being sent to ServiceNow in each triggered application. The default is 150 objects per batch.
  • snow_chunk_size. Specify the number of CI objects to send in each chunk or in each sub-payload with a batch (specifed in the snow_batch_size field). The default is 150 objects per chunk or sub-payload.
  • max_count_for_relationships. Specify the maximum number of device IDs to query for sets of relationships in a single chunk from SL1.
  • verify_snow_ssl. Toggle on (blue) this option to enable verification of the SSL certification when you run this application.
  • exclude_inactive. Select this option to prevent syncing devices to ServiceNow that are not enabled, unavailable, or in maintenance. By default, this option is not selected.
  • enable_device_active. Select this option to enable the Device Active block in the device GraphQL query, which contains information about the active state of the SL1 device. By default, this option is not selected. Accessing this data in the attribute mappings requires a Jinja2 Template. For more information, see Using a Jinja2 Template.
  • enable_asset_networks. Select this option to enable the assetNetworks block in the device GraphQL query, which returns a list of asset networks. By default, this option is not selected. Accessing this data in the attribute mappings requires a Jinja2 Template. For more information, see Using a Jinja2 Template.

    Please note that enabling this option might cause performance issues on the SL1 side.

  • use_ap2_url. Select this option if you want the device URLs in the SL1 URL field in ServiceNow CIs to point to the corresponding Device Investigator page in the SL1 user interface: /inventory/devices/<SL1_device_ID>/investigator. This option is enabled by default. If you turn off this option, the device URL points to the classic EM7 user interface: /em7/index.em7?exec=device_summary&did=<SL1_device_ID>.
  • unmerge_devices. De-select this option if you want to turn off the "unmerge" behavior added in version 3.2.0 of this SyncPack, where PowerFlow splits a merged device record into two objects to allow for correct default relationships in ServiceNow. This option is enabled by default.
  • Domain_Separation. Select this option if your ServiceNow environment is domain-separated, where the data, processes, and administrative tasks have been organized into logical groupings called domains. If your ServiceNow instance is domain-separated, the user listed in the snow_user field must be a member of the top domain and have access to all of the domains you intend to integrate. Also, ServiceNow should be the "source of truth" for organizations if your environment is domain-separated. If this option is selected, PowerFlow syncs the ServiceNow company sys_id with the corresponding SL1 organization.
  • drop_sys_id. Select this option if you want to remove the sys_id in existing CIs from the sync. If you set drop_sys_id to true, make sure that ServiceNow can correctly identify and correlate your existing CIs with the properties that are available. By default, this option is not selected.
  • drop_company. Select this option if you want to remove the sys_id in existing Companies from the sync, which prevents the "company" field from being sent to ServiceNow. Selecting this option has no effect if you selected the Domain_Separation option for this application. By default, this option is not selected.

    If you select this option, the ServiceNow company sys_id for the CI and the SL1 organization crm_id for the SL1 device will not be compared when determining if an update has occurred. Do not select this option if you selected the Domain_Separation option, as ServiceNow requires PowerFlow to send the "company" field in domain-separated environments. Also, do not select this option if you selected the change_device_organizations option, as changing the company for a CI in ServiceNow requires the "company" field to be sent.

  • change_device_organizations. When enabled, this parameter allows devices to change companies with a Device Sync if the companies are within the same domain in ServiceNow. If you change the Organization/Company and another field or fields, but do not enable this parameter, PowerFlow will not apply any changes to the device. By default, this option is not selected.
  • generate_report. Select this option to create a report about the devices that you sync with ServiceNow. PowerFlow generates a report every time you run the device sync application, and the reports are available on the Reports page of the PowerFlow user interface.
  • enable_advanced_topology. Select this option to allow the pull and process advanced topology step to be executed when the sync is run. If disabled, this step will be skipped. This toggle defaults to a value of True.
  • Simulation_Mode. Select this option if you want to perform a simulated run of this application to show you the potential results of that run. By default, this option is not selected.
  • retry_jitter. When selected, instead of using a defined interval between retries, the PowerFlow system will retry the step execution at random intervals. By default, this option is not selected.
  • retry_backoff. When selected, instead of using a defined interval between retries, PowerFlow will incrementally increase the interval between retries. By default, this option is not selected.
  • gql_filter. Using JSON, you can optionally define a custom GraphQL filter to apply to the devices in the sync. To test out a GraphQL filter, go to the GraphiQL interface in SL1 by typing the URL or IP address for SL1 in a browser, add /gql to the end of the URL or IP address, and press Enter. Search the built in GraphQL docs for DeviceSearch and determine how to set up your custom filter. An example of a Device Search query using JSON: {"name": {"doesNotBeginWith": "jc-is-ma"}}

    You can use this field to filter devices by Device Group. For more information, see Filtering Device Sync by Device Group.

    A misconfiguration in this field might change the monitoring flag for one or more devices. For example, a misconfiguration in this field could switch the SL1 Monitored flag from "true" to "false", removing that device or devices from the device sync. This field is an advanced feature that requires a basic knowledge of the SL1 GraphQL implementation. For more information, see Using the ScienceLogic GraphQL API.

  • customer_ci_relation_overrides. To override existing relationship linking and directly control the link between Device Classes and attributes, add JSON code to this field. The JSON for this field includes default relationship overrides for VMware instead of direct parent/child relations. For more information, see Configuring Customer CI Relation Overrides and Mappings between SL1, ServiceNow, and Other Applications.

  1. In the Mappings section, click the Edit button (PowerFlow 2.7.0 or later) or the expand button () to view and edit the mappings between ServiceNow CI classes and SL1 device classes. This section is pre-loaded with a large number of default device class mappings. You can map a single ServiceNow CI class with multiple SL1 device classes.

    The "Sync Devices from SL1 to ServiceNow" application will only sync a device from SL1 if the device class for that device is mapped to a ServiceNow CI class in the Mappings section. The default mappings in this section do not cover all technologies, however, and syncing additional technologies from SL1 to ServiceNow might require additional research to understand the class structure.

    For more information about how to view, edit, and create mappings, see Editing Mappings in a PowerFlow Application. This topic also covers how to use the Company Mapping Override and the Attribute Mappings sections, below.

  2. In the Company Mapping Override section, you can create a new mapping for the ServiceNow company field. You can override the company field with a different ServiceNow field where you can read and write the company_sys_id for CIs.

  3. In the Attribute Mappings section, click the Edit button (PowerFlow 2.7.0 or later) or the expand button () to view and edit the mappings for any other custom device attributes you want to sync between SL1 (the first column) and ServiceNow (the second column). For more information, including lists of default and available device attribute mappings, see Device Attribute Mappings.

    To sync Device Notes between SL1 and ServiceNow, create a custom attribute for the device note in this section. This option works best if you only want a single value synced over so that value can remain in the notes. All custom attributes for each SL1 device are automatically synced.

    For the Attribute Mappings section, you can use a Jinja2 Template for device attribute fields on the SL1 side (the left column). For more information, see Using a Jinja2 Template.

    When an attribute value is "0" in SL1, the corresponding field in ServiceNow might display as empty.

  4. Click Save. The Configuration pane closes.

  5. Run the "Sync Devices from SL1 to ServiceNow" application.

  6. When the application completes, open the Step Log and review the log messages for the "Compare SL1 Devices and ServiceNow CIs" step to see if any Device or CI records were added, updated, or disconnected from the sync. As needed, select the other steps to review the logs on the Step Log for those steps.

Depending on the number of devices you are syncing to ServiceNow, it might take a few minutes for all devices to get fully synced to the CMDB. You might notice after running device sync that the number of SL1 Monitored CIs continues to increase after each refresh. This is expected behavior due to payload chunking in ServiceNow. ServiceNow processes each payload as an individual chunk.

ScienceLogic recommends that you schedule a Device Sync to run every 24 hours. For more information, see Scheduling PowerFlow Applications.

Using a Jinja2 Template

The attribute mappings in Device Sync applications now support Jinja2 Templates, which let you sync complex, concatenated (linked) fields from SL1 to ServiceNow. For example, you can add these complex values in the SL1 side of the attribute_mappings section of the Configuration pane for the "Sync Devices from SL1 to ServiceNow"application, and that value is mapped to one or many fields in ServiceNow. For more information about Jinja2 Templates, see the Template Designer Documentation.

In the "Sync Devices from SL1 to ServiceNow" application, the SL1 side can be a Template. In the "Sync CI Attributes from ServiceNow to SL1" application, the ServiceNow side can be a Template.

Example: A Basic Template for Device Attributes

This example is included in the "Sync Devices from SL1 to ServiceNow" application as the first default value in the attribute_mappings section of the Configuration pane:

This template, when used on the SL1 side of the attribute_mappings section, populates the short_description field in ServiceNow:

"Description: {{device.device_category}}, Device Class: {{device.device_class}}": [ "short_description" ]

In the above example, for a device with a category: Testing and a Device Class of Testing | Testing, the end result would be Description: Testing, Device Class: Testing | Testing, which will be posted to the short_description field in ServiceNow.

The Jinja2 Templates will have access to all properties on the Device.

Any item that is generated by a template is always a string.

Example: An Advanced Template for Device Sync

The following example lets you get the active status of SL1 Devices:

{%- set output = [] -%}
{%- if device.active.unavailable == True -%}{%- set output = output + ['Unavailable'] -%}
{%- endif -%}
{%- if device.active.userDisabled == True -%}{%- set output = output + ['User Disabled'] -%}
{%- endif -%}
{%- if device.active.userInitiatedMaintenance == True -%}{%- set output = output + 
['User Initiated Maintenance'] -%}{%- endif -%}
{%- if device.active.userMaintenance == True -%}{%- set output = output + 
['User Initiated Maintenance'] -%}{%- endif -%}
{%- if output|length > 0 -%}
{{ ", ".join(output) }}
{%- else -%}
{{ "Active" }}
{%- endif -%}

Example: Another Advanced Template for Device Sync

The following example shows another way to get the active status of SL1 Devices:

{%- set prettify = {"userInitiatedMaintenance": "User Initiated Maintenance", "systemDisabled": 
"System Disabled", "maintenance": "System Maintenance", "unavailable": "Unavailable", 
"userDisabled": "User Disabled"} -%}
{%- set ns = namespace(maint=[]) -%}
{%- for k,v in device.active.items() -%}
{%- if v -%}
{%- set ns.maint = ns.maint + [prettify[k]] -%}
{%- endif -%}
{%- endfor -%}
{{", ".join(ns.maint) if ns.maint else "Active"}}

Example: Advanced Template for Device Class, Sub Category, and Model

The following example shows how to gather device data based on Device Class and Sub Category if available, or Model if Device Class and Sub Category are not available:

{%- set output = [] -%}
{%- set output = device.device_class.split('|') -%}
{%- if (output[0]|trim) in ['Checkpoint', 'ScienceLogic', 'Microsoft'] -%}
{%- set output = output[1]|trim -%}
{% else %}
{%- set output = device.model -%}
{%- endif -%}
{{output}}

Filtering Device Sync by Device Group

You can use the gql_filter field on the Configuration pane of the "Sync Devices from SL1 to ServiceNow" application to add a block of JSON code that lets you define a custom filter to apply to the devices in the sync.

You cannot enter GraphQL code in the gql_filter field in PowerFlow. The field only accepts JSON.

Using GraphQL to Create the Custom Filter

In this example, you will create a custom GraphQL filter in SL1 based on Device Groups. This filter will prevent Devices that belong to specific Device Groups from creating CIs in the ServiceNow CMDB.

To create a JSON filter for the gql_filter field:

  1. Go to the GraphiQL interface in SL1 by typing the URL or IP address for SL1 in a browser, adding /gql to the end of the URL or IP address, and pressing Enter.

  2. Create a GQL query that uses a search variable, such as the following example:

    query DeviceFetch($search: DeviceSearch, $order: [ConnectionOrder], $first: Int) {
      devices(first: $first, search: $search, after: "", order: $order) {
        pageInfo {
          hasNextPage
          matchCount
        }
        edges {
          cursor
          device: node {
            ...
    
          }
        }
      }
    }
    
  3. After the query gives you the results you want, copy the resulting JSON variable definitions from the Query Variables section:

  4. Paste that JSON code into the gql_filter portion of PowerFlow and save the PowerFlow application.

JSON Code Template

Instead of using the GraphiQL user interface in SL1, you can use the following JSON code as a template for filtering based on Device Group; simply paste the code into the gql_filter field on the Configuration pane and edit the search criteria and group names as needed:

{
  "deviceGroup": {
    "has": {
      "or": [
        {
          "name": {
            "contains": "group1"
          }
        },
        {
          "name": {
            "contains": "group2"
          }
        }
      ]
    }
  }
}

Tips for customizing the JSON code:

  • To add or remove additional Device Groups, copy or delete the following block of code and edit the group name as needed:

        {
          "name": {
            "contains": "group2"
          }
        }
  • If you add additional name blocks, add a comma after each name block except for the last name block. If you delete a block, delete the preceding comma.

  • You can change the "or" to an "and" if you want to block syncing for devices that are in more than one Device Group.

  • The "contains" can be changed to "eq" to make the name an exact match. For example, "contains": "office" would match "The Office," "HQ Office," and "Office235."

Adding Device Class Mappings

You can dynamically set the device mappings on a per-run basis using the API. You can also persistently save device mappings with the API. You can find these mappings in the mappings section of the Configuration pane for the "Sync Devices from SL1 to ServiceNow" application.

The following image displays an example of using Postman to send the mapping data to PowerFlow:

This example only maps device classes to ServiceNow for VMware, SL1 devices, and a few Cisco devices. If the your environment contains other device classes, you must manually create the mappings.

To add device class mappings using Postman, POST the following JSON file to trigger the required applications in the PowerFlow user interface to model SL1 devices to ServiceNow:

{

"name": "device_sync_sciencelogic_to_servicenow",

"params": {

"mappings": {

"cmdb_ci_ip_switch":[

"Cisco Systems | Catalyst 3850-48P",

"Cisco Systems | Nexus 9372PX"

],

"cmdb_ci_linux_server": [

"ScienceLogic, Inc. | EM7 Message Collector",

"ScienceLogic, Inc. | EM7 Customer Portal",

"ScienceLogic, Inc. | EM7 All-In-One",

"ScienceLogic, Inc. | EM7 Integration Server",

"ScienceLogic, Inc. | EM7 Admin Portal",

"ScienceLogic, Inc. | EM7 Database",

"ScienceLogic, Inc. | OEM",

"ScienceLogic, Inc. | EM7 Data Collector",

"NET-SNMP | Linux",

"RHEL | Redhat 5.5"

],

"cmdb_ci_esx_resource_pool": ["VMware | Resource Pool"],

"cmdb_ci_esx_server": [

"VMware | ESXi 5.1 w/HR",

"VMware | Host Server",

"VMware | ESX(i) 4.0",

"VMware | ESX(i) w/HR",

"VMware | ESX(i) 4.0 w/HR",

"VMware | ESX(i)",

"VMware | ESX(i) 4.1 w/HR",

"VMware | ESXi 5.1 w/HR",

"VMware | ESXi 5.0 w/HR",

"VMware | ESX(i) 4.1",

"VMware | ESXi 5.1",

"VMware | ESXi 5.0"

],

"cmdb_ci_vcenter_datacenter": ["VMware | Datacenter"],

"cmdb_ci_vcenter_datastore": ["VMware | Datastore", "VMware | Datastore Cluser"],

"cmdb_ci_vcenter_dv_port_group": ["VMware | Distributed Virtual Portgroup"],

"cmdb_ci_vcenter_dvs": ["VMware | Distributed Virtual Switch"],

"cmdb_ci_vcenter_folder": ["VMware | Folder"],

"cmdb_ci_vcenter_network": ["VMware | Network"],

"cmdb_ci_vmware_instance": ["VMware | Virtual Machine"],

"cmdb_ci_vcenter": ["VMware | vCenter", "Virtual Device | Windows Services"],

"cmdb_ci_vcenter_cluster": ["VMware | Cluster"]

},

"configuration": "template_snow_integration" #name your configuration file

}

}

Persistently Saving Device Class Mappings with the API

You can persistently save device class mappings using the API.

  1. Use Postman or cURL to do a GET to load the "Sync Devices from SL1 to ServiceNow" application:

    GET PowerFlow_hostname/api/v1/applications/device_sync_sciencelogic_to_servicenow

    where PowerFlow_hostname is the IP address or URL for your PowerFlow system.

    NOTE: The response should contain the entire JSON output for the application.

  1. Copy the entire JSON code and save it to a file named: "device_sync_sciencelogic_to_servicenow".

  1. Open the file you created and locate the object with the "name":"mappings" property in the "app_variables" list. The "value" property in this object specifies the mappings to use throughout the PowerFlow applications:

  1. Modify the "value" property of the object to use the mappings you want to use.
  2. Ensure that the mappings follow the same JSON data structure, or else the sync will not work:

    {

    "cmdb_ci_class": [

    "ScienceLogic Dev Class| ScienceLogic subclass",

    "Another Silo Dev Class | Another Silo subclass"

    ]

    }

  1. After you update the mappings, use the iscli tool to upload the updated application with your new settings. Type the following command at the command line:

    iscli –uaf device_sync_sciencelogic_to_servicenow –H PowerFlow_hostname -p password

    where:

    • PowerFlow_hostname is the hostname or IP address of the PowerFlow system.
    • password is the password you use to log in to the PowerFlow system.

Checking for Missing Device Mappings

You can use the "Report: Identify Unmapped Devices Classes" PowerFlow application to check whether any device mappings are missing in your PowerFlow server.

This application pulls the class mappings from Device Sync and Attribute Sync and compares the mappings with the full list of device classes of discovered devices in SL1. The application generates a report on the Reports page that lists missing mappings, and if any device classes are unmapped, the application generates an event in the target SL1 system.

To configure the "Report: Identify Unmapped Devices Classes" application:

  1. If you do not have the "ServiceNow Base" PowerPack version 104 or later on your SL1 system, search for and download the PowerPack from the PowerPacks page on the ScienceLogic Support Site at https://support.sciencelogic.com/s/powerpacks. Install the PowerPack in SL1.
  2. In SL1, enable the "ServiceNow CMDB: Un-Mapped Device Classes" Event Policy from the "ServiceNow Base" PowerPack version 104 or later to trap the alert generated by this application.
  3. In the PowerFlow user interface, go to the Configurations page.
  4. Click the Actions button () for the configuration object you want to use with this application and select Edit. The Configuration pane for the object appears.
  5. In the Configuration Data Values section, click Add Value. A new name-value line appears.
  6. Add a configuration variable named pf_host that has a value of the externally addressable IP or fully qualified domain name (FQDN) of the PowerFlow cluster or instance.
  7. Click Save.
  8. Go to the Applications page and select the "Report: Identify Unmapped Devices Classes" application.
  9. Click Configure to open the Configuration pane:

  10. Complete the following fields, as needed:

  • Configuration. Select the configuration object you updated in steps 1-5 to align with this application. Make sure that the pf_host value that is updated on the Configuration pane is accurate. You cannot edit fields that are populated by the configuration object. Required.
  • read_timeout. Specify the maximum amount of time in seconds the application should wait for a response before timing out. The default is 20 seconds.
  • query_retries. Specify the number of times to retry this query if needed. The default chunk size is 0.
  1. Click Save. The Configuration pane automatically closes after this message appears.

  2. Click Run to run the application.

  1. After the application runs, click the Reports button and select the relevant report-missing-classes report from the Reports page. The "missing_classes" report appears:

    The report displays missing mappings for Device Sync (SL1 to ServiceNow) in the first column, and missing mappings for Attribute Sync (ServiceNow to SL1) in the second column.

    Also, if any device classes are unmapped and you enabled the "ServiceNow CMDB: Un-Mapped Device Classes" Event Policy in step 2, SL1 generates an event on the Events page in SL1:

Device Attribute Mappings

The "Sync Devices from SL1 to ServiceNow" application can also collect manufacturer and model attributes from asset records aligned with devices in SL1 and sync that information with ServiceNow. You can access these mappings in the Attribute Mappings section of the Configuration pane for that application.

These manufacturer and model attributes are different from custom attributes in SL1.

PowerFlow only populates the manufacturer and model attributes if the values exist in ServiceNow CIs; PowerFlow does not create new manufacturer values in ServiceNow. "Sync Devices from SL1 to ServiceNow" application uses the sys_id field as a reference when syncing manufacturer and model information between SL1 and ServiceNow.

Integer fields in ServiceNow have a maximum value of 2147483647. If a value exceeds that value, ServiceNow stores it as 2147483647. This is a MySQL limitation on the maximum value that can be stored in a signed integer variable.

The "Sync Devices from SL1 to ServiceNow" application only syncs assets that have a value populated in SL1. SL1 automatically populates fields in an asset record when the record is properly configured. For more information on configuring assets in SL1, see Asset Management.

Try one of the following options for the best approach for syncing manufacturer and model attributes, especially if your ServiceNow instance uses Domain Separation:

  • Add the ServiceNow user that is listed in the snow_user field on the Configuration pane of the "Sync Devices from SL1 to ServiceNow" application to the Global Domain in ServiceNow.
  • Schedule the "Sync Devices from SL1 to ServiceNow" application to run with different ServiceNow users that belong to each ServiceNow domain, using the Custom Parameters field on the schedule window to overwrite the snow_user value.

Default Device Attribute Mappings

The "Sync Devices from SL1 to ServiceNow" application contains a set of default device attribute mappings between SL1 and ServiceNow. You can access these mappings in the Attribute Mappings section of the Configuration pane for that application.

The following table describes the default device attribute mappings:

SL1 Device Attribute

ServiceNow CI Attribute

Description

"Description: {{device.device_category}}, Device Class: {{device.device_class}}": [ "short_description"

NOTE: This field requires a Jinja2 Template. For more information, see Using a Jinja2 Template.

asset_tag asset_tag
cpuCount cpu_count
cpuMake cpu_type
cpuSpeed cpu_speed
dateAdded first_discovered
diskSize disk_space
dnsDomain dns_domain
function justification
hostname fqdn, host_name
instance_uuid account_id
ip ip_address
manufacturer_sys_id manufacturer
memory ram
model_sys_id model_id
name name
operatingSystem os
purchaseDate order_date
serial serial_number
status hardware_substatus
warrantyExpirationDate warranty_expiration

SL1 Device Attributes Available for Syncing

In the Attribute Mappings section of the Configuration pane for the "Sync Devices from SL1 to ServiceNow" application, you can also use the following SL1 device attributes from SL1 when syncing attributes with ServiceNow:

  • arraySize
  • asset_id
  • asset_tag
  • company_sys_id
  • component_unique_id
  • cpuCount
  • cpuMake
  • cpuSpeed
  • dateAdded
  • depreciationMethod
  • depreciationSchedule
  • device_category
  • device_class
  • diskCount
  • diskSize
  • dnsDomain
  • dnsName
  • domain_sys_id
  • firmwareVersion
  • floor
  • function
  • hostId
  • hostname
  • ip
  • location
  • make
  • manufacturer_sys_id
  • memory
  • model
  • model_sys_id
  • name
  • operatingSystem
  • org_id
  • org_name
  • owner
  • panel
  • parent_device
  • parent_did
  • plate
  • punch
  • purchaseCheck
  • purchaseCost
  • purchaseDate
  • purchaseOrderNumber
  • rack
  • region
  • rfid
  • room
  • serial
  • serviceCheck
  • serviceCost
  • serviceDate
  • serviceDescription
  • serviceExpirationDate
  • serviceOrderNumber
  • servicePolicyNumber
  • shelf
  • sl1_id
  • sl1_url
  • snow_ci_class
  • snow_sys_id
  • status
  • vitalAssetInformation
  • vitalServiceInformation
  • warrantyCheck
  • warrantyCost
  • warrantyDate
  • warrantyDescription
  • warrantyExpirationDate
  • warrantyOrderNumber
  • warrantyPolicyNumber
  • zone

Adding New Device Attributes to ServiceNow

You can also add one or more new attributes to ServiceNow that you can then sync with SL1.

To add an attribute in ServiceNow:

  1. In ServiceNow, go to the Tables page (System Definition > Tables) and select the table to which you want to add a field for a new attribute.
  2. From the Table page, click the New button to add a new field on the table. A new record appears.
  3. From the Type drop-down list, select the data type you want to store, such as String. Depending on your selection, additional required fields display. For example, If you selected String, then Column label should contain the text you want to display in ServiceNow, and Column name is the exact column name used by PowerFlow or the API.
  4. Complete the required fields and any other fields as needed, and then click the Submit button. The field is added to ServiceNow.

Configuring Customer CI Relation Overrides

When you are mapping Device Classes and attributes, you might find that SL1 creates relationship mappings very differently than the way that ServiceNow creates relationships. As a result, ScienceLogic strongly recommends that you use the customer_ci_relation_overrides field instead of using ServiceNow to set up those relationships.

In the "Sync Devices from SL1 to ServiceNow" PowerFlow application, you can use the customer_ci_relation_overrides field to override the existing relationship linking and directly control the link between Device Classes and attributes. The customer_ci_relation_overrides field lets you build dynamic relationships rather than statically setting up relationships within ServiceNow.

ScienceLogic does not support using ServiceNow to control and set up your device relationships.

In addition, ScienceLogic strongly recommends that you use the default relationship overrides for VMware, which you can view by clicking Show JSON Configs from the Configuration pane for the "Sync Devices from SL1 to ServiceNow" PowerFlow application.

This mapping process is intended for advanced users that are familiar with how SL1 and ServiceNow construct device relationships.

In the following example, the relationship structure in SL1 is linear :

In ServiceNow, however, the structure is not as linear, and it requires an override (a manual link) between classes to make the relationship link required:

The following image shows the JSON structure formatting that is required for the customer_ci_relation_overrides field:

The values in the customer_ci_relation_overrides field supersede any of the values configured in the mappings section in the Configuration pane for the "Sync Device Classes from SL1 to ServiceNow" PowerFlow application.

You must ensure that all classes in the relationship chain in SL1 are mapped to classes in ServiceNow, or else the chain will break, and PowerFlow will not correctly apply the overrides.

In the customer_ci_relation_overrides field, you can string together multiple relationships as in the following example:

{
   "cmdb_ci_db_mssql_instance": {
       "relations": [
           {
               "parent": "cmdb_ci_win_server",
               "rel_type": "Runs on::Runs",
               "reverse": true
           }
       ],
       "values": {"sys_class_name": "snow_ci_class", "instance_name": "name"}
   },
   "cmdb_ci_db_mssql_database": {
       "relations": [
           {
               "parent": "cmdb_ci_db_mssql_instance",
               "rel_type": "Contains::Contained by",
               "reverse": false
           }
       ],
       "values": {"sys_class_name": "snow_ci_class", "database": "name"}
   },
   "cmdb_ci_db_mssql_server": {
       "relations": [
           {
               "parent": "cmdb_ci_win_server",
               "rel_type": "Runs on::Runs",
               "reverse": true
           }
       ],
       "values": {"sys_class_name": "snow_ci_class", "instance_name": "name"}
   }
}

Viewing Reports for Device Sync

The "Sync Devices from SL1 to ServiceNow" application lets you create a report about the devices that you sync with ServiceNow. The report displays on the Reports page ():

Enable the report by selecting the generate_report option on the Configuration pane for the application.

When the relevant data is present in a device sync, the report displays the following data under the Details pane:

  • Creations Sent to ServiceNow. Device information for devices in SL1 that will be created in ServiceNow.
  • Device Counts. Lists the number of created, disconnected, and updated devices, as well as the number of devices pulled from SL1 and ServiceNow during the sync. If domain separation is on and there are devices removed due to domain separation errors, that count will be added to the table.
  • Deletions Sent to ServiceNow. Device information for devices in SL1 that will be deleted in ServiceNow.
  • Post CIs to ServiceNow. Each instance of the "Post CIs to ServiceNow" application, listing creations, disconnects, errors, skips, and updates made in ServiceNow.
  • Updates Sent to ServiceNow. Device information for devices in SL1 to be updated in ServiceNow.

Log Messages for the "Generate Required CI Relations for ServiceNow" Application

This section describes the different types of log messages you might see in the Step Log when you run the "Generate Required CI Relations for ServiceNow" application. Please note that this application is a report used by PowerFlow, and it does not send any data to ServiceNow.

The following message displays if there are devices in a device tree that do not currently have a CI class mapping assigned.

Warning: 2751 Relations with missing mappings detected. Please re-run app with log level 10 to troubleshoot.

In this situation, the device tree cannot be built in ServiceNow. To address this issue, make sure that you have your entire technology tree mapped out in the mappings section of the "Sync Devices from SL1 to ServiceNow" application or in the mappings section of the "Generate Required CI Relations for ServiceNow" application.

If you do a Custom Run of the "Generate Required CI Relations for ServiceNow" application in Debug mode (log level 10), the application will create a log that displays the parent and child class, CI, and device ID. For example:

Debug: Missing Mapping for Device. Parent: {"class": "VMware | Cluster", "ci": None, "id": 76}, Child: {"class": "VMware | Host Server", ci: "cmdb_ci_esx_server", id: 363 }

The following message appears if the GraphQL payloads had bad data for parent and or child devices:

Warning: 10 bad payloads received from SL1. Re-run app in debug to troubleshoot.

If you do a Custom Run the application in Debug mode, the application will create a log that displays these payloads.

The following message appears if all relations are mapped:

Flow: No missing relations found!

The following message appears if there is a parent/child relation between ServiceNow CI classes that does not currently exist in ServiceNow and is required to sync those devices:

Flow: Missing Relations: [{"parent": "cmdb_ci_vcenter_folder", "child": "cmdb_ci_esx_server"}, {"parent": "cmdb_ci_vcenter", "child": "cmdb_ci_vcenter_datacenter"}]

Refer to the labels in the log (above) to determine which CI class is the parent type and which is the child type. To address this issue, navigate to your ServiceNow instance and create the required service rules based on the recommendations in the Step Log.

The following message appears if the application encounters a list of relations that are required, but were successfully found in ServiceNow:

Info: Found Relations: [{"parent": "cmdb_ci_vcenter_folder", "child": "cmdb_ci_esx_server"}, {"parent": "cmdb_ci_vcenter", "child": "cmdb_ci_vcenter_datacenter"}]

This message lets you verify that your mappings and relations are configured correctly.