ServiceNow integration¶

Introduction¶

The OctoSAM to ServiceNow integration module provides inventory information to the ServiceNow CMDB. In comparison with the SCCM integration, the OctoSAM integration provides cleaner and more complete information:

OctoSAM Inventory collects much more data about each machine than SCCM, all this data is potentially available to import into ServiceNow. On a typical windows client computer, more than 1000 attributes are collected.
OctoSAM Inventory is an inventory system at its heart, while SCCM inventories only as much information as is needed for its operation
OctoSAM normalizes data using its extensive software catalog and other mechanisms
OctoSAM supports not only Windows but also VMware ESX, Linux and Mac computers
OctoSAM can provide vital licensing information from your virtualization infrastructure
OctoSAM implements on its side specific mechanisms and data structures for ServiceNow integration, while SCCM does not.
OctoSAM ServiceNow integration is optionally bi-directional, data flows in both directions where as with SCCM you can only synchronize one way.
Using OctoSAM inventory as a source of truth gives you all the additional functionality of OctoSAM in addition to the ServiceNow CMDB
Links to the detailed information in the OctoSAM web interface can easily be integrated in ServiceNow
For in-depth analysis you can always switch to the real desktop application experience of the OctoSAM GUI
Your detailed inventory information stays in-house but is in sync with the cmdb in ServiceNow for essential information

Architecture¶

The OctoSAM integration has two elements: Synchronization from OctoSAM to ServiceNow and optionally synchronization in the opposite direction, from ServiceNow to OctoSAM.

Synchronization from OctoSAM to ServiceNow is done using the traditional Data Source, Import Set, Transform Map mechanism of ServiceNow. This provides full flexibility to configure synchronization of items and attributes according to your needs. Starting with Orlando you can also use the more flexible Robust Transform Engine (RTE) for import.

Data is exported from OctoSAM as a compressed .XML file that can be imported via all supported ServiceNow mechanisms. This has several advantages compared with the JDBC approach that some other integration implementations use:

The import process is not dependent on the availability of the OctoSAM database
The OctoSAM export is consistent within itself. Using multiple JDBC queries one after an other can lead to inconsistent data - the situation where you have a software installation for a computer that is not yet available.
The export can be made at a point in time where all information is up to date, that usually means right after OctoSAM housekeeping.
Internal changes to the OctoSAM database do not alter the integration interface as long as the format of the file can be maintained
No inward bound JDBC connection from the MID server to the OctoSAM database needs to be opened.

Synchronization from ServiceNow to OctoSAM is done using the standard ServiceNow REST table API.

The two way synchronization allows OctoSAM to write key information from ServiceNow into its own database for later analysis. Also when using multiple sources for your CMDB it can provide another means to check if OctoSAM scans all expected systems.

Multiple ServiceNow instances¶

OctoSAM supports export of data to multiple ServiceNow instances but supports import only from one ServiceNow instance per OctoSAM database. If you need to set up full end-to-end integration between test instances of ServiceNow and OctoSAM, you need to set up additional OctoSAM databases for each ServiceNow instance. If your test instance is a perfect clone of a production instance, you can also just clone/copy the OctoSAM database. However, if your test ServiceNow instance data differs (you have ci_item records with different sys_ids or OctoSAM IDs) you need to maintain a separate OctoSAM installation that reflects the configuration of your ServiceNow instance.

Tables and columns¶

Naming and format conventions¶

OctoSAM uses the ServiceNow name and format of a column if there is a direct match. This allows to generate the best part of the transform map automatically.

Some fields do not have a direct match with ServiceNow, but may be useful for the transform configuration. Fields starting with u_ are provided by OctoSAM and can be automatically mapped if the target table provides extension fields with the same name.

Columns of type reference point to other tables in ServiceNow. They usually require some additional considerations during transform.

Required columns in ServiceNow¶

OctoSAM Integration with the ServiceNow CMDB requires that you crate a column named u_octosam_id in the Configuration Item table cmdb_ci. Additionally, if you want to sync software installations with the ServiceNow SAM module, you need to create a column u_octosam_id in the Software Install table cmdb_sam_sw_install

