Configuration

The ServiceNow enhanced generic adapter configuration is split into three parts: integration point configuration, adapter.properties configuration, and ServiceNowConfig.xml. For details about integration points configuration, see Create the integration point.

adapter.properties Configuration

This configuration contains various enable/disable features specific to the adapter itself. The configuration resides in the following file:

<adapter package>\discoveryConfigFiles\ServiceNowGenericAdapter\adapter.properties

The following properties are supported at the moment:

• connector.class

  This property specifies the class name of the underlying connector used for communicating to ServiceNow. At the moment only REST connector implementation is supported.

  connector.class=com.hpe.ucmdb.adapters.snow.connector.ServiceNowRestConnector

• push.connector.class

  This property specifies the class name of the underlying connector used for push job only. The supported values are com.hpe.ucmdb.adapters.snow.connector.ServiceNowRestConnector and com.hpe.ucmdb.adapters.snow.connector.ServiceNowSoapConnector. In case this property is not specified then the value of the connector.class property is used.

• SOAP connector internal properties

  These are the standard JAVA SAAJ properties that specify the SOAP SAAJ implementation used for the SOAP connector. Users can use the one that is available on their system. The default implementation used in development is specified by these properties:

  javax.xml.soap.SOAPConnectionFactory=com.sun.xml.internal.messaging.saaj.client.p2p.HttpSOAPConnectionFactory

  javax.xml.soap.MessageFactory=com.sun.xml.internal.messaging.saaj.soap.ver1_1.SOAPMessageFactory1_1Impl

  javax.xml.soap.MetaFactory=com.sun.xml.internal.messaging.saaj.soap.SAAJMetaFactoryImpl

• Retry Policy Properties

  These properties control the call retries in case there is a connection outage or the server is temporarily unavailable. connector.retry.count specifies the maximum number of retries. The default value is 3 in case this property is not specified. connector.retry.interval specifies the interval in seconds between two calls. The default value is 60 seconds.

  connector.retry.count=3

  connector.retry.interval=60

  The property connector.retry.statuses lists HTTP status codes that act like the triggers for the retry mechanism to be started. By default, it lists as follows.

  connector.retry.statuses=408,503,-1

  • 408 – Request Timeout – The 408 Request Timeout error is an HTTP status code that means the request that you send to the website server (for example, a request to load a web page) takes longer than the website's server is prepared to wait.
  • 503 – Service Unavailable – This response code is received whenever the web server currently cannot handle the HTTP request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. Some servers in this state may also simply refuse the socket connection, in which case a different error may be generated because the socket creation timed out.

  • -1 – This response code is received whenever the instance is unreachable.

  Custom error codes can be added to the adapter.properties file if you want to do so.

• population.return.global_id

  Set this feature to false in case you do not want the adapter to update the ServiceNow correlation_id fields with generated UCMDB global_id values for populated CIs. See Population Flow for more information. The default value is true.

• class.model.coalesce.field

  This property contains the field used for the reconciliation on ServiceNow side (see CI Reconciliation). In the push and population mapping files this field must be set to UCMDB global_id value. If not specified, the default value is correlation_id.

• class.model.table.prefixes

  This property contains a comma separated list of prefixes of all the ServiceNow tables that should compose external class model. The default and strongly recommended prefixes are cmdb_ci, cmdb_rel_ci, cmdb_rel_type, sys_import_set_row and ucmdb_integ_. But users can change this list in whatever way they can. For more information, see External Class Model Flow .

• class.model.incremental.update

  Set this value to true to perform the incremental class model update, or set it to false to disable the incremental class model update. See Incremental Update for more details.

• adapter.logger

  Specifies the adapter specific logger name. Enable the adapter log to isolate the logs coming from this adapter from all other logs on the probe. In order to achieve this, you need to add additional entries in the <DataFlowProbe_Install_Dir>\conf\log\fcmdb.properties file.

  In the given example if we need to enable the TRACE logging and we don’t want to affect other adapter loggers we can specify this property in adapter.properties file:

  adapter.logger=servicenow.generic.adapter

  With this property set, we add the following entries in the <DataFlowProbe_Install_Dir>\conf\log\fcmdb.properties file:

  log4j.category.servicenow.generic.adapter=TRACE,servicenow.generic.adapter.appender

  log4j.appender.servicenow.generic.adapter.appender=com.mercury.topaz.cmdb.shared.base.log.BetterRollingFileAppender

  log4j.appender.servicenow.generic.adapter.appender.File=${logs.dir}/servicenow.generic.adapter.log

  log4j.appender.servicenow.generic.adapter.appender.MaxFileSize=10240KB

  log4j.appender.servicenow.generic.adapter.appender.MaxBackupIndex=${def.files.backup.count}

  log4j.appender.servicenow.generic.adapter.appender.layout=org.apache.log4j.PatternLayout

  log4j.appender.servicenow.generic.adapter.appender.layout.ConversionPattern=${msg.layout}

