ServiceNow Integration

Owned by Karl Henselin
Last updated: Jun 02, 2023 by Jay-Ar Brouillard
6 min read

ServiceNow integration is supported with basic authentication or OAuth. The user will need enough permissions to create change requests.

Preparing for ServiceNow Integration with FlexDeploy

See ServiceNow Required Permissions and ServiceNow OAuth Support for details.

Create Issue Tracking Instance

Property Name

Property Code

Required

Description

Property Name

Property Code

Required

Description

ServiceNow URL

SN_URL

Yes

The URL for accessing ServiceNow.

ServiceNow User Name

SN_PORT

Yes

A local ServiceNow service account user with a non-expiring password. 

ServiceNow Password

SN_PASSWORD

No*

The password for the ServiceNow User Name above.

Note that encrypted properties are stored in Credential Store (Local or External) and can be configured using Edit button next to credential name drop down. Alternatively, you can reuse single credential for multiple properties also, in which case you should name that credential appropriately.

Required for the following Auth Types, BasicAuth and  OAuthResourceOwner

ServiceNow Auth Type

SN_AUTH_TYPE

Yes

Authentication method for connecting to ServiceNow, BasicAuth,  OAuthResourceOwner, OAuthJWTAssertion.  Defaults to BasicAuth.  

ServiceNow Client ID

SN_CLIENT_ID

No*

The auto-generated unique ID of the application. The instance uses the client ID when requesting an access token. 

Required for the following Auth Types, OAuthResourceOwner and OAuthJWTAssertion.

ServiceNow Client Secret

SN_CLIENT_SECRET

No*

The shared secret string that both the instance and the client application use to authorize communications with one another. The instance uses the client secret when requesting an access token. (Encrypted).  

Required for the following Auth Types, OAuthResourceOwner and OAuthJWTAssertion.

ServiceNow Keystore Path

SN_KEYSTORE_PATH

No*

ServiceNow Keystore Path (path to the jks file).  

Required for the following Auth Types, OAuthJWTAssertion.

ServiceNow Keystore Passphrase

SN_KEYSTORE_PASS

No*

Java keystore passphrase for the ServiceNow Keystore (Encrypted).  

Required for the following Auth Types, OAuthJWTAssertion.

ServiceNow Certificate Alias

SN_CERT_ALIAS

No*

Private certificate alias.  

Required for the following Auth Types, OAuthJWTAssertion.

ServiceNow Certificate Passphrase

SN_CERT_PASS

No*

Passphrase for the ServiceNow Certificate (Encrypted).  

Required for the following Auth Types, OAuthJWTAssertion.

ServiceNow JWT Verifier Map Key ID

SN_JWT_VERIFIER_MAP_KEY_ID

No*

ServiceNow JWT Verifier Map Key ID. 

Required for the following Auth Types, OAuthJWTAssertion.

ServiceNow Certificate Algorithm

SN_CERT_ALGORITHM

No*

Algorithm used for the certificate. Defaults to RS256.

Required for the following Auth Types, OAuthJWTAssertion.

ServiceNow Refresh Token Lifespan

SN_DEFAULT_REFRESH_TOKEN_LIFESPAN

No

The number of seconds that a refresh token is valid. The instance uses the lifespan value when requesting a refresh token. By default, refresh tokens expire in 100 days (8640000 seconds).

ServiceNow Request GET URL

SN_REQUEST_GET_URL

No

The URL to get the change request details as json response. 

  • Default URL is /api/now/table/change_request?sysparm_query=number%3D{SN_CHANGE_NUMBER}

  • If needed, you can change and use your custom GET url for ServiceNow REST endpoint.  The URL should include {SN_CHANGE_NUMBER} string as the execution system will replace it with the actual change number during execution.

    • e.g. /api/xyz/mycompanty_servicenow_generic_api/readChangeRequest?number%3{SN_CHANGE_NUMBER}

  • If the response returned from this GET API contains an attribute called description it will be mapped to the description of the linked ticket, otherwise the description on the links tab will appear as empty.  Prior to 5.5.0.2, an error would occur if the description field was not present in the payload returned from this GET API.

ServiceNow Navigation Request URL

SN_REQUEST_NAV_URL

No

The URL to open ServiceNow and navigate to the Change ticket associated to the project workflow execution

ServiceNow Request POST URL

SN_REQUEST_POST_URL

No

The URL to create a change request.

  • Default URL is /api/now/table/change_request

  • If needed, you can change and use your custom url to create a new change using the POST operation

    • if you want to use Service Catalog, then change the url to /api/now/table/sc_request

Approved Check Script

SN_APPROVED_SCRIPT

No