Table	Label	Name	Type	Length
cmdb_ci	OctoSAM ID	u_octosam_id	String	50
cmdb_sam_sw_install	OctoSAM ID	u_octosam_id	String	50

Set the read-only flag, so that the value cannot be overwritten via user interface. It's recommended to define a database index on these columns.

Computer¶

XPath expression to get the computers:

/octosam/computers/computer

Optional columns in cmdb_ci_computer¶

If these custom columns are defined on the cmdb_ci_computer table, they can be populated via Auto Mapping.

Table	Label	Name	Type	Length
cmdb_ci_computer	Directory Deleted	u_directory_deleted	True/False
cmdb_ci_computer	Directory Deleted First Detected	u_directory_deleted_first_detected	Date/Time
cmdb_ci_computer	Directory Found	u_directory_found	True/False
cmdb_ci_computer	Last Found In Directory	u_last_found_in_directory	Date/Time
cmdb_ci_computer	SMBIOS UUID	u_smbios_uuid	String	50
cmdb_ci_computer	DHCP	u_dchp	True/False
cmdb_ci_computer	Last Reboot	u_last_reboot	Date/Time
cmdb_ci_computer	OctoSAM Custom Field1	u_octosam_custom_field1	String	512
cmdb_ci_computer	OctoSAM Custom Field2	u_octosam_custom_field2	String	512
cmdb_ci_computer	OctoSAM Custom Field3	u_octosam_custom_field3	String	512
cmdb_ci_computer	OctoSAM Custom Field4	u_octosam_custom_field4	String	512

Example Data¶

<octosam>
  <computers correlation_field="octosam_id">
    <computer>
      <target_class>cmdb_ci_win_server</target_class>
      <name>sv5185</name>
      <domain>acme</domain>
      <dns_domain>acme.local</dns_domain>
      <fqdn>sv5185.acme.local</fqdn>
      <octosam_id>b3a9a394-9240-44e7-b17e-d78bfb6d2640</octosam_id>
      <u_smbios_uuid>21c7a2e3-c190-4ca0-9239-d24b816a4cfa</u_smbios_uuid>
      <u_octosam_smbios_uuid>21c7a2e3-c190-4ca0-9239-d24b816a4cfa</u_smbios_uuid>
      <u_octosam_url>https://octosam.acme.com/OctoWeb/Machine/Machine/b3a9a394-9240-44e7-b17e-d78bfb6d2640</u_octosam_url>
      <os_family>WIN</os_family>
      <os_server>true</os_server>
      <os>Windows Server 2016 Standard</os>
      <os_version>14393</os_version>
      <!--most frequent user: acme/sv5185$ CN=sv5185,OU=Server,OU=Computer,DC=acme,DC=local-->
      <assigned_to>acme/sv5185$</assigned_to>
      <organization>Acme IT</organization>
      <os_service_pack />
      <first_discovered>2020-01-20 10:19:04</first_discovered>
      <last_discovered>2020-05-20 01:30:01</last_discovered>
      <manufacturer>VMware</manufacturer>
      <model>VMware Virtual Platform</model>
      <chassis_type>Other</chassis_type>
      <serial_number>VMware-423d4d4c8482de0b-d0e257fd81cb3729</serial_number>
      <virtual>true</virtual>
      <u_directory_deleted>false</u_directory_deleted>
      <u_directory_found>true</u_directory_found>
      <u_last_found_in_directory>2020-05-20 02:08:06</u_last_found_in_directory>
      <short_description>OctoSAM</short_description>
      <mac_address>00:50:56:bd:63:9e</mac_address>
      <u_last_reboot>2020-04-28 04:04:46</u_last_reboot>
      <ip_address>10.37.25.185</ip_address>
      <default_gateway>10.37.25.1</default_gateway>
      <u_dhcp>false</u_dhcp>
      <cpu_manufacturer>Intel</cpu_manufacturer>
      <cpu_type>Intel(R) Xeon(R) Gold 5118 CPU @ 2.30GHz</cpu_type>
      <cpu_core_count>2</cpu_core_count>
      <cpu_count>2</cpu_count>
      <cpu_speed>2295</cpu_speed>
      <ram>8192</ram>
      <u_last_replication>2020-05-20 01:30:01</u_last_replication>
      <u_last_replication_sys_id>164e3e75-0afb-4d66-984b-d501041ad4fd</u_last_replication_sys_id>
    </computer>
  </computers>
