SCOPED CERTIFIED APPLICATION INSTALLATION AND

CONFIGURATION GUIDE
Service Graph Connector for Armis

version: 1.1

effective date: October 15th, 2021

Page: 1 of 20
 Integration Design Document Template

Table of Contents

Contents
1 Overview .........................................................................................................................................................3
2 Application Dependencies ................................................................................................................................3
2.1 ITOM Licensing .......................................................................................................................................................... 3
3 Configuration Instructions ................................................................................................................................4
3.1 Default Class Mappings ........................................................................................................................................... 12
Target Tables: 12
3.2 Default Field Mappings............................................................................................................................................ 20
4 Support and Troubleshooting ......................................................................................................................... 23
4.1 Service Level Agreement Definition ........................................................................................................................ 23
• Promised Call Response Time: 1 Hour .............................................................................................................. 23
4.2 Troubleshooting ...................................................................................................................................................... 23
5. Advanced Config 23

Page: 2 of 20
 Integration Design Document Template

1 Overview
The Service Graph Connector for Armis imports device data from Armis to your ServiceNow CMDB
according to ServiceNow best practices. It is capable of mapping Armis device models sourced from
their database of over 280 million device models to 80+ ServiceNow CMDB classes, many of which
are being classified for the first time. The Service Graph designation ensures that we are working
directly with ServiceNow’s CMDB team to correctly model the CI data according to the current best
practices.
The integration leverages ServiceNow’s IntegrationHub ETL plugin to provide a user-friendly, low-
code interface for their Robust Transform Engine (RTE) and Identification & Reconciliation Engine
(IRE). The RTE ensures performant data ingestion and transform, while the IRE ensures that the
Armis data overlays on top of other integration’s data while minimizing duplicates.

2 Application Dependencies
 List all plugins required:
o IntegrationHub ETL (1.3.1 or higher)
o Robust Transform Engine (RTE)
o CI Identification (IRE)
o Configuration Management (CMDB)
o CMDB CI Class Models (1.12.0 or higher)
o Integration Commons for CMDB (sn_cmdb_int_util) (2.3.1 or higher)
o ServiceNow IntegrationHub Action Template - Data Stream
o ITOM Licensing (com.snc.itom.license) plugin
o System Import Sets
o Orlando Patch 7, Paris Patch 1, or Quebec Patch 1 (or higher)

2.1 ITOM Licensing

Usage of this Service Graph Connector requires a subscription to a Subscription Unit based
IT Operations Management (ITOM) Visibility or ITOM Discovery application. Managed IT
Resources (as defined in Section 1.1 of the ServiceNow Subscription Unit Overview -
https://www.servicenow.com/content/dam/servicenow-assets/public/en-us/doc-
type/legal/servicenow-subscription-unit-overview.pdf) created or modified in the CMDB by
this Service Graph Connector, but not yet managed by ITOM Visibility or ITOM Discovery,
will increase Subscription Unit consumption within that application. Customers should
review their current Subscription Unit consumption within ITOM Visibility or ITOM
Discovery to ensure available capacity.

Page: 3 of 20
 Integration Design Document Template

3 Configuration Instructions
1. Click “Get” on the Service Graph Connector for Armis store page to entitle the integration
to one or more instances. This will require ServiceNow HI Admin credentials.
2. Once entitled, navigate to the instance, System Applications > Service Graph Connector for
Armis and click “Install”
3. After installation completes, refresh to the page and type “Armis” to see the Armis
modules. Click “Service Graph Connector for Armis – Guided Setup”. It is recommend to
be in the app scope.
4. Click the “Get Started” button

Page: 4 of 20
 Integration Design Document Template

5. Within the “Connect” section, click the “Get Started” button

6. For the task “Enter your Armis URL”, click the “Configure” button. Please modify the
highlighted portion of the screenshot below and replace with your actual armis instance.
For example, if you login to http://myinstance.armis.com to view the Armis portal, this is
the url you should enter as the Connection URL.

You only need to modify the Connection URL, then you can click the Update button.

Page: 5 of 20
 Integration Design Document Template

Once you complete each task, click “Mark as Complete” to track your progress:

7. Next, for the task “Enter your Armis API Secret”, click the “Configure” button.

All you need to do here is paste in your API Secret* from Armis into the “API Key” field
below and then click the “Update” button and “Mark as Complete”.

NOTE: If your ServiceNow instance has multiple Armis integrations installed, it is

recommended that you use a separate user account to generate a new API Secret so each
application has a unique key. If both applications share the same API Secret, then one
application request may invalidate the token for the other application.

Page: 6 of 20
 Integration Design Document Template