A Groovy expressions which determines whether a task for the change ticket is approved or not.  The expression must return a boolean, and has access to the following variables:

  • TICKET - an object with fields (JSON) contained in the change ticket, as returned by the ServiceNow REST API.  Fields are referenced as TICKET.<field name>.<sub-field name>

  • FD_ENVIRONMENT_CODE - The environment for a particular deployment request or associated pipeline stage.

If the Approved Check Script is left blank, the default implementation is to return true if the "approval" field of the ticket is set to "approved".

Simple Example which is used by default
TICKET.approval == 'approved'
Example that checks myfield value specific to target environment
(TICKET.myfield == 'UATApproved' && FD_ENVIRONMENT_CODE='UAT') || (TICKET.myfield == 'PRODApproved' && FD_ENVIRONMENT_CODE='PROD')

If you want to see values that can be used, enable FINEST log level for flexagon.fd.model.integration.cms.CMSScript using Admin Operations.

Following example is to check if current date time is between start_date and end_date defined on Ticket. Let's assume format for the date string returned and TimeZone as GMT.

Check if now is between start_date and end_date defined on ticket
import java.util.Date; import java.util.TimeZone; import flexagon.ff.common.core.utils.FlexDateTimeUtils; if(TICKET.approval == 'approved' && TICKET.start_date != null && TICKET.end_date != null) { Date start = FlexDateTimeUtils.stringToDate(TICKET.start_date, "yyyy-MM-dd HH:mm:ss", TimeZone.getTimeZone("GMT")); Date end = FlexDateTimeUtils.stringToDate(TICKET.end_date, "yyyy-MM-dd HH:mm:ss", TimeZone.getTimeZone("GMT")); Date now = new Date(); if(now.after(start) && now.before(end)) { return true; } } return false;

Rejected Check Script

SN_REJECTED_SCRIPT

No

A Groovy expressions which determines whether a task for a change ticket is rejected or not.  The expression must return a boolean, and as has access to the following variables:

  • TICKET - an object with fields (JSON) contained in the change ticket, as returned by the ServiceNow REST API.  Fields are referenced as TICKET.<field name>.<sub-field name>

  • FD_ENVIRONMENT_CODE - The environment for a particular deployment request or associated pipeline stage.

If the Rejected Check Script is left blank, the default implementation is to return true if the "approval" field of the ticket is set to "rejected".

Simple Example which is used by default
Example that checks myfield value specific to target environment

Additional Info Script

SN_ADDITIONAL_INFO_SCRIPT

No

A Groovy expression which determines additional information to add to an external approval when it is approved or rejected.  The expression must return a Map<String, String> and have an entry with the key of "notes" for the value to get added to external approval as a task note. Script has access to the following variables:

  • TICKET - an object with fields (JSON) contained in the change ticket, as returned by the ServiceNow REST API.  Fields are referenced as TICKET.<field name>.<sub-field name>

  • FD_ENVIRONMENT_CODE - The environment for a particular deployment request or associated pipeline stage.

Example where ServiceNow Approver(s) and time of approval are added to task notes

Don't Poll

SN_DONT_POLL

No

Returns whether FlexDeploy should poll ServiceNow to check the change tickets for Approval/Rejection.  The default value is false, which means polling will occur.  Only check this box if you are using the FlexDeploy REST API to communicate ticket approval/rejection.

ServiceNow Available TICKET Variables

Within the script properties on the ServiceNow Instance. The following values are available to you via the TICKET object to use in your script logic. For example, TICKET.approval would return the approval value of the ServiceNow change.

Field Code

Display Name

Description

Data Type

Required

Field Code

Display Name

Description

Data Type

Required

short_description

Short Description

A short description for the change ticket

String

No

description 

Description

A description for the change ticket

String

No

state

State

 

String

No

sys_class_name

Sys Class Name

 

String

No

approval

Approval

 

String

No

start_date

Planned Start Date

 

String

No

end_date

Planned End Date

 

String

No

closed_by

Closed By

 

String

No

impact

Impact

 

String

No

priority

Priority

 

String

No

risk

Risk

 

String

No

requested_by

Requested By

 

String

No

assignment_group

Assignment Group

 

String

No

assigned_to

Assigned To

 

String

No

category

Category

 

String

No

cmdb_ci

CI

 

String

No

type

Type

 

String

No

Configure Folder for Change Management Approvals

Configure ServiceNow Change Management Instance on your parent folder. Change management configurations are inherited by sub-folder and projects. This configuration will allow you to integrate ServiceNow tickets with your FlexDeploy deployment. See Configure Change Management on Folders for more details.

Linking ServiceNow with FlexDeploy Deployments

If Auto Create Ticket, is not enabled, then user must specific the change ticket number on the deployment request. See Link Change Ticket(s) with Deployments . Otherwise, Change Ticket field will be required in the deployment request form. When change ticket number is passed the ticket number is validated on the external application.

The following macros are not currently supported in the footer:
  • style