Skip to content

ServiceNow Interface for MDCMS

from Midrange Dynamics

From Version 8.2

Published December 21, 2021

ServiceNow Interface for MDCMS - Table of Contents

Overview

What is ServiceNow?

ServiceNow is a web-based, proprietary incident management product. It can be licensed to run in the cloud on ServiceNow servers or licensed as a server product installed within the organization’s infrastructure. The ServiceNow interface for MDCMS is designed to communicate seamlessly with either licensing version with a common set of administrative tools. 

Information Shared between ServiceNow and MDCMS

The intention of the interface is to share data and workflow control between MDCMS and ServiceNow in order to avoid needing to manually duplicate entries in both systems as well as to be able to manage tasks from either system.
Specific Projects and Task Types can be defined as being applicable to MDCMS or ServiceNow as well as specifying where tasks of the given type may originate. This allows for the flow of information to differ by type and to reduce the amount of information shared between systems to only that which is relevant. Due to the flexibility of ServiceNow and MDCMS APIs, any column in any table, parent-table or child-table in ServiceNow can be shared with MDCMS. The primary table will typically be task, incident or change request.

How MDCMS Communicates with ServiceNow

ServiceNow provides a set of REST APIs that MDCMS can consume in order to retrieve or update information.
A new MDCMS background service called MDSNOW consists of 1 job to use these REST APIs.
MDSNOW is a MDCMS program that polls for deltas to tasks for applicable projects every n seconds, by invoking the ServiceNow REST APIs.

Only one partition needs to connect to ServiceNow (typically the development partition). This partition MUST be set as a Workflow location and the MDPUSH or MDPULL jobs MUST be used to share the ServiceNow information, even if there is only a single partition.
The authorization of MDCMS to invoke the ServiceNow APIs is enabled using either basic user/password credentials or using OAuth with password flow. In the case of OAuth, the user and password of a ServiceNow administrator is used to generate a token, which is passed on future calls rather than the password (unless a new token needs to be created).

Prerequisites for using the Interface

  • An active MDCMS and MDWorkflow license (v8.2.3+) on the IBM i partition used to connect to ServiceNow

  • A valid SSL Certificate must be available in Digital Certificate Manager *SYSTEM certificate store

  • ServiceNow must be reachable within the network by the partition

  • The ServiceNow authorization credentials must be provided by a user with administrator access in ServiceNow

  • The MDCMS-Side configuration must be performed by a user with MDSEC authority to System Settings (code 11)

Configure the Interface

ServiceNow Interface Settings

The interface settings are managed from MDCMS -> MDCMS Setup Menu -> Services -> MDSNOW

Common Service Settings
The common service settings are available on the initial MDSNOW service screen.
Default Job Queue The name and library of the job queue that the MDSNOW and jobs
should be submitted to. The default of QSYSNOMAX runs in subsystem
QSYSWRK.
Default End Time The time of day that running MDSNOW jobs should cleanly end

*NEVER – the MDENDServiceNow command will be used
Default Delay Interval The amount of time in seconds between checks for updates to projects
and tasks.

If using the MDCMS WebHook for ServiceNow, it is recommended to set the
interval to 30 minutes (1800 seconds). Otherwise, it is recommended to
set it to 30 seconds.

ServiceNow-Specific Settings
Press F10 from the MDCMS Service screen for MDSNOW to get to settings specific to the ServiceNow interface.
ServiceNow URL The domain name of the ServiceNow web application for the https
connection

Example: https://my-company.service-now.com
ServiceNow User The user name of a registered user in ServiceNow with administrative
rights.
Password The password for the ServiceNow user
Enabled N – don't communicate with ServiceNow

Y - communicate with ServiceNow
Use OAuth N - use basic user/password credentials for communication with
ServiceNow

Y - use an OAuth token as credentials for communication with
ServiceNow.
Client ID The Client ID that is generated by ServiceNow for the client
application
Client Secret the passphrase known to ServiceNow for decrypting the token when
using OAuth credentials
Proxy Host The address of the Proxy server to route http requests through
Proxy Port The port number on the Proxy server to route http requests
through
Proxy User The user id on the Proxy server (if required) for authenticating the
http request on the proxy
Proxy Password The password of the user id on the Proxy server (if required) for
authenticating the http request on the proxy

Setup OAUTH Credentials in ServiceNow

If you would prefer to use OAuth for authenticating MDCMS in ServiceNow instead of basic authentication, take the following steps:

  1. Sign into ServiceNow as an administrator

  2. Navigate to System OAuth→Application Registry

  3. Click New and select Create an OAuth API endpoint for external clients 

  4. Enter a name, such as MDCMS, enter a Client Secret and click Submit

  5. In a 5250 session, navigate to MDCMS -> MDCMS Setup Menu -> Services -> MDSNOW and press F10 to view ServiceNow specific settings

  6. Set Use OAuth to Y

  7. Set Client ID to the string shown in the OAuth Client listing in ServiceNow

  8. Set the Client Secret to the Client Secret set in ServiceNow

Map Users

