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:
-
Sign into ServiceNow as an administrator
-
Navigate to System OAuth→Application Registry
-
Click New and select Create an OAuth API endpoint for external clients
-
Enter a name, such as MDCMS, enter a Client Secret and click Submit
-
In a 5250 session, navigate to MDCMS -> MDCMS Setup Menu -> Services -> MDSNOW and press F10 to view ServiceNow specific settings
-
Set Use OAuth to Y
-
Set Client ID to the string shown in the OAuth Client listing in ServiceNow
-
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.