*If you don’t know your Armis API Secret, login to your Armis instance, click your Profile
icon, then click Settings > API Management and then click the “Create” button under API
Secret Key if necessary. Once created, copy the key back into the above “API Key” field. If
you generate the API Secret with only READ access, PII will appear as asterisks when
queried. “Full advanced permissions” will grant the API unrestricted unmasked data. Make
sure to generate a unique API Secret if you are using multiple Armis integrations.

8. Now lets perform a Test Load to verify our Connection and Credentials

Click “Test Load 20 Records” to test the connection.

Page: 7 of 20
 Integration Design Document Template

If everything is set up correctly for the connection, you should see a state of “Complete” and a Completion code of
“Success. If you are seeing errors, please go back and review your connection settings in the previous steps.

Page: 8 of 20
 Integration Design Document Template

If you can see the messages above indicating that Authentication was successful and the
import was started, you can close the tab, Mark as Complete, and move on to the next
step to review the ETL mappings.

You can optionally proceed to the “Armis IntegrationHub ETL” module and use the import
set from the Test Load to review the ETL class mapping and transforms. This is not required
to use the integration and only provides a UI to edit Class/Field maps. Mark as Complete

Page: 9 of 20
 Integration Design Document Template

9. Now we’re going to schedule the imports. First, navigate to the scheduling phase

Now click the “Get Started” button on the “Schedule Import Jobs” task group.

Page: 10 of 20
 Integration Design Document Template

Then click the “Configure” button on the “Configure Daily Import Time” task to schedule
the import job.

To schedule, you first have to click the “Active” checkbox. This will make the “Time” field
visible on the form.

Enter an import time that will reduce competition with other integrations for system
resources, then click “Update” and “Mark as Complete”. Note: This job is intended to
import any Armis Devices that have been seen on the network in the last few days.

10. Now we want to click “Configure” for the “Configure Monthly Import Time” task

Page: 11 of 20
 Integration Design Document Template

As in the previous step, we need to first make the record Active in order to see the Time
field. Please select a time which is slightly earlier than the daily import job and minimize
competition with other integrations for system resources. Click Update then “Mark as
Complete” once you have entered the correct values.

3.1 Default Class Mappings

Target Tables:
The Armis CMDB Integration utilizes the ServiceNow Robust Transform Engine to quickly transform
and map devices to many tables in the CMDB
Mappings to certain tables are determined by the Armis Type field.
If an Armis type does not match the mapping conditions the device will not be imported.

Page: 12 of 20
 Integration Design Document Template

Personal Computer [cmdb_ci_pc_hardware]

 Armis Types
o Laptops
o Desktops
o Laptops (by adapter)
o Engineering Workstations
Point of Sale Device [cmdb_ci_pos]

 Armis Types
o Points of Sale
o Credit Card Reader
Display Device [cmdb_ci_display]

 Armis Types
o Projectors
o Monitors
Drone [cmdb_ci_drone]

 Armis Types
o Drones

Game Console [cmdb_ci_game_console]

 Armis Types
o Game Consoles
Hardware [cmdb_ci_hardware]

 Armis Types
o Keyboards
o Mouses
o Gaming
o ATMs
o Analog Gateways
o Unknown

Human Machine Interface [cmdb_ci_hmi]

 Armis Types
o HMI Panels

Page: 13 of 20
 Integration Design Document Template

HVAC Equipment [cmdb_ci_hvac]

 Armis Types
o HVACs
IoT Device [cmdb_ci_iot]

 Armis Types
o Weather Instruments
o Thermostats
o Lightings
o Alarms
o Household Appliances
o AC Drives
o Controllers
o Beacons
o Sensors
o Smart Switches
o Virtual Assistants
IoT Gateway [cmdb_ci_iot_gateway]

 Armis Types
o IOT Gateways
o Gateways

IP Camera [cmdb_ci_ip_camera]

 Armis Types
o IP Cameras
o Dash Cams
o Smart Cameras
o Digital Cameras
IP Router [cmdb_ci_ip_router]

 Armis Types
o Routers
IP Switch [cmdb_ci_ip_switch]

 Armis Types
o Switches

Manufacturing Device [cmdb_ci_manufacturing] (Deprecated)

 Armis Types
o Industrial Robots
o I/O
o Remote IOs
o Generic OT’s
o Generic IO’s
o Barcode Readers

Page: 14 of 20
 Integration Design Document Template

o Servo Drives
o Power Monitors
o Motor Controllers
o Industrial Managed Switches

Medical Diagnostic Device [cmdb_ci_med_diagnostic]

 Armis Types
o MRIs
o X-Rays
o CTs
o Ultrasounds
o General Imaging
o ECGs
o PACSs
Medical Measuring Device [cmdb_ci_med_measuring]

 Armis Types
