Mappings Services to CMDB

Introduction

The Service Mapping tab allows you to specify the CMDB table to write service information to as well as the Resolve Insights service fields that you want to synchronize. You can also enable or disable mappings after you create them.

Default Mappings

The Service Mappings table includes a number of mapping 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.

Creating 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 duplicating mappings as long as only one of them is enabled. Insights determine duplicates by the combination of these fields: CMDB System, App Role, App Service.

Take these steps to create a service mapping:

1. Go to Settings > CMDB Mappings > Service Mappings.
2. Click Add New.
3. On the Service Field Mapping page, fill in the following fields:
   • Table Name - The name of the CMDB table to which you want to push data from Insights. Example: cmdb_ci_appl_active_directory
   • CMDB System - Select the CMDB system to push to.
   • App Role - Optional. 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.
   • App Service - Optional. 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.
   • Mandatory Fields - Optional. 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 the plus sign. Non-existing fields will have null as a value in the request response.
   • Restricted Fields - Optional. Enter a list of service 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 and then click the plus sign.
   • Enable Mapping - Switch the toggle if you want to enable the mapping as soon as you create it.
4. Click Continue.
5. (Optional) On the Field Mapping page, map service fields to target CMDB fields.
   Repeat to add as many fields as you need.
6. Click Save & Complete.
7. (Optional) Back at the Service Mapping table, test your mapping.

Testing a Service 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.

Take these steps to test a mapping:

1. Go to Settings > CMDB Mappings > Service Mappings.
2. In the mapping's Actions column, click the Test Mapping icon.
   The Test Mapping dialog box appears.
3. In the Device Id field, enter the ID of a device from your inventory and click Test Mapping.
   Example: c9e1f205-a07f-4cb4-9d84-700bd1d1dac1
4. 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 > Table View page, click Columns and then check Device Id.

Editing a Service Mapping

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

Take these steps to edit a service mapping:

1. Go to Settings > CMDB Mappings > Service Mappings.
2. In the mapping's Actions column, click the Edit (pencil) icon.
3. Edit the fields as necessary:
   • For editing the settings on the Service Field Mapping tab, refer to Creating a Service Mapping.
   • For editing the settings on the Field Mapping tab, refer to Mapping Service Fields.
4. Click Save & Close.
5. (Optional) Back at the Service Mapping table, test your mapping.

Mapping Service Fields

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 service fields during the initial service mapping creation or later when editing a mapping.

On the Field Mapping page, use the controls described below to create a service field mapping.

Starting and Saving a Field Mapping

Click the Add New Field button to open a new device field mapping form. You can add as many field mappings as you like.

Click the Save Field button on the form to save the mapping.

Specifying the CMDB Field Name

In the CMDB Field Name text field, enter the exact name of the target table field as it appears in your CMDB.

Specifying the Insights Field Name

You have two alternative options to specify the Insights field name that you want to map to CMDB Field Name. Use the radio buttons to select one of the following options:

• 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:
  • Insights Field - Enter the name of the Elasticsearch field that you are mapping.
  • Fallback Field - Enter the name of an Elasticsearch field to read the value from if the Insights Field is null.
  • Default Value - Enter a value to be used in case neither Insights Field nor Fallback Field contains a value.
  • Overridding Value - Enter a value to be used regardless of what value is found in Insights Field.
• Use Script - Choose this option to provide a Painless script to extract field data from the Elasticsearch database to map to the CMDB field. The following field appears:
  • Painless Script - 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;
}

Modifying the Insights Field

After specifying the Elasticsearch field using the Insights Field or Use Script options, you can optionally use various operators to modify the value of the field before pushing it to the CMDB.

Check Use Operator to enable value modification.

Conditional Operator

Use this operator to modify the pushed value if it is found or not found in the Elasticsearch field.

Fill in the form as follows:

• If the value of the "Mapping" is equal to - Enter the value that you expect to appear in the Elasticsearch field. Only single values are supported.
• Use value - Enter the substitute value to be pushed to the CMDB if the value in If the value of the "Mapping" is equal to is found.
• Else, use value - Optional. Enter the substitute value to be pushed to the CMDB if the value in If the value of the "Mapping" is equal to is not found.

Example: If the value of devSubType is equal to Bare Metal, push Physical Appliance, else push Virtual Appliance.

Split Operator

Use this operator when you want to push only a part of the value found in Elasticsearch.

• Use as separator - Enter a character or a string at which to split the Elasticsearch value into several parts.
• Limit the maximum parts to split to - 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 integrated within 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.

Example: To extract the subnet and machine part of a 172.16.x.x IPv4 address, enter . as a separator, 3 as a limit and then return part number 3, which should yield you the x.x part.

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 in the Use Operator section.

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

• Lookup Table Name - Enter the name of the CMDB table where you want to search for the value.
• Lookup Table Field - Enter the name of the CMDB table field to look in.
• Lookup Value Operator - Optional. Use various operators to modify the lookup result before pushing it to the CMDB.
  • Conditional - Use this operator to modify the pushed value when a particular value is found or not found in the lookup result.
    • If the value of the "Mapping" is equal to - Enter the value that you expect to appear in the lookup result.
    • Use value - Enter the substitute value to be pushed to the CMDB if the value in If the value of the "Mapping" is equal to is found.
    • Else, use value - Enter the substitute value to be pushed to the CMDB if the value in If the value of the "Mapping" is equal to is not found.
  • Split - Use this operator when you want to push only a part of the lookup result.
    • Use as separator - Enter a character or a string at which to split the lookup result into several parts.
    • Limit the maximum parts to split to - 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.

Deleting Service Mappings

You can delete one or more device mappings simultaneously.

To delete mappings, check their boxes in the first table column and then click Delete.

Enabling and Disabling Service Mappings

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

To disable a mapping, switch the toggle in the Enable column.