Topology Population Flow

The adapter’s population works by receiving a structure from the expected topology from the UCMDB platform or framework. The structure is tree-like, containing the root node, children and the table’s attributes.

Based on that, the population processes the results in the following order:

1. The Root node
2. The Child nodes
3. Recursively process (if any) children of the child nodes.

Procuring the root node from ServiceNow almost always employs the same mechanism – a query is formed to the required table that gets all of the records from the table. Inside the URL, it should be specified which attributes or fields it expects from ServiceNow.

The adapter then forms a list of Result Tree Nodes (RTNs) which are the representation that UCMDB expects for the CIs.

If there are child elements, they are assigned or linked to their parent element. As a result, the list of RTNs that the adapter returns will contain the entire topology.

Specifics about how parents are related to children are later determined by the UCMDB framework based on the mapping files and original TQL query.

Standard (Referenced) Population

The standard population is the mode that the adapter used before the changes in this version. It can be summed up with the following:

1. Procure the root node for certain ServiceNow tables with required attributes. Store the results in the cache for the specific table.

   Example URL:

   api/now/table/<parent_table>?sysparm_fields=<fields_required_by_attributes>

2. If any children are specified, procure them from ServiceNow. The call should also request the attribute of the children that references the parent’s sys_id. In the ServiceNowConfig.xml file, this is the childCiTargetTableField attribute. The adapter filters only those children whose childCiTargetTableField references the parent’s sys_ids from the last step. The parent’s sys_ids are contained in the cache.

   Example URL:

   api/now/table/<child_table>?sysparm_fields=<fields_required_by_attributes>&sysparm_query=<childCiTargetTableField>IN<parent_sys_ids_from_previous_step>

3. Based on the values of the attribute mentioned above, the adapter finds request for the parent’s table from the cache, and then fetch the parent RTNs that match the children’s sys_ids.
4. Assign the respective children to the respective parent CIs.

Referencing topology Population

Referencing is essentially the same as standard population; however, the difference is that the parent CIs are not determined by the sys_id field, but rather by a custom field that can be defined in the ServiceNowConfig.xml as parentRef. The configuration looks like as follows:

<ci ciType="business_service" targetTable="cmdb_ci_service">

  <relations>

   <relation childCiType="person" type="ConsumerProvider" populationType="referencing" childCiTargetTableField="owned_by"/>

  </relations>

</ci>

<ci parentRef="owned_by" ciType="person" targetTable="sys_user"> 

</ci>

The population flow is as follows:

1. Procure the root node. This step determines if any of the children of the root node should be procured using referencing topology. If there are any, get their parentRef value from the configuration. Then request the value of the parentRef field from ServiceNow. This is the field that will be used to get the children at the next stages.

   Example URL:

   api/now/table/<parent_table>?sysparm_fields=<fields_required_by_attributes+parentRef_fields_of_children>

2. Go over the parent’s parentRef fields and collect the children’s sys_ids. Then use these sys_ids to get the children from ServiceNow.

   Example URL:

   api/now/table/<child_table>?sysparm_fields=<fields_required_by_attributes>&sysparm_query=sys_idIN<parentRef_field_values_from_previous_step>

3. Match the child entries to the parent by the parentRef values. The parent’s parentRef field should equal the child’s sys_id. Once the RTNs are assembled, they are ready to return.
4. In certain cases, the ServiceNow topology and UCMDB topology have the inverse direction of the relationship. Therefore, you can keep the parent and child that you want in the adapter, and still get the proper result after the mapping is finished.

Relationship Topology Population

Relationship topology population relies on a prerequisite during the adapter startup that the adapter loads the the cmdb_rel_ci table.

1. Prerequisite

   During the adapter startup, the cmdb_rel_ci table table is loaded from ServiceNow. On the first launch, the table is always fetched from ServiceNow. However, on any subsequent launches, the adapter checks if the size of the table in ServiceNow is the same as that of your file. If not, the adapter updates it.

2. Configuration for relationship topology in the ServiceNowConfig.xml looks like as follows.

   <ci ciType="business_application" targetTable="cmdb_ci_appl">

     <relations>

       <relation childCiType="node" type="usage" populationType="relationship" reverseParenthood="false" targetRelType="Runs on::Runs"/>

       <relation childCiType="unix" type="containment" populationType="relationship" targetRelType="Runs on::Runs"/>

     </relations>

   </ci>

   <preloaded_types>

     <relationship_type name="Runs on::Runs" />

       <relationship_type name="Owns::Owned by" />

   </preloaded_types>

   targetRelType indicates the direction of the relationship in ServiceNow. It can be between the parent CI type (in this case cmdb_ci_appl) and the child CI type (Node or UNIX).

   The preloaded types must match the ones used as targetRelType in Prerequite. This happens after the adapter is initially loaded.

3. Fetching the root CI happens just like in standard mode.

   Example URL:

   api/now/table/<parent_table>?sysparm_fields=<fields_required_by_attributes>

4. After the root CI properties are discovered, if populationType is relationship, the flow is as follows:

   1. Get the relationship between parent and child.
   2. Filter out only those entries in the cmdb_rel_ci table cache that use this relationship.
   3. If reverseParenthood is set to true, match all the IDs from the step 3 to the IDs in the child column of the cmdb_rel_ci table, and then take the IDs from the parent column.
   4. If reverseParenthood is set to false, match all the IDs from step 3 to the IDs in the parent column of the cmdb_rel_ci table, and then take the sys_ids from the child column.

5. At the end of either step 4c or 4d, the job has a list of the child IDs getting from ServiceNow. They are then requested using a filter by sys_id.

   Example URL:

   api/now/table/<child_table>?sysparm_fields=<fields_required_by_attributes>&sysparm_query=sys_idIN<ids_from_step_4>