o Lab Equipment
o Measuring Instruments

Medical Support Device [cmdb_ci_med_support]

 Armis Types
o Storage and Transport
o Workstations
o Emergency Response

Medical Therapeutic Device [cmdb_ci_med_theraputic]

 Armis Types
o Carts
o Acute Cares
Media Player [cmdb_ci_media_player]

 Armis Types
o Media Players
o Video Broadband Devices
o DVRs
o Media Controllers
o AV Transmitters
Multimedia Device [cmdb_ci_multimedia]

 Armis Types
o Audio Headsets
o VR Headsets
o Speakers

Page: 15 of 20
 Integration Design Document Template

Network Gear [cmdb_ci_netgear]

 Armis Types
o Appliances
o Intrusion Prevention Systems
o Pentests
o Malicious
o WLCs
o Vulnerability Scanners
Process Logic Controller [cmdb_ci_plc]
(Deprecated)

 Armis Types
o PLCs
Rack [cmdb_ci_rack]

 Armis Types
o Cabinets
o Frames
o Fillers
o Chassis
o Cable Managers
o Patch Panels
Single Board Computing

 Armis Types
o Single-Board Computers
Scanner [cmdb_ci_scanner]

 Armis Types
o Scanners

Security Device [cmdb_ci_security]

 Armis Types
o Security Equipment
o Triggers

Storage Server [cmdb_ci_storage_server]

 Armis Types
o Storage Server
Smart Television [cmdb_ci_stv]

 Armis Types
o TVs
o Interactive Kiosks

Page: 16 of 20
 Integration Design Document Template

UPS [cmdb_ci_ups]

 Armis Types
o UPS

Vehicle [cmdb_ci_vehicle]

 Armis Types
o Cars
o Trucks
o Electric Scooters

WAN Accelerator [cmdb_ci_wan_accel_network]

 Armis Types
o WAN Optimizers
Wireless Access Point [cmdb_ci_wap_network]

 Armis Types
o Access Points
o Hotspots
o Amplifiers
Wearable Technology [cmdb_ci_wearable]

 Armis Types
o Watches
Printer [cmdb_ci_printer]

 Armis Types
o Printers
Computer[cmdb_ci_computer]

 Armis Types
o Scada Clients
Server [cmdb_ci_server]

 Armis Types
o Virtual Machines
o Scada Servers
o Servers

Communication Hardware [cmdb_ci_comm_hardware]

 Armis Types
o VOIPs

Page: 17 of 20
 Integration Design Document Template

Handheld Computing Device [cmdb_ci_handheld_computing]

 Armis Types
o Mobile Phones
o Tablets
o Ereaders

Windows Server [cmdb_ci_win_server]

 Armis Types
o Servers
 Operating System
o Windows
Linux Server [cmdb_ci_linux_server]

 Armis Types
o Servers
 Operating Systems
o Linux
o Arista
o Aruba
o Debian
o Red Hat
o Fedora
o Ubuntu

AIX Server [cmdb_ci_aix_server]

 Armis Types
o Servers
 Operating Systems
o AIX

UNIX Server [cmdb_ci_unix_server]

 Armis Types
o Servers
 Operating Systems
o BSD

IP Address [cmdb_ci_ip_address]

 Created by default for each record with an IP address populated

Network Adapter [cmdb_ci_network_adapter]

 Created by default for each record with a MAC address

Software Packages [cmdb_ci_spkg]

 Used if instance is on legacy SAM

 Armis Types
o OS (derived from hardware records)

Page: 18 of 20
 Integration Design Document Template

Software Instance [cmdb_software_instance]

 Used if instance is on legacy SAM

 Armis Types
o OS (derived from hardware records)
Software Installation [cmdb_sam_sw_install]

 Used if instance has SAM-F or SAM-P plugin enabled

 Armis Types
o OS (derived from hardware records)

Operational Technology (OT) [cmdb_ci_ot]

 Note that if there is a more specific class available, that class will be used
 Armis Types
o Generic OT’s

OT Control System [cmdb_ci_ot_control]

 Note that if there is a more specific class available, that class will be used
 Armis Types
o Controllers
o Motor Controllers
o PLC’s
o Remote IO’s
o SCADA Servers

OT Supervisory System [cmdb_ci_ot_supervisory]

 Note that if there is a more specific class available, that class will be used
 Armis Types
o Engineering Stations
o Engineering Workstations
o Historians
o HMI’s
o HMI Panels
o SCADA Clients

OT Field Device [cmdb_ci_ot_field_device]

 Note that if there is a more specific class available, that class will be used
 Armis Types
