CMDB Mappings

Introduction

When pushing inventory data from Resolve Insights to your CMDB of choice, the data might not map perfectly between the two systems. The CMDB Mappings settings page allows you to appropriately map the Insights data into your CMDB.

You can map the following Insights resources to CMDB:

• Devices
• Services
• Applications

The CDMD Mappings allows you to specify the CMDB table to write device information to, as well as the Resolve Insights device fields that you want to synchronize. You can also enable or disable mappings after you create them.

Insights provides many default device, service, and application mappings suggestions to help you more easily configure the mappings that you want. You can edit a mapping to customize it for your needs, you can delete it, or you can disable it.

If you can't find the mapping you want, you can create new mappings.

Create a Mapping

note

You can select one of the existing mappings as a template and edit it directly.

Create a Device Mapping

Creating allows you to configure a mapping for a new combination of the Insights table, CMDB system, device type, and all the other device data fields.

You can create duplicate mappings as long as only one of them is enabled. Insights determine duplicates by the combination of CMDB System, Platform, Device Type, and Device Sub Type.

1. Navigate to CMDB > Device Mappings
2. Click + Add Device Mapping
3. Under the Device Mappings tab, provide the following details:
   • Table Name - The name of the CMDB table to which you want to push data from Insights. Example: cmdb_ci_server.
   • CMDB System - Select the CMDB system to push to.
   • (Optional) Platform - Filter by platform: Only devices that run on the specified platform will match the mapping. Enter the device's platform, such as LINUX or SUNOS, as it appears in the Inventory.
   • (Optional) Device Type - Filter by device type: Only devices that have the specified device type will match the mapping. From the list, select the device type that you want this mapping to match, such as Storage or Cloud.
   • (Optional) Device Sub Type - Filter by device subtype: Only devices that have the specified device subtype will match the mapping. From the list, select the device sub-type that you want this mapping to match.
   • (Optional) Mandatory Fields - Used only with the Use Script field mapping option. Enter the list of Elasticsearch fields that must be included in the initial table query. To require a field, enter its name as it appears in Elasticsearch and then click Enter. Non-existent fields will have null as a value in the request response.
   • (Optional) Restricted Fields - Enter a list of device fields that you don't want pushed to the CMDB even if they are mapped. To restrict a field, enter its name as it appears in Elasticsearch or as it appears in your CMDB system, and then click Enter.
   • Enable Mapping - Switch the toggle if you want to enable the mapping as soon as you create it.
4. (Optional) Under the Field Mapping tab, map device fields to target CMDB fields. Repeat to add as many fields as you need.
5. Click Create
6. (Optional) Back at the Device Mapping table, test your mapping

Create a Service Mapping

Creating allows you to configure a mapping for a new combination of the Insights table, CMDB system, application role, and all the other service data fields.

You can create duplicate mappings as long as only one of them is enabled. Insights determines duplicates by the combination of these fields: CMDB System, App Role, and App Service.