Press F8 from the ServiceNow Interface Settings screen to list all Users defined in ServiceNow and specify what the equivalent MDCMS User Profile is.

Press F5 to build or refresh the list of ServiceNow Users. If the refresh fails, use option L=Logs for Service MDSNOW and view the IFS log for the current date to see the specific cause of the problem.

Press F9 to toggle the list between all entries and only mapped entries.
Use the filter fields to limit the list to rows containing the filter values.

If the ServiceNow user's user name, display name or email address matches a MDCMS user description or email address, MDCMS will automatically map the MDCMS user profile.
You only need to map ServiceNow users, if they will potentially be creating projects, creating tasks, or be assigned to tasks that are relevant to MDCMS

When a user mapping is confirmed, MDCMS will automatically store the ServiceNow user's email address, if an email address isn't already defined for the MDCMS user.
Only Import task if Assigned to a mapped User? Y - A task will only be imported from ServiceNow to MDCMS if the
assignee for the task is mapped to an MDCMS user

N - A task will be imported from ServiceNow to MDCMS, even if not
assigned, or if assigned to someone that isn't mapped. All other import
rules continue to apply, though.
ServiceNow User Name The ServiceNow login ID
Display Name The Description of the ServiceNow user
MDCMS User The MDCMS user to map to. Press F4 to select from list of defined
users



If left blank, corresponding tasks will still potentially be imported,
but the user will be anonymous.
O (User Origin) Flag designating the user to map based on the direction of the
data flow (import or export), since there may be duplicate users in
MDCMS or in ServiceNow.
J - when importing user-related data from ServiceNow, map the given
ServiceNow user to the specified MDCMS user. Multiple ServiceNow users
can map to the same MDCMS user
M - when exporting user-related data to ServiceNow, map the specified
MDCMS user to the given ServiceNow user. The MDCMS user can only be
mapped once for export.
B - when importing or exporting user-related data, map the specified
MDCMS user to the given ServiceNow user. The MDCMS user can only be
mapped once for export.

Map Projects

Before Tasks can be shared between ServiceNow and MDCMS, the ServiceNow settings need to be mapped to MDCMS settings. These settings can be managed by pressing F9 from the ServiceNow Interface Settings screen for the MDSNOW service.

Any combination of a MDCMS Project and Task Type can be mapped to Table containing tasks in ServiceNow.

Press F6 to add a new mapping combination.
Project A Project already defined in MDCMS
Task Type A Task Type defined in MDCMS to allow importing and/or exporting
between MDCMS and ServiceNow
ServiceNow Table A table defined in ServiceNow that is based on the tasks table,
such as incidents, change requests or tasks. Press F4 to select from the
list of tables defined in ServiceNow.
The first time F4 is pressed, MDCMS collects all tables. The list can
be refreshed by pressing F5
Task Origin Flag designating where tasks for the given mapping may
originate
S - the tasks for the mapping will only originate in ServiceNow and
be exported to MDCMS as tasks
M - the tasks for the mapping will only originate in MDCMS (or
somewhere other than ServiceNow) and be exported to ServiceNow as
tasks
B - the Project/Task Type mapping may contain tasks that originate in
either ServiceNow or MDCMS

Field Mapping

Option 1 for a Mapped Project lists all standard and custom fields defined in MDCMS for the task type that are permitted to be mapped to a field in the ServiceNow table. 

Press F9 to toggle the list between all entries and only mapped entries.

Use the filter fields to limit the list to rows containing the filter values. 

Use option 2 to add or change the mapping for a field. 

Use option 4 to remove the mapping for a field.
ServiceNow Field The ServiceNow field name. Press F4 to browse. If list empty or
fields have changed in ServiceNow, press F5 to refresh the list of
fields for the table.
Type The type of field in ServiceNow, to aid in selecting the appropriate
Custom Field in MDCMS.

array(<type>) indicates that the field is a list of the given
type.
MDCMS Field The MDCMS field to map to. Press F4 to select from list of defined
fields



If left blank, corresponding tasks will still be imported, but the field
won't be included in the import or export.
O (Field Origin) Flag designating the direction of the data flow (import or
export) for the field.
S - only import the field value from ServiceNow - the field won't be
editable in MDCMS.
M - only export the field value to ServiceNow
B - pass the field value in both directions, indicating that editing
of the field is intended in either product.

Import Conditions

Option 2 for a Mapped Project lists the conditions to apply to determine when an entry in the ServiceNow table should be imported into MDCMS.
Condition Sequence The sort sequence of the condition to ensure it is in the
appropriate logical block of conditions.
New OR Block Each condition within a block are treated as AND conditions
(every condition must be true within the block)
If a set of conditions can be true OR a set of conditions can be
true, then the 2nd set of conditions should be placed in it's own OR
block. Mark the start of an OR block by setting this parameter to
Y
ServiceNow Field The name of the field in the ServiceNow table to condition the
import on.
Operator The operator for the condition. Use F4 to select from a list of
syntactically correct operators
Condition Value The value to compare to for the content of the ServiceNow
field.