o AD Drives
o Generic IO’s
o IO’s
o Industrial Robots
o Sensors
o Barcode Readers
o Servo Drives
o Smart Cameras
o Power Monitors
o Industrial Managed Switches

Page: 19 of 20
 Integration Design Document Template

3.2 Default Field Mappings

*Note: All Armis table mappings are the same with the exception that some do not have OS
Armis API Column Header Sample Data NOW Attribute Ref? Referenced Table
Hardware*
id 1091 source_native_key
name Linux Computer name
ipAddress 192.168.1.244 ip_address
macAddress d9:f5:ca:41:7e:2f mac_address
manufacturer Lenovo manufacturer Y core_company
model Thinkpad T model_id Y cmdb_hardware_product_model
operatingSystem Ubuntu operating_system
operatingSystemVersion 17.04 os_version
serialNumber C02VL3ECHV2H serial_number
type Laptop sys_class_name
IP Address
Id||ipAddress 1091||192.168.1.244 Source_native_key
ipAddress 192.168.1.244 Ip_address
192.168.1.244 Name
nic
Network
Adapter
macAddress d9:f5:ca:41:7e:2f Name
macAddress d9:f5:ca:41:7e:2f macAddress
Id||macAddress 1091|| Source_native_key
d9:f5:ca:41:7e:2f
ipAddress 192.168.1.244 Ip_address
OS
Software
(Legacy)
Os_software_key Mac OS X:::10.14.6 Key
operatingSystemVersion 10.14.6 Version
operatingSystem Mac Os X Name

Page: 20 of 20
 Integration Design Document Template

OS
Software
Os_software_key:::id Mac Os Source_native_key
X:::10.14.6:::1091
osManufacturer Apple Publisher
Installed_on Y Cmdb_ci_hardware

3.3 Overriding Default Class Maps

If the default mappings listed above do not fit with your current ServiceNow processes, it is possible to overwrite the
mappings to your liking using the SGArmisClassCalculatorOverride Extension Point.

You can navigate to the Extension Point in our Application Menu: Service Graph Connector for Armis > Admin >
Extension Point. This will bring you directly to the override.

To create a new instance of this override, click the “Create Implementation” button under the related links. This will
automatically create and redirect you to a new script include based on the Extension Point template.

To use the override functionality, simply enter the targetClassData you would like to use for specific Armis types,
Purdue levels, operating systems, or a specific row type.

Please note that this override is the last piece to run in the ArmisClassCalculator script include. If you would like to
keep any of the original mappings for the targetClassData parameter, you can specify certain fields to overwrite, and
exclude the rest to use the defaults.

Page: 21 of 20
 Integration Design Document Template

Parameters:
1. targetClassData: an object containing target class name, the parent class of your target class, the super class
(generally will be cmdb_ci_hardware), and the sys_id of the asset type (applicable for CIs with a Purdue
Level)

Example:
{
targetClass: targetClass,
superClass: superClass,
shellClass: shellClass,
assetType: assetType
};

2. armisType: the Armis type you would like to target as listed in the Armis API. If you do not have access to the
API, you can check the names available in our ArmisOTTypeDictionary or the ArmisITTypeDictionary.

3. purdueLevel: the Purdue Level you would like to target.

4. operatingSystem: the Operating System you would like to target.

5. rowType: specific import row type you would like to target. This is a custom field made available in the
integration staging table. Options include the following:
 device
 plcModule
 networkAdapter

6. additionalParameters: any other fields you would like targeted beyond what is listed above.

Example using Armis Type:

Page: 22 of 20
 Integration Design Document Template

4 Support and Troubleshooting

4.1 Service Level Agreement Definition

• Support Hours of Operation: 24 hours per day
• Support Days of Operation: 7 days per week
• Promised Call Response Time: 1 Hour
• Promised Call Resolution Time: N/A
• Contact Method: Website, email, phone
• Contact Details: support.armis.com, support@armis.com, +1 (866) 695-1147

4.2 Troubleshooting
Most of the integration is pre-configured so that you just have to enter your Armis URL and API
Secret. If the integration isn’t working, please start with the credentials.
Additionally, certain CMDB classes like HVAC may not have IRE Identification Rules established.
These classes may need Identification Rules added manually or they cannot be inserted.
If you do need support, please use the in-app Contact Support module.

5. Advanced Config

System Properties:
 x_armis_cmdb.aql: The default Armis device query.
 x_armis_cmdb.aql_monthly_time_frame: Sets the AQL timeframe field for the monthly import
 x_armis_cmdb.aql_daily_time_frame: Sets the AQL timeframe field for the daily import
 x_armis_cmdb.import_fields: A list of fields retrieved from the API

END OF DOCUMENT

Page: 23 of 20