1. Navigate to CMDB > Service Mappings
2. Click + Add Service Mapping
3. Under the Service Mappings tab, provide the following details:
   • Table Name - The name of the CMDB table to which you want to push data from Insights. Example: cmdb_ci_server.
   • CMDB System - Select the CMDB system to push to.
   • (Optional) App Role - Filter by application role: Only services that have the specified application role will match the mapping. Enter the application role as it appears in Insights, such as Database or Oracle FMW.
   • (Optional) App Service - Filter by service name: Only services that have the specified service name will match the mapping. Enter the service name as it appears in Insights, such as MySQL or `FMW OSB Server.
   • (Optional) Mandatory Fields - Used only with the Use Script field mapping option. Enter the list of Elasticsearch fields that must be included in the initial table query. To require a field, enter its name as it appears in Elasticsearch and then click Enter. Non-existent fields will have null as a value in the request response.
   • (Optional) Restricted Fields - Enter a list of device fields that you don't want pushed to the CMDB even if they are mapped. To restrict a field, enter its name as it appears in Elasticsearch or as it appears in your CMDB system, and then click Enter.
   • Enable Mapping - Switch the toggle if you want to enable the mapping as soon as you create it.
4. (Optional) Under the Field Mapping tab, map device fields to target CMDB fields. Repeat to add as many fields as you need.
5. Click Create
6. (Optional) Back at the Service Mapping table, test your mapping

Create an Application Mapping

Creating allows you to configure a mapping for a new combination of the Insights table and CMDB system fields.

You can create duplicate mappings as long as only one of them is enabled. Insights determines duplicates by the CMDB System field - you can only have one active mapping for a given CMDB system.

1. Navigate to CMDB > Application Mappings
2. Click + Add Application Mapping
3. Under the Application Mappings tab, provide the following details:
   • Table Name - The name of the CMDB table to which you want to push data from Insights. Example: cmdb_ci_server.
   • CMDB System - Select the CMDB system to push to.
   • (Optional) Mandatory Fields - Used only with the Use Script field mapping option. Enter the list of Elasticsearch fields that must be included in the initial table query. To require a field, enter its name as it appears in Elasticsearch and then click Enter. Non-existent fields will have null as a value in the request response.
   • (Optional) Restricted Fields - Enter a list of device fields that you don't want pushed to the CMDB even if they are mapped. To restrict a field, enter its name as it appears in Elasticsearch or as it appears in your CMDB system, and then click Enter.
   • Enable Mapping - Switch the toggle if you want to enable the mapping as soon as you create it.
4. (Optional) Under the Field Mapping tab, map device fields to target CMDB fields. Repeat to add as many fields as you need.
5. Click Create
6. (Optional) Back at the Application Mapping table, test your mapping

Create Fields Mapping

Field mapping allows you to more granularly match the Insights data to the CMDB table structure. You can specify which target table field will store each Insights table field.

You can map device fields during the initial device, service, or application mapping creation or later when editing a mapping.

1. Click the + Add Field Mapping button to open a new field mapping form. You can add as many field mappings as you like.
2. Enter the exact Name of the target table field as it appears in your CMDB.
3. Choose the Mapping Type
   1. Insights Field - Choose this option to manually specify the details of the Elasticsearch field that you want to map to the CMDB field. The following fields appear:
      • Name - Enter the name of the Elasticsearch field that you are mapping.
      • (Optional) Fallback Field - Enter the name of an Elasticsearch field to read the value from if the Insights field value is null.
      • (Optional) Default Value - Enter a value to be used in case neither the Insights field nor the Fallback field contains a value.
      • (Optional) Overriding Value - Enter a value to be used regardless of what value is found in the Insights field.
   2. Painless Script - Choose this option to provide a Painless script to extract field data from the Elasticsearch database to map to the CMDB field. Enter the Painless script code that returns an Elasticsearch field value. Using a script is useful when you want to create a JSON object that closely matches the data structure expected by your CMDB.

Painless script example:

if (doc.containsKey('hostName') && doc['hostName'].value != null) {
    def hostName = doc['hostName'].value;
    def match = hostName + '.';
    def resultMatch = hostName;
    def found = false;
    if (doc.containsKey(params.meridianFieldName) && doc[params.meridianFieldName].value != null) {
        if (doc[params.meridianFieldName].length == 1) {
            resultMatch = doc[params.meridianFieldName][0]
        } else {
            for (s in doc[params.meridianFieldName]) {
                if (s.startsWith(match)) {
                    if (!found) {
                        resultMatch = s;
                        found = true;
                    } else {
                        resultMatch = hostName;
                        break;
                    }
                }
            }
        }
    }
    return resultMatch;
}
if (params.fallBackFieldName != null && doc.containsKey(params.fallBackFieldName)) {
    return doc[params.fallBackFieldName].value;
}

3. Choose Operations - Optionally use various operators to modify the value of the field before pushing it to the CMDB.
   1. Conditional - Use this operator to modify the pushed value if it is found or not found in the Elasticsearch field.
      • IF the Mapping value = - Enter the value that you expect to appear in the Elasticsearch field. Only single values are supported.
      • THEN - Enter the substitute value to be pushed to the CMDB if the value in IF the Mapping value = is found.
      • ELSE - Enter the substitute value to be pushed to the CMDB if the value in IF the Mapping value = is NOT found. Example: If the value of devSubType is equal to Bare Metal, push Physical Appliance, else push Virtual Appliance.
   2. Split - Use this operator when you want to push only a part of the value found in Elasticsearch.
      • Split Mapping Value by - Enter a character or a string at which to split the lookup result into several parts.
      • Number of parts to split - Specify how many parts you want to end up with, starting on the left. For example, if you specify 4, Insights will do three splits at the first three separators it finds. All further instances of the separator will remain part of the fourth part.
      • Return part - Enter the number of the part that you want to return. Parts are numbered from left to right starting at 1.
4. Click Save to record the field mapping.

Querying for CMDB Row ID

note

CMDB lookups are only supported with ServiceNow.

Another way to modify the value found in Elasticsearch is to use it to query a specific table inside your CMDB and request the ID of the matching row (or the primary key). The final value to be pushed to the CMDB will be the matching row ID.

When using lookups, the original Elasticsearch value is first subjected to the Operations section.

To configure a lookup, fill in the options in the Lookup Field optional section.

• Table Name - Enter the name of the CMDB table where you want to search for the value.
• Table Field - Enter the name of the CMDB table field to look in.
• (Optional) Lookup Operations - Use various operators to modify the lookup result before pushing it to the CMDB.

Edit a Device, Service, or Application Mapping

You can edit all details of a mapping, including the table mapping and the field mapping.

1. Navigate to CMDB > Device/Service/Application Mappings.
2. Choose the mapping that you want to edit and click on the Edit (pencil) icon under the Actions column.
3. Apply the changes for the selected mapping
   • For editing the settings on the Device Mapping, the Service Mapping or the Application Mapping tabs, refer to Create a Mapping
   • For editing the settings on the Field Mapping tab, refer to Create Fields Mapping.
4. Click Save.

Test a Device, Service, or Application Mapping

You can test-run a mapping after you create one or edit an existing mapping. The test run ensures that you have set the mappings properly on the Insights side, but does not test your connection with the CMDB or if the CMDB table and field names that you provided are correct.

1. Navigate to CMDB > Device/Service/Application Mappings.
2. In the mapping's Actions column, click the Test Mapping icon.
3. Enter the Device Id of the test device from your inventory or select the application name from the drop-down list
4. Click Test.
5. Check the returned record.
   You should see the filtered Insight record the way it will be pushed to the CMDB, with all mapping options applied.
   note

   To let you more easily read the data when testing Cherwell mappings, the screen shows the Cherwell column names instead of the Cherwell column IDs. In the actual push request sent to Cherwell, however, column names are replaced with the corresponding column IDs.

tip

To find the device ID on the Inventory > Devices page, click Columns and then check Device ID.

Enable or Disable a Device, Service, or Application Mapping

You can enable or disable mappings one at a time. Insights ignores disabled mappings when pushing service data to the CMDB, but you can still test disabled mappings.

1. Navigate to CMDB > Device/Service/Application Mappings.
2. Use the Enable/Disable toggle under the Actions column for the mapping that you want to change.

Delete a Device, Service, or Application Mapping

1. Navigate to CMDB > Device/Service/Application Mappings.
2. Depending on the number of mappings that you want to delete, do the following:
   • If deleting a single mapping, in the Actions column for the mapping, click the Delete (trashcan) icon.
   • If deleting multiple mappings, select their respective rows in the table and click the Delete button.