</octosam>

Fields¶

OctoSAM	ServiceNow	Type	Remarks
assigned_to	assigned_to	Reference	reference to the MostFrequentUser user object either with or without domain name. See `ServiceNow.UserIncludeDomain` configuration parameter.
cpu_core_count	cpu_core_count	Integer
cpu_count	cpu_count	Integer
cpu_manufacturer	cpu_manufacturer	String
cpu_speed	cpu_speed	Integer	CPU speed in MHz
cpu_type	cpu_type	String
default_gateway	default_gateway	String	IP default gateway
dns_domain	dns_domain	String	DNS domain of the computer
first_discovered	first_discovered	DateTime
fqdn	fqdn	String	fully qualified domain name of the computer
ip_address	ip_address	String	IP address of the main network interface
last_discovered	last_discovered	DateTime
mac_address	mac_address	String	the mac address of the main network interface of the computer
manufacturer	manufacturer	Reference
model	model_id	Reference	manufacturer and model should be looked up in the transform using ServiceNow provided lookup tools such as MakeAndModelJS
name	name	String	computer name normalized to lowercase, should be looked up in ServiceNow for items that are synchronized for the first time
octosam_id	u_octosam_id	String	OctoSAM unique id, a GUID that references the machine, should be indexed in ServiceNow
organization		String	OctoSAM organization that this computer is mapped to
os	os	String
os_domain	os_domain	String	NETBIOS domain name of the computer
os_family		String	operating system family defined by OctoSAM, can be used in transform scripts instead of searching within the os
os_server		True/False	`true` if the operating system is a server version
os_service_pack	os_service_pack	String	Service pack of the operating system, if available
os_version	os_version	String
ram	ram	Integer	RAM in MB
serial_number	serial_number	String	Serial Number reported by the machine if available (not always available and not always unique, depending on OS manufacturer, setup)
short_description	short_description	String
target_class	sys_class	String	ServiceNow class
u_dhcp		True/False	`true` if the main network interface has DHCP enabled
u_directory_deleted		True/False	flag if the computer was deleted in active directory
u_directory_deleted_first_detected		Date/Time	date/time when OctoSAM first detected that a machine was deleted in active directory
u_directory_found		True/False	`true` if the computer was found in active directory by OctoSAM
u_last_found_in_directory		DateTime	date/time the computer was last found in active directory
u_last_reboot		DateTime	last reboot of the operating system
u_last_replication		DateTime	With active 2 way replication this is the timestamp of the last ServiceNow to OctoSAM replication
u_last_replication_sys_id		String	This is the sys_id of the item reported by last ServiceNow to OctoSAM replication
u_octosam_url		String	link to this machine object in the OctoSAM web interface
u_smbios_uuid		String	SMBIOS uuid reported by the machine if available (not always available and not always unique, depending on OS, manufacturer, setup)