ServiceNowConfig.xml Configuration

This configuration contains the business logic information specific to certain jobs. It resides in the following file:

<adapter package>\discoveryConfigFiles\ServiceNowGenericAdapter\ServiceNowConfig.xml

Here is an example of this file:

<config>
    <ciTypeMappings>
        <ci ciType="disk_device" stagingTable="ucmdb_integ_ci_storage_device" targetTable="cmdb_ci_storage_device">
        </ci>
        <ci ciType="file_system" stagingTable="ucmdb_integ_ci_file_system" targetTable="cmdb_ci_file_system">
        </ci>
        <ci ciType="interface" stagingTable="ucmdb_integ_ci_network_adapter" targetTable="cmdb_ci_network_adapter">
            <relations>
                <relation childCiType="ip_address" type="containment" childCiTargetTableField="nic" />
            </relations>
        </ci>
        <ci ciType="ip_address" stagingTable="ucmdb_integ_ci_ip_address" targetTable="cmdb_ci_ip_address">
        </ci>
        <ci ciType="nt" stagingTable="ucmdb_integ_ci_win_server" targetTable="cmdb_ci_win_server">
            <relations>
                <relation childCiType="interface" type="composition" childCiTargetTableField="cmdb_ci" />
                <relation childCiType="file_system" type="composition" childCiTargetTableField="computer" />
                <relation childCiType="disk_device" type="composition" childCiTargetTableField="computer" />
            </relations>
        </ci>
        <ci ciType="containment" stagingTable="ucmdb_integ_rel_ci" targetTable="cmdb_rel_ci">
        </ci>
        <ci ciType="composition" stagingTable="ucmdb_integ_rel_ci" targetTable="cmdb_rel_ci">
        </ci>
    </ciTypeMappings>
    <populationQueries>
        <tql name="SNOW Biz Containment Biz 1.0"/>
        <tql name="SNOW Windows Population 1.0"/>
    </populationQueries>
</config>

For the current adapter version, this configuration contains these types of data:

• List of Population Queries

  When we create a new pair of population TQL and mapping file, in order to display this TQL in “Add Query” dialog of the “Edit Integration Job” action for the integration point we need to add the TQL name in this list of population queries.

• CI/Relation Type Mappings

  These mappings help push and population jobs in determining the correct mapping of UCMDB CI/relation type to ServiceNow staging table and target table.

  Let’s consider the Windows CI push to ServiceNow. In the example above we can see that UCMDB CI type nt has the corresponding ServiceNow staging table ucmdb_integ_ci_win_server and target table cmdb_ci_win_server. Also it has 3 CI types related to it: interface, file_system and disk_device. In the same way we can see that CI type interface has the corresponding ServiceNow staging table ucmdb_integ_ci_network_adapter and target table cmdb_ci_network_adapter.

  In the push job, the CIs are mapped to staging tables. However, the deleted CIs from UCMDB need to be deleted from target table. For every staging table the adapter tries to read the target table from this configuration (see Push Integration Mechanism). If the mapping is not there, then deletion is not performed.

  Furthermore, if the corresponding child-parent field mapping is not specified in the XML mapping file (see Push Integration Mechanism), then the adapter tries to find the child-parent relation field in this configuration. In the example above, in the defined relation from nt to interface, we can also see the attribute childCiTargetTableField="cmdb_ci". This attribute points to the ServiceNow child table field that points to the parent table. In this case the ServiceNow relation is defined by the cmdb_ci_network_adapter.cmdb_ci field that points to parent table cmdb_ci_win_server. The adapter assigns the parent CI sys_id value generated by ServiceNow to the specified field of the child CI right before it pushes it to ServiceNow.

  The opposite of push is the population job. For the populated CI when the adapter needs to push the generated UCMDB global_id value back to ServiceNow correlation_id field, from UCMDB it only receives the UCMDB CI type information about the CI along the sys_id and global_id (see CI Reconciliation). Using this mapping the adapter can deduce the ServiceNow table to update for the specified CI type. However, if the corresponding mapping in this file is not specified then the adapter assumes that the table to update is cmdb_ci which is correct since all CMDB tables in ServiceNow extend cmdb_ci table.