It is possible to integrate with ServiceNow as a ticketing system, including support for form templates.
This will allow you to not only approve/decline remediation plans and tasks such as agent deployment but with using form templates, it can be ensured that the change can be sent to the correct parties with all required information.
Please Note: a user that has REST capabilities, and is allowed to Open, Read and Change (Write) to tickets is required for ITSM integration.
High-Level Overview
There are 3 ways for integrating JetPatch with ServiceNow:
- Out-of-the-box - JetPatch Integration capabilities out-of-the-box without special customization and modification.
- Dedicated ServiceNow interface - Create a custom Interface in ServiceNow to handle JetPatch requests.
- Custom Integration - contact your Account Manager for more information.
Service Now Components:
- Dedicated System Application
- Dedicated System Web Service
- Upload Table - Same fields as Change Request table (transform table)
- Change Request table
Architectures
Out of the box (default ServiceNow configuration):
Dedicated ServiceNow interface (custom interface):
*Check Change details - There are other ways of getting the status of the Change details. For more information check "Polling Approval Flow" in ITSM High-Level Overview
Default Change Request Information
The following fields will be reflected in Change Request in ServiceNow:
ServiceNow Field | Value | Description/Notes | Configurable |
Requested By | A user in ServiceNow | See KC | No, based on the user that activated the Remediation Plan in JetPatch |
Type | "Normal" or Standard change requests using templates | The Change Request type. | |
Description |
|
Remediation Plan information |
No, based on Remediation Plan details |
Short Description | "Request to approve RP #" | Number (#) populates based on Remediation Plan details | No, based on Remediation Plan details |
Risk | Default is 2 (high) | Risk of the Change Request. | Configurable in 4.2.5+ |
Assigned to | A user in ServiceNow | A user to assigned the Change Request for approval. |
Note: this field can be empty |
Additional information
ServiceNow Field | Value | Description/Notes | Configurable |
Affected CIs | List of relevant computers from RP |
The match between JetPatch and ServiceNow entries is done by name and/or IP so the names in JetPatch should match the CI names in ServiceNow. Only the matched CI will be populated |
Configurable |
Note1: Change Tasks are not supported.
Note2: `sys_target_sys_id` Requirement: When using the upload table method, JetPatch expects the `sys_target_sys_id` field in ServiceNow to contain the actual Change Request (CR) `sys_id`. This ensures seamless downstream operations, such as associating Configuration Items (CIs). If `sys_target_sys_id` is missing or not populated, JetPatch may default to using a temporary `sys_id`, which can cause failures. Default Behavior: ServiceNow is expected to populate `sys_target_sys_id` automatically as part of its standard behavior during CR creation. If Missing: Implement a **Business Rule** in ServiceNow to ensure the `sys_target_sys_id` is set correctly during CR creation.
Out-of-the-box Configuration
Note1 - The following steps are relevant only for Out-of-the-box integration
Note2: A ServiceNow user that has REST capabilities, and is allowed to Open, Read and Change (Write) to tickets is required for ITSM integration.
Step 1: JetPatch Integration App in ServiceNow
In order to open automatic tickets for in ServiceNow we need to create a dedicated Integration app in ServiceNow backend
STEP 1.1: Creating System Application
- In serviceNow server, Go to Home → Create and Deploy → System Application → Create Application → Start from scratch (create button on the right):
- Name = JetPatch integration
- Scope = the default that provided after filling the Name filed
- Click on Create button (you don't need to enter to Edit App after that)
If The creation does not succeed because of "could not be registered in the AppRepo for this reason: Scope is not available" - change the application name and try again (link)
STEP 1.2: Creating System Web Service
- In the left search box (top of the menu) search for "Web".
- Under "System Web Services" → "Inbound", click on Create New:
- Application = if it's different from "JetPatch integration", click on the wheel in the top right of the page (right to Logout) → Application → choose Intigua Integration
- Label = Jetpatch Integration
- Copy fields from target table = mark as V
- Target table = search for "change Request [change_request]"
- Click on Create button
- In order to work with our app, we need to create a "Transform Map" between our table to the Change Request table. Click on the "Auto Map Matching Fields" at the bottom of the page, after "Related Links"
- Click on the "Update" button
STEP 1.3: Validate Intigua Server Configuration
- In ServiceNow backend, search again for System Web Service.
- You should find "JetPatchIntegration" in the System Web Services section, click on it (if you don't see it - refresh the page)
- The Name should be "x_inti4_jetpatch_i_jetpatch_integration". Copy it and save this for later.
Step 2: Setup ServiceNow configuration in JetPatch
Configuration fields
Add the following configurations in the intigua.properties file, located on the JetPatch Application Server.
Please change the values based on your environment (via the Intigua application ServiceNow WSDL file).
Enable ServiceNow Integration
For Patch Operations:
# Whether or not to enable the Remediation Plan integration
serviceNow.remediationPlanEnabled=true
(OPTIONAL) For Agents and Connector Operations
- Note: most users only want integration for patch operations, so please skip this optional step unless you really want integration for agent management or for connector deployment
- Deploy/Remove/Start/Stop a managed agent
- Install/Remove Connector
# Whether or not the enable the integration for connector/agent deployment/removal
serviceNow.enabled=true
ServiceNow URL and Credentials
# The URL to service now
serviceNow.hostUrl=https://example.service-now.com
# Intigua's integration user
serviceNow.userName=<SNOW_USERNAME>
# Intigua's integration user password
serviceNow.password=<SNOW_PASSWORD>
Please Note: a the ServiceNow.user must have REST capabilities, and is allowed to Open, Read and Change (Write) to tickets is required for ITSM integration.
ServiceNow tables mapping
# The table of creating and polling items
serviceNow.table=change_request
# Name of the table to upload into (which is normally part of the Intigua Integration application)
serviceNow.uploadTable=<NEW_APPLCIATION_NAME_CREATED_IN_STEP_1.3.3_ABOVE>
ServiceNow fields mapping
For the Upload table (the new application table):
# The correlation ID field as appear in the upload table
serviceNow.correlationId.field.upload=u_correlation_id
# The field where Intigua should write a short description
serviceNow.shortDescription.field=u_short_description
# The field where Intigua should write a detailed description
serviceNow.description.field=u_description
# The assignee field in ServiceNow:
serviceNow.assignee.field=u_assigned_to
# The field for Risk:
serviceNow.risk.field=u_risk
# Use PUT call to upload table for ticket closing (Closing ticket via "upload table" and not using the regular table)
serviceNow.ticket.close.via-upload=true
- For more configurations follow ITSM Integration Setup.
Notes:
- In most cases, creating a new application map to the "Change Request" table will result in a "u_" prefix to the fields (this is why the values above are starting with "u_").
- The fields above may be changed. Please check the "Checking ServiceNow Properties Names for JetPatch Configuration" in the Notes below.
For the Change Request table:
# The field to poll for the request status
serviceNow.approval.field=u_approval
# The correlation ID field as appear in the Change Request table
serviceNow.correlationId.field=u_correlation_id
Note - The fields above may be changed. Please check the "Checking ServiceNow Properties Names for JetPatch Configuration" in the Notes below.
Expected values for Risk
# Comma delimited values is expected in serviceNow.approval.field in case of risk:
serviceNow.risk.veryHigh.values=1
serviceNow.risk.high.values=2
serviceNow.risk.moderate.values=3
serviceNow.risk.low.values=4
serviceNow.risk.none.values=5
Expected values for Change Status
# Comma delimited values is expected in serviceNow.approval.field in case of a rejection
serviceNow.approval.reject.values=rejected
# Comma delimited values is expected in serviceNow.approval.field in case of an approval
serviceNow.approval.approved.values=approved
# Comma delimited values is expected in serviceNow.approval.field when the request is pending
serviceNow.approval.pending.values=requested,not yet requested,not requested
General Integration Configuration
# The interval between pooling the "Service Now" service in seconds
serviceNow.polling.interval.minutes=1
# Timeout
serviceNow.approval.timeout.hours=168
Predefined "Assigned To" user (can be empty):
# The assignee username in ServiceNow:
serviceNow.assigneeUserName=<ASSINED_TO_USER_NAME>
Example of what it would look like in ServiceNow
Additional Configuration (optional):
Changing protocols configuration
Timeout changes:
# Protocols timeout in milliseconds (default 10 seconds)
serviceNow.connection.timeout.ms=10000
serviceNow.socket.timeout.ms=10000
connection re-use:
serviceNow.connection.no-reuse=false
True - JetPatch will not reuse a connection (related to the 'keep-alive' http property).
False (default) - JetPatch will check if the current connection can be kept.
Step 3: Validate integration between JetPatch and ServiceNow
- Try to deploy/remove an agent on a machine or activate a new Remediation Plan.
- If you are trying to do agents activities - You will see new activity in Pending.
- If you are trying to do patching activities - You will see that the Remediation Plan in the "Pending" column.
- Go to ServiceNow server and search for "Change".
- Under "Change" section go to "Open". Make sure you are sorting the table based on the creation date ("Created")
- You need to see new request which "Approval" is Requested.
- Approve the Change Request
- Go back to the Intigua console and check that the operation continue and is being executed.
Optional Step#1 - (Template Name / ID, date, CI matching)
2. Start and End Date
Assuming Upload Table:
-
Fields:
-
u_start_date
: Earliest "next start time" for all affected endpoints. -
u_end_date
: Latest "next end time" for all affected endpoints.
-
- Configuration:
-
Usage:
- Use
u_start_date
andu_end_date
in ITSM calls for Upload Table operations.
- Use
Assuming Main Table:
-
Fields:
-
start_date
: Automatically represents the earliest "next start time." -
end_date
: Automatically represents the latest "next end time."
-
-
Configuration:
- No additional mapping or field customization is required; the default fields are used.
-
Usage:
- Directly use
start_date
andend_date
in ITSM calls for Main Table operations.
- Directly use
3. Affected CI (computer) list will be populated with relevant computers from RP. The match between JetPatch and ServiceNow entries is done by name and/or IP so the names in JetPatch should match the CI names in ServiceNow. Only the matched CI will be populated.
See this article for more information
4. Ticket close call in ServiceNow can be conditioned by a property serviceNow.ticket.close.on-state
- If not set (default) the ticket close and close retry will be not condition.
If set to an expected tickets state the ticket will be tried to close when reach one of the expected states. - More then one states can be set being delimited by comma. Both display value and numerical value can be used
serviceNow.ticket.close.on-state=0,Review,Closed
Notice that ticket close retry might be disabled by setting the itsm.ticket.pg.close.retry to false (default true)
itsm.ticket.pg.close.retry=false
Then ticket close will be tried only once. If state condition test fails ticket close fails as well and will not be tried again.
Optional Step#2 - Controlling Risk value with / without using template.
Before 4.2.5, JetPatch will always send the "Risk" value as "2" and "high"
With JetPatch Version 4.2.5 and above (see below)
Using ServiceNow template you can chose which Risk value will be used once creating a remediation plan.
Below property needs to be added into the intigua.properties file, it can be used as follows:
serviceNow.risk.value=
1 - Property is not configured with any values i.e. remains null, Risk value will be taken from the template set in ServiceNow.
2 - Property is configured with values & Risk value is set on a template - Risk value will eventually will be set according to the property above.
Notes
Change Field Length
In some cases, you need to change the max length for the "Short description" and "Description" fields:
1. In the search panel, search for the JetPatch dedicated System Web Services ("Intigua Integration") and click on it.
2. In the "Web Service Fields" find the problematic field (you can go to the next page in the top right corner of the table) and click the "!" icon and Open Record:
3. Change the value in the "Length" field.
Recommended values:
- Short description = 100
- Description = 4000
Canceling a Remediation Plan
When a user cancels a Remediation Plan in JetPatch, JetPatch will try to close the ticket and won't cancel it:
Using Upload Table
body: {"u_correlation_id":"IntiguaRP_ZZZZ_AAAAAAAAAA","state":"3"}
Note: serviceNow.state.field=state
Using Main ServiceNow Table
body: {"close_code":"successful","close_notes":"Canceled","state":"3"}
To enable ServiceNow to transition a ticket from any state to the Closed state, you need to configure the state model to permit such transitions. Here's how to do it:
- Go to System Definition -> Script Includes from the left menu.
- Search for "ChangeRequestStateModel_
normal" in the "Name" column and click on it. - In the "Script" section, we need to allow the transition from each state to "closed":
-
Before doing any changes backup the existing script by copy the script content to a file and save it.
- In each state, need to add the "Close" transition
closed: { moving: function() { return this.toClosed_moving(); }, canMove: function() { return this.toClosed_canMove(); } }
Example of the changes in the "draft" state: - Save the script
-
Checking ServiceNow Properties Names for JetPatch Configuration
The properties in JetPatch configuration (intigua.properties) should match the values created in Service Now new "System Web Service" integration (intigua integration).
There are two ways to get the desired value -
- Check the WSDL of the "Intigua Integration":
- In the left menu, search for "System Web Service" and click on the JetPatch integration ("Intigua Integration).
- Click on the "WDSL" link and view the fields and view the fields name.
- Check the field name in the "System Web Service":
- In the left menu, search for "System Web Service" and click on the JetPatch integration ("Intigua Integration).
- In the table at the bottom ("Web Service Fields") check the "Name" of the fields.
Technical API calls
Create a new change request:
Method | POST |
URL | <serviceNow.hostUrl>/api/now/v1/table/<serviceNow.uploadTable> |
Body Example: | { "short_description":"Request to approve remediation plan #5001", "requested_by":"Vadim admin", "u_correlation_id":"IntiguaRP_5001_1578913047880", "u_description":"Remediation Plan #5001 was activated on Mon Jan 13 13:21:01 IST 2020\nJetPatch would like to:\nInstall patch \"SUSE-SU-2015:0377-1: moderate: Security update for unzip\" on all applicable servers from group \"SUSE 11\"\n\n", "u_remediation_plan_description":"Update unzip", "u_risk":"2", "u_requested_by":"Change Manager" } |
Expected Response: | {"result" :{ "sys_id":<sys-id> ...}} |
Notes:
- In order to use the "configuration_items" information - the ServiceNow interface should be customized to support it
- The "remediation_plan_description", "configuration_items" and "requested_by" are optional configuration. More information can be found in ITSM Integration Setup
Checking change request details:
- Before creating the change request - check if the change request exists by correlation id.
- After creating the change request - to check if it was approved.
- Before closing the change request - getting the sysid of the ticket.
Method | GET |
URL |
<serviceNow.hostUrl>/api/now/v1/table/<serviceNow.table>?correlation_id=<CORRELATION_ID> |
Body Example: | N/A |
Expected Response: |
single item in list: {"result" : [{...}]} |
Note - JetPatch is checking the value for the "approval" key when it needs to be approved.
Close change request using the main ServiceNow table (default):
Note - Default closure flow (serviceNow.ticket.close.via-upload is false)
Method | PUT |
URL | <serviceNow.hostUrl>/api/now/v1/table/<serviceNow.table>/<TICKET_SYSID> |
Body Example: | {"state":"3"} |
Expected Response: | Any JSON |
Close change request using upload table:
Note - serviceNow.ticket.close.via-upload need to be set to true
Method | POST |
URL | <serviceNow.hostUrl>/api/now/v1/table/<serviceNow.uploadTable> |
Body Example: | {"correlation_id":"IntiguaRP_5001_1578913047880", "state":"3"} |
Expected Response: | Any JSON |
Approving ticket using an external system:
Note - "ticketId" or "correlationId" - Either one is mandatory.
Method | POST |
URL | <JetPatch URL>/vmanage-server/rest/rest-api/tickets/approval |
Expected Body: | { "ticketId":"2d8c2771db5e44100f1af9afaa9619aa" "correlationId": "IntiguaRP_5001_1578913047880", "status" : "rejected", "reason" : "Need to remove patch X" } |
Response Example: | The response is the same as posted body |
Reopen rejected ticket:
Reopen the same Change ticket (default)
Method | PUT |
URL | <serviceNow.hostUrl>/api/now/v1/table/<serviceNow.uploadTable>/<TICKET_SYSID> |
Expected Body: | { "short_description":"Request to approve remediation plan #5001", "requested_by":"Vadim admin", "correlation_id":"IntiguaRP_5001_1578913047880", "description":"Remediation Plan #5001 was activated on Mon Jan 13 13:21:01 IST 2020\nJetPatch would like to:\nInstall patch \"SUSE-SU-2015:0377-1: moderate: Security update for unzip\" on all applicable servers from group \"SUSE 11\"\n\n", "remediation_plan_description":"Update unzip", "risk":"2", "assigned_to":"Change Manager" } |
Response Example: | Any JSON |
Troubleshooting
Test Communication and User Access
Run the following command from the JetPatch server manager
curl -k -u <USERNAME:PASSWORD> <serviceNow.hostUrl>/api/now/v1/table/<serviceNow.uploadTable>
Note1: If you receive an SSL error, try the following command to diagnose
Note2: curl test does not work if password has special characters in it.
Test Payload Instructions
-
Activate a Remediation Plan:
- Attempt to activate a remediation plan via JetPatch.
- ITSM ticket is not created, locate the payload details from the relevant log file from JetPatch manager log (
vmanage.log
) to identify the fields sent to ServiceNow.
-
Test the Payload via
curl
:- Use the following
curl
command to test the payload, replacing placeholders with actual values from the log or your environment.
- Use the following
curl -k -u <USERNAME:PASSWORD> -X POST \
-H "Content-Type: application/json" \
-d '{
"end_date": "<END_DATE>",
"u_description": "<DESCRIPTION>",
"u_cmdb_ci": "<CMDB_CI>",
"u_short_description": "<SHORT_DESCRIPTION>",
"u_correlation_id": "<CORRELATION_ID>",
"start_date": "<START_DATE>"
}' \
https://<serviceNow.hostUrl>/api/now/v1/table/<serviceNow.uploadTable>
If you receive an ACL error, verify the user's roles and table permissions, adjust ACL rules in ServiceNow's System Security > Access Control (ACL), and ensure REST API access is enabled.
**Issue: Missing or Incorrect `sys_target_sys_id`**
- **Cause:** When using the upload table method, the `sys_target_sys_id` field may not be populated correctly in ServiceNow due to customizations or misconfigurations.
- **Impact:** JetPatch may use a temporary process `sys_id` instead, causing failures in associating Configuration Items (CIs) or other downstream operations.
- **Resolution:**
1. Verify that the `sys_target_sys_id` field exists and is active on the `change_request` table in ServiceNow.
2. If missing or not populated, create a Business Rule in ServiceNow to populate this field automatically during CR creation (see below for details).
3. Test API responses to confirm the correct `sys_target_sys_id` is included in the payload.
**Steps to Create a Business Rule in ServiceNow:**
- Navigate to **System Definition > Business Rules** in ServiceNow.
- Create a new rule:
- **Name:** Populate `sys_target_sys_id`
- **Table:** `change_request`
- **Trigger:** On Insert
- Add the following script:
```javascript
(function executeRule(current, previous /*null when async*/) {
// Set sys_target_sys_id to the actual CR sys_id
current.sys_target_sys_id = current.sys_id;
})(current, previous);
Comments
0 comments
Please sign in to leave a comment.