You can configure additional fields that you want to export from the OctoSAM machine object in the appsettings.json configuration file:

  "ServiceNow": {
    "Export": {
      ...
      "AdditionalFields": {
        "Machine": {
            "CustomField1": "u_octosam_custom_field1",
            "DirectoryExtensionAttribute1": "u_directory_extension_attribute1",
            "DirectoryExtensionAttribute2": "u_directory_extension_attribute2",
            "DirectoryContainerPath": "u_directory_container_path"
        }
    }
  },

Computer transform map¶

The value of octosam_id can be used to determine insert or update action (coalesce). Note that OctoSAM uses a logical device identity model. Same computer name means same Machine. The idea is that in a managed environment, names of active computers already have to be unique. For example, this is always the case if the computer is member in Active Directory.

Note that if you delete a machine from the OctoSAM database and later create a new Machine record with the same name, a new octosam_id will be generated. It's therefore recommended not to remove machine objects from the OctoSAM database during their logical lifespan.

If your ServiceNow CMDB id model is based on a physical machine identity you need to build some logic to coalesce on hardware characteristics. Note that no hardware id is guaranteed to exist or to be unique. Some hardware vendors are lazy to implement truly unique ids, some environments do not support scanning these ids and in virtual environments all of these ids can be manually overridden.

If a computer is not yet available in ServiceNow, i.e. if its synchronized for the first time, the transform should lookup the computer based on other information usually on the name, but depending on your scenario, other identifying fields may be useful such as the serial_number, u_smbios_uuid or the mac address fields (conditional coalesce).

If you choose to coalesce on another field than octosam_id, you need to override the u_octosam_id of existing records in ServiceNow, in case you want to link back into the OctoSAM web interface. Also depending on your coalesce rules you need to take special actions when importing related CIs such as network adapters.

u_smbios_uuid Field¶

The SMBIOS UUID is a valid choice to detect unique hardware items. However, depending on the implementation of the BIOS, this id can not always be read properly or is not unique. By default, OctoSAM exports the OctoSAM ID (same value as u_octosam_id) in the field u_smbios_uuid for Machines that do not provide a valid hardware UUID. This behavior can be turned off by setting GenerateUuidIfEmptyOrInvalid in the configuration - however, the transform script must then be able to handle empty missing and non-unique values in the field. A list of invalid UUIDs can also be specified in case the manufacturer sets a formally valid but not unique UUID.

assigned_to Field¶

In the default constellation, assigned_to contains the most frequent user of the computer calculated by OctoSAM. However, OctoSAM also supports import of device affinity from ServiceNow. If you have a policy to manually assign the main user to a machine, this can be reflected in the OctoSAM database (in combination with the calculated affinity types that OctoSAM provides).

If you have the later policy, do not transform the field from OctoSAM to ServiceNow as that would override the manually configured value. Alternatively, transform the assigned_to field from OctoSAM to a custom reference field in ServiceNow to have both the assigned and the calculated affinity information in the database. You can also protect the field from unwanted accidental overwrite in ServiceNow using the appropriate access control mechanisms.

target_class Field¶

OctoSAM exports the proposed class of the item in the target_class attribute.

Values of target_class

target_class	Represents
cmdb_ci_computer	other computers
cmdb_ci_esx_server	VMWare ESX server
cmdb_ci_hyper_v_server	Windows servers that are Hyper-V hosts
cmdb_ci_linux_server	Linux server
cmdb_ci_server	other servers
cmdb_ci_win_server	Windows servers

Hardware reference fields¶

The reference columns manufacturer and model_id should be used to lookup the model according to ServiceNow standards.

(function transformRow(source, target, map, log, isUpdate) {

    /* make and model lookup */
    var mm = MakeAndModelJS.fromNames(source.u_manufacturer, source.u_model, "hardware");
    target.model_id = mm.getModelNameSysID();
    target.manufacturer = mm.getManufacturerSysID();

})(source, target, map, log, action==="update");

OctoSAM exports normalized manufacturer names but not normalized model names. If you have a maintained database of hardware models you may need to customize the mapping to your needs during ServiceNow import.

Link to OctoSAM Web interface computer details page (Obsolete)¶

Note

OctoSAM 1.10.6 and later export the URL to the machine directly in the u_octosam_url field.

With the OctoSAM ID on cmdb_ci, you can link back to the OctoSAM web interface. Without having to change the ServiceNow UI, you can also define a column of type URL (read-only) and populate it through script transform:

answer = (function transformEntry(source) {

    // form OctoSAM URL from u_octosam_id
    return "https://octosam.acme.com/OctoWeb2/Machine/Machine/" + source.u_octosam_id;  // return the value to be put into the target field

})(source);

Network information¶

Network information such as mac_address, ip_address on the computer CI is given for backward compatibility. OctoSAM also provides the full network adapter configuration to create related cmdb_ci_network_adapter items.

Order of transform processing¶

Make sure that the computers load and transform is processed prior to the dependent hardware and software data sources.

Network adapters¶

XPath expression to get the network adapters:

/octosam/hardware/network_adapter

Example data¶

<octosam>
  <hardware correlation_field="octosam_id">
   <network_adapter>
      <octosam_id>9f911bcf-563f-42f4-bc47-ad0ef92a7a9f</octosam_id>
      <computer>sv9259-1</computer>
      <computer_octosam_id>c7031f9c-8134-487f-afa3-e95aadba1f53</computer_octosam_id>
      <last_discovered>2020-05-18 16:39:35</last_discovered>
      <name>[00000000] Microsoft Kernel Debug Network Adapter</name>
      <ip_address />
      <ip_default_gateway />
      <mac_address />
      <dhcp_enabled>true</dhcp_enabled>
   </network_adapter>
  </hardware>
</octosam>

OctoSAM	ServiceNow	Type	Remarks
computer	ci_item	Reference	The name of the computer where this network adapter is installed. This is provided mainly for logging. Transform script should use the `computer_octosam_id` field
computer_octosam_id	ci_item	Reference	OctoSAM ID of the computer where this network adapter is installed
dhcp_enabled	dhcp_enabled	True/False	`true` if dhcp is enabled on this adapter
ip_address	ip_address	String
ip_default_gateway	ip_default_gateway	String
last_discovered	last_discovered	DateTime
mac_address	mac_address	String
name	name	String	Name of the network adapter (unique within the same computer)
octosam_id	u_octosam_id	String	OctoSAM unique id, a GUID that references the network adapter
octosam_tech_id	tech_id	String	This is the tech_id of the item as it was reported by ServiceNow at the time of the last import from ServiceNow

Network adapter transform map¶

The value of u_octosam_id should be used to determine insert or update action on the target table cmdb_ci_network_adapter (set the coalesce flag on this column).

Reference to the computer is mapped from source column computer_octosam_id via column "Configuration Item" cmdb_ci on the target table.

If you coalesce your computers on other attributes than octosam_id, you need to take that into account when you import dependent items.

All network adapters have the same last discovered time as their referenced machine. After successful transformation, you can delete all network adapters that are in the database for a computer that do not have the same last_discovered timestamp as the computer.

Network information delivered in the computer record¶

The computer also reports network info from the (assumed) default network card. This is provided for ease of reporting and backward compatibility. However, a machine can have multiple active network cards.

Memory modules¶

XPath expression to get the memory modules:

/octosam/hardware/memory_module

Example data¶

<octosam>
  <hardware correlation_field="octosam_id">
    <memory_module>
      <octosam_id>fa09b2c7-89df-42fa-90a9-4de937b3993a</octosam_id>
      <computer>srv9259</computer>
      <computer_octosam_id>c7031f9c-8134-487f-afa3-e95aadba1f53</computer_octosam_id>
      <last_discovered>2020-05-18 16:39:35</last_discovered>
      <name>Physical Memory 0</name>
      <speed />
      <total_width />
      <serial_number>None</serial_number>
      <bank_label>None</bank_label>
      <part_number>None</part_number>
      <device_locator>M0</device_locator>
      <capacity>4096</capacity>
      <type/>
      <type_detail>
    </memory_module>
  </hardware>
</octosam>

OctoSAM	ServiceNow	Type	Remarks
bank_label	bank_label	String
capacity	capacity	Number	memory capacity in MB
computer	ci_item	Reference	The name of the computer where this network adapter is installed. This is provided mainly for logging. Transform script should use the `computer_octosam_id` field
computer_octosam_id	ci_item	Reference	OctoSAM ID of the computer where this network adapter is installed
device_locator	device_locator	String
last_discovered	last_discovered	DateTime
name	name	String	Name of the network adapter (unique within the same computer)
octosam_id	u_octosam_id	String	OctoSAM unique id, a GUID that references the network adapter
octosam_tech_id	tech_id	String	This is the tech_id of the item as it was reported by ServiceNow at the time of the last import from ServiceNow
part_number	part_number	String
serial_number	serial_number	String
speed	speed	String
total_width	total_width	Number
type	type	String
type_detail	type_detail	String

Memory module transform map¶

The value of u_octosam_id should be used to determine insert or update action on the target table cmdb_ci_memory_module (set the coalesce flag on this column).

Reference to the computer is mapped from source column computer_octosam_id via column "Configuration Item" cmdb_ci on the target table.

If you coalesce your computers on other attributes than u_octosam_id, you need to take that into account when you import dependent items.

All memory modules have the same last discovered time as their referenced computer. After successful transformation, you can delete all network adapters that are in the database for a computer that do not have the same last_discovered timestamp as the computer.

Software installs - ServiceNow SAM module not installed¶

TBD

Software installs - ServiceNow SAM module installed¶

XPath expression to get the software install:

/octosam/software/install

Example data¶

<octosam>
  <software correlation_field="octosam_id">
    <install>
      <octosam_id>b5b17263-394e-46c6-8ea1-dac7d8e066b3</octosam_id>
      <computer_octosam_id>b3a9a394-9240-44e7-b17e-d78bfb6d2640</computer_octosam_id>
      <package_octosam_id>1aeed6d6-deee-4bc6-9360-0c6e797e9ae7</package_octosam_id>
      <display_name>Microsoft Internet Explorer</display_name>
      <publisher>Microsoft</publisher>
      <first_discovered>2020-01-20</first_discovered>
      <last_discovered>2020-05-20</last_discovered>
      <install_date />
      <install_location />
      <last_used>2020-01-20</last_used>
      <last_scanned>2020-05-20</last_scanned>
    </install>
  </software>
</octosam>

OctoSAM	ServiceNow	Type	Remarks
computer	ci_item	Reference	The name of the computer where this network adapter is installed. This is provided mainly for logging. Transform script should use the `computer_octosam_id` field
computer_octosam_id	ci_item	Reference	OctoSAM ID of the computer where this network adapter is installed
display_name	display_name	String	The normalized name of the installed Software Package.
install_date	install_date	Date
install_location	install_location	Number
last_scanned	last_scanned	DateTime
last_used	last_used	Date
octosam_id	u_octosam_id	String	OctoSAM unique id, a GUID that references the network adapter
package_octosam_id	samp_sw_product	Reference	Reference to the OctoSAM synced product (to be discussed)

Software install transform map¶

The value of octosam_id should be used to determine insert or update action (coalesce).

Reference to the computer is mapped from source column computer_octosam_id to target Table Software Install (cmdb_sam_sw_install) column Installed On installed_on

Only software installs on computers in the same file are reported. If computer transform succeeds for all records, you can assume that the computer exists.

If you coalesce your computers on other attributes than u_octosam_id, you need to take that into account when you import dependent items.

All software installs have the same last scanned time as their referenced computer. After successful transformation, you can delete all software installs that are in the database for a computer that do not have the same last_scanned timestamp as the computer.

Custom higher level SAM logic may be involved when removing an installation.

Data housekeeping on ServiceNow¶

Computer¶

Computer objects may be linked to other items in ServiceNow, use ServiceNow housekeeping procedures to mark obsolete computer objects.

Obsolete hardware items¶

We suggest to remove obsolete hardware configuration items after import.

Octosoft provides the OctoSAMUtil script include that you can call from an onComplete script of your transform maps. The script include is provided in a subdirectory of the Support folder of the installation media

(function runTransformScript(source, map, log, target /*undefined onStart*/ ) {
   try {
      var util = new global.OctoSAMUtil(log);
      util.cleanupObsoleteHardware(map.target_table);
   }
   catch(e) {
      log.error("onComplete Error:" + e);
   }    
})(source, map, log, target);

Obsolete software installs¶

We suggest to remove obsolete software installs after import. Install the provided OctoSAMUtil script include and call it from the onComplete script of your transform map:

(function runTransformScript(source, map, log, target /*undefined onStart*/ ) {
   try {
      var util = new global.OctoSAMUtil(log);
      util.cleanupObsoleteSoftware(map.target_table);
   }
   catch(e) {
     log.error("onComplete Error:" + e);
   }
})(source, map, log, target);

OctoSAM configuration settings¶

{
  ..
 "ServiceNow": {
    "Export": {
      "LimitComputerTestSet": false,
      "UserIncludeDomain": false,
      "SamModuleEnabled": true,
      "ExportMemoryModule": true,
      "ExportNetworkAdapter": true,
      "CommentedExport": false,
      "GenerateUuidIfEmptyOrInvalid": true,
      "InvalidUuids": [
        "03000200-0400-0500-0006-000700080009" // KABA devices that all have the same hardware UUID
      ],
      "AdditionalFields": {
        "Machine": {
            "CustomField1": "u_octosam_custom_field1",
            "DirectoryExtensionAttribute1": "u_directory_extension_attribute1",
            "DirectoryExtensionAttribute2": "u_directory_extension_attribute2",
            "DirectoryContainerPath": "u_directory_container_path"
        }
      }
    }
  }
}

Setting	Default Value	Description
AdditionalFields		A dictionary of additional fields to export. Currently only Machine fields are supported.
CommentedExport	`false`	The exported file contains comments that help navigating in the file for manual analysis
ExportMemoryModue	`true`	Export detailed memory hardware information
ExportNetworkAdapter	`true`	Export detailed network hardware and configuration information
GenerateUuidIfEmptyOrInvalid	`false`	If true, the export uses the OctoSAM ID if a machine has an empty or invalid SMBIOS UUID. Additionally you can specify a list of invalid UUIDs
LimitComputerTestSet	`false`	Limit test set to computers that have the magic string 'SNOW_TEST' in either one of their custom fields
MachineIncludeDomain	`false`	Include the domain in machine names (for installations that have multiple domains). Note that references to machines are usually made via octosam_id.
SamModuleEnabled	`true`	Specify `true` if the SAM Module is active in ServiceNow this influences selection and naming of fields
UserIncludeDomain	`false`	Include the domain in user names (for installations that have multiple windows domains)

Note

As of Release 1.10.4, we supply scripts and how-to documents only for import in a ServiceNow instance with SAM module enabled.

Artifacts delivered with the ServiceNow integration license option¶

Octosoft delivers all required components on the OctoSAM side. In addition we deliver documentation and example code for implementing the ServiceNow side. However, at this stage we do not deliver any official ServiceNow components, Update Sets or (scoped) apps. Implementing the ServiceNow side requires basic knowledge of ServiceNow administration including customization and scripting and the ServiceNow CMDB structure.

The components on the OctoSAM side try to make integration on the ServiceNow side as straight forward as possible. For example we have moved some decisions that typically require scripting in the transform map to the export side of the integration. All data exported is formatted in a way that ServiceNow can handle without additional configuration.

Whenever possible, transform maps can be generated automatically and cover all fields where you do not have to make customer-specific decisions anyway. This architecture gives the customer the most flexibility on how to implement the ServiceNow import side. Co-existence with other discovery mechanisms and other inventory integrations can be achieved relatively easily. Newest features of the ServiceNow Releases can be used. Currently there is a lot of development within the ServiceNow integration mechanism and CMDB APIs between ServiceNow releases. For example you can use features like the Robust Transform Engine (RTE) or multi-source CMDB. This documentation describes only the simplest form of integration as an example. It is assumed that the implementor of the ServiceNow side adapts this information to suit the particular site requirements.

Exporting data from OctoSAM¶

Use the octoutil commands to export a compressed .xml file containing all the data. A full export contains all machines, while an incremental export contains only the machines and related information changed since the last export.

Import via ServiceNow Import Set is the same for full or incremental exports. You need to make sure that the schedules of OctoSAM export and ServiceNow imports are setup in a way that ServiceNow regularly receives full exports Incremental exports are useful if your workflows depend on new information being replicated quickly for example if you set up new computers in an environment.

octoutil export servicenow [full|incremental] _zipfile_

Info

You can issue octoutil commands from housekeeping scripts. This lets you synchronize the ServiceNow export with the OctoSAM Import Service. Full Export should be executed after the OctoSAM Housekeeping.

Test data¶

Limit test data size¶

For integration tests its not practicable to always import and transform the whole amount of data. If the configuration setting LimitComputerTestSet is set, the export will only export machines that have the magic string 'SNOW_TEST' in one of their CustomFields. Any of the fields CustomField1, CustomField2, CustomField3 or CustomField4 can be used. Dependent items such as cmdb_ci_network_adapter or software installations are only exported for the selected computers.