ServiceNow Status Transition -> MDCMS Status Transition

Option 3 for a Mapped Project lists all Status Codes defined in ServiceNow and allows you to specify what the equivalent MDCMS Status Code is in order to automate the transition of a status for an MDCMS Task when the task status transition occurs in ServiceNow..
Press F5 to build or refresh the list of ServiceNow Status Codes. 
Press F9 to toggle the list between all entries and only mapped entries.
ServiceNow Status The Status Code defined in ServiceNow that can be attributed to
tasks of the selected Table based on the Status field mapped in the
Field Mapping option.
Description The Description of the ServiceNow element
MD Status The MDCMS Status Code to map to



If left blank, then all tasks currently in that status will not cause
the creation or update of the task in MDCMS. This is a good method to
allow the preliminary request and review process to remain entirely in
ServiceNow and then flow into MDCMS once work should occur.



Press F4 on the field to manage and select a valid MDCMS Status
Code



Multiple ServiceNow Status Codes can be mapped to the same MDCMS Status
Code
Update Only Y – update the information for the task in MDCMS when the ServiceNow
task is in that status, but don't create the task in MDCMS when it
doesn't exist yet. This is to update MDCMS when ServiceNow transitions
back to an earlier status that normally wouldn't flow into MDCMS or to
avoid bringing over ServiceNow history for closed tasks during the
initial import.
O (task Origin) Flag that limits the status transitioning based on where the task
originated.
S - only perform the status transition in MDCMS if the task
originated in ServiceNow
M - only perform the status transition in MDCMS if the task
originated in MDCMS (or anywhere except ServiceNow)
B - perform the status transition regardless of where the task was
created.
Exceptions The Status Transition that occurs in ServiceNow can be ignored in
MDCMS when the current status in MDCMS is defined on the exception list
for the new Status value.

To list/define status exceptions, position the cursor to the row and
press F8. Place a Y on each row when the update in MDCMS to the new
Status should now occur if the MDCMS status has the row's status.
This is helpful if you have additional transitions within MDCMS for
better granularity for your dev team, so that the MDCMS status won't
revert to a code that is less granular.

MDCMS Status Transition -> ServiceNow Status Transition

Option 4 for a Mapped Project lists all Status Codes defined in MDCMS and allows you to specify which of those codes are allowed to be updated (transitioned) to by specifying the ServiceNow Status that MDCMS will request to be transitioned to. If the task originated in MDCMS, a status transition in MDCMS will be allowed even if it isn't mapped to a ServiceNow Status.

Press F5 to build or refresh the list of ServiceNow Status Codes. 
Press F9 to toggle the list between all entries and only mapped entries.
MDCMS Status The Status Code defined in MDCMS that is allowed to be transitioned
to within MDCMS for ServiceNow tasks
ServiceNow Status The name of the ServiceNow Status Code that will be transitioned
to within ServiceNow. Press F4 to select from list.
The special value of *internal can be used to allow the transition
with MDCMS, but not to trigger a transition within ServiceNow.

This is helpful if you have additional transitions within MDCMS for
better granularity for your dev team.

IMPORTANT - Prerequisites for the ServiceNow Status Update to function:

  • the Workflow that is defined in ServiceNow for the task's type must allow the transition from the current status in ServiceNow to the status that is mapped from the MDCMS status 

  • the IBM i partition that connects to ServiceNow must be defined in the OS/400 Locations on the partition initiating the status change. If it's the same system, then the Location ID is *LOCAL

  • the OS/400 Location definition must have the MDWorkflow Rep parameter set to Y and assigned either a Push Job# or Pull Job#

  • the MDPUSH or MDPULL service must be running

  • the MDSNOW service must be running

Pull tasks from ServiceNow

Full Import

Once the mapping is complete for projects, task types, users, fields and status codes, F10=Get tasks can be pressed from the ServiceNow Interface Settings for the MDSNOW service.
All tasks for mapped projects matching mapped types and status codes will be imported or updated in MDCMS.
A full import should be performed initially and whenever a condition, field or Status Transition is added to the mapping.

A full import for a specific project can be performed using option G=Get Tasks in the Mapped Projects listing.

Delta Import

Once an initial Full Import is performed, the MDSNOW service will check every n seconds for any new or changed tasks since the last check for each ServiceNow Project that is registered in MDCMS. The bandwidth for this request is very small since only differences from the prior check are returned. It's recommended to set the interval to 30-60 seconds. 

Registered ServiceNow Projects will continue to be queried until they are closed in MDCMS.

View ServiceNow Information from MDCMS

ServiceNow tasks

The ServiceNow task Key is stored in the MDCMS Task Reference Code. The code value can be searched and listed in MDCMS by pressing F8=Ref Code in the Task Listing. 

View ServiceNow Information from MDOpen/MDWorkflow

ServiceNow tasks

The ServiceNow task Key is stored as a Task Reference Code of type ServiceNow.
You can navigate directly to ServiceNow from a Task in MDOpen/MDWorkflow by clicking on the URL link for a row in the Task Listing.