ServiceNow Connector 1.0.0.2

The ServiceNow Connector is a two-way Connector that lets you:

• List, create, and update ServiceNow incidents from RunMyJobs.

• Run ServiceNow scripts from RunMyJobs.

• Import and run RunMyJobs Process Definitions from ServiceNow.

New Features in 1.0.0.2

This release includes the following enhancements and fixes.

• Added Incident Number Out parameter to Redwood_SNOW_CreateIncident_Template Process Definition.

• Fixed NullPointerException in Redwood_SNOW_CreateIncident calls when sys_row_error is not returned by ServiceNow.

Prerequisites

• RunMyJobs 9.2.9 or later.

• API Key component version 1.0.0.2 or greater. This dependency is automatically handled by the Catalog.

• Connection component 1.0.0.3 or later. This dependency is automatically handled by the Catalog.

• Privileges Required to use Connections.

• Privileges Required to use ServiceNow.

• Connection information for the ServiceNow connection:

  • Instance ID

  • Username and Password (for a Basic Auth connection)

  • An OAuth Client ID and Secret (for an OAuth Connection)

• The Redwood Automation Connector ServiceNow application from the ServiceNow App Store must be installed in your ServiceNow instance if you want to use its features (such as importing Process Definitions into ServiceNow, responding to User Messages, and so forth).

• Connectivity from the central RunMyJobs server to the ServiceNow instance.

• Connectivity from the Secure Gateway to the ServiceNow instance.

• To use the Inbound communication features from ServiceNow to RunMyJobs (in other words, to run RunMyJobs Processes from ServiceNow), one of the following is required:

  • Connectivity from the ServiceNow instance to RunMyJobs.

  • Connectivity from a ServiceNow Mid Server to RunMyJobs (see below for more details).

Redwood Automation Connector Features for ServiceNow

The Redwood Automation Connector is not required for the following actions.

• Using the Redwood_SNOW_CreateIncident_Template Process Definition to create ServiceNow incidents from RunMyJobs.

• Using the Redwood_SNOW_UpdateIncidentTemplate Process Definition to update ServiceNow incidents from RunMyJobs.

• Using the Redwood_SNOW_GetIncident definition to fetch ServiceNow incident details from RunMyJobs.

The Redwood Automation Connector is required for the following actions.

• Use the Redwood_SNOW_CreateIncident Process Definition (not the template) to create ServiceNow incidents from RunMyJobs. This Process Definition uses a staging table that is created by the Redwood Automation Connector and uses the global configuration from the Redwood Automation Connector app configuration to provide some property values automatically when creating an incident.

• Using the Redwood_SNOW_UserMessageTemplate Process Definition. If you want to use the provided UserMessage to create an incident, respond to the UserMessage from ServiceNow.

• Using the Redwood_SNOW_RunJob definition.

• Importing RunMyJobs Processes into ServiceNow and executing them from within ServiceNow.

Notes on Creating Incidents

There are some notable differences between the Redwood_SNOW_CreateIncident Process Definition and the Redwood_SNOW_CreateIncidentTemplate Process Definitions.

Redwood_SNOW_CreateIncident:

• Requires the Redwood Automation Connector ServiceNow application.

• Inserts first into a staging table, then the specified fields are combined with global values from the Redwood Automation Connector application configuration to set the incident fields.

• Does not allow setting additional fields.

Redwood_SNOW_CreateIncidentTemplate:

• Does not require the Redwood Automation Connector ServiceNow application.

• Inserts directly into the Incidents table.

• Allows the user to set any ServiceNow fields they want to by adding them as parameters on the Process Definition.

• Does not use any values from the Redwood Automation Connector ServiceNow application configuration.

Contents of the Component

Note: If you want to use the Redwood Automation Connector application, it must be installed in the target ServiceNow instance before the Process Definitions can be used.

Redwood_SNOW_CreateIncident

Creates an incident in a ServiceNow instance. For more information, see Notes on Creating Incidents.

Note: Redwood_SNOW_CreateIncident sets the values of some fields (e.g., category, subcategory, caller) automatically based on the properties set in the App Configuration page of the Redwood Automation Connector app.

Parameters

Redwood_SNOW_CreateIncident_Template

This template definition lets you specify which fields should set when creating a ServiceNow incident.

Using this template is different from using Redwood_SNOW_CreateIncident. Redwood_SNOW_CreateIncident sets the values of some fields (e.g., category, subcategory, caller) automatically based on the properties set in the App Configuration page of the Redwood Automation Connector app. This template does not look at any of those properties. It will set only whichever properties you provide as parameters on the Process Definition. It is up to you to customize any Process Definitions you create from this template.

Any parameters you add in the Incident Fields parameter group will be sent with the request. The name of each parameter must be the name of the ServiceNow field to set (not its display name). For example, use assignment_group if you want to set the Assignment Group value.

Note: For information on how to retrieve all fields from a ServiceNow table, see this post.

Parameters

Redwood_SNOW_GetIncident

Fetches incident information from a ServiceNow instance.

Parameters

Redwood_SNOW_RunJob

Executes a script that is defined in the Background Jobs section of the Redwood Automation Connector ServiceNow application. See below for more details about creating Background Jobs.

Note: It is not possible to automatically correlate logs in ServiceNow to a particular job. If you would like log entries from the job to be written to the stdout.log file of the Redwood Process, add a prefix (e.g. "Job1:" to all of your log messages in the ServiceNow script, then add that same prefix as the value of the logPrefix parameter. Any log entries with that prefix will be collected and added to the log file of the Redwood process.

Parameters

Redwood_SNOW_UpdateIncidentTemplate

Template for updating one or more fields of an existing incident in ServiceNow. To use this, clone the template to create a new definition. In the cloned definition, provide the connection name and the incident number to update. If you are providing a default connection, use this syntax: EXTConnection:Partition.ConnectionName (for example, EXTConnection:GLOBAL.ServiceNowConnection),

Any fields you want to update can be added as Job Parameters in the parameter group called 'Update Fields'. The name of the parameter should be the name of the Incident Field from the incident schema (e.g., short_description). The value of the parameter is the value to assign to that field.

Some default parameters are provided on the template as an example, but you can remove those or add different ones as needed. Only the fields specified as parameters on the process will be updated.

Parameters

Redwood_SNOW_UserMessageTemplate

Template User Message that will create a ServiceNow Incident and can be responded to from ServiceNow.

Usage: The User Message template can be used to create an incident from a RunMyJobs workflow and wait for a response before continuing. For example, If a process fails, the next Step in the Chain can be a clone of this User Message Template that creates an incident in ServiceNow. The User Message Process can then wait for a response before completing.

Unlike the Create Incident Process, when an Incident is created from this User Message template, it will appear in the Incidents view in the Redwood Automation Connector application in ServiceNow. From there, a ServiceNow user can choose one of the Response options provided by the User Message. When that is done, ServiceNow will send the UserMessage response to Redwood, the User Message process will complete, and the workflow can continue.

Note: This User Message is a Template definition and cannot be modified directly. You must create a new User Message definition from the template, then provide the details for the connection, the incident to create, and the desired response options.

Parameters

Setup

To install the ServiceNow Connector and create a connection to ServiceNow:

1. Install the Redwood Automation Connector in ServiceNow if you want to use its features. (It is no longer required for creating and updating incident reports in ServiceNow.)

2. Locate the ServiceNow Connector in the Catalog and install it. All dependencies will be installed automatically.

3. Create a ServiceNow Connection.

Creating a ServiceNow Incident from an Alert

One use case of this connector could be to automatically create a ServiceNow incident when a RunMyJobs alert is raised. Use the instructions and sample code below as a starting point for such a setup.

1. Create an alert source.

   • Create a Process Alert Source or Process Server Alert Source and configure it to raise an alert for the desired objects and events.

2. Create an Alert Gateway that will perform the action to create the incident.

   • Create a new Email Alert Gateway.

   • Set the Address Pattern to an alias or address that matches the address in the desired Alert Source(s).

   • Display or click the Actions tab.

   • Create a Pre-Send Action if one is not already present.

   • Choose a user role from the Action Subject dropdown list. This is the context that will be used to process the action. The user role must have Read permission on the ServiceNow Connection and Submit permission on the Redwood_SNOW_CreateIncident Process Definition.

   • In the Source field, write code to submit the Redwood_SNOW_CreateIncident Process Definition. This will create a ServiceNow incident when the alert is raised. Use the sample code below as a starting point. At a minimum, you will need to change the value of the connectionKey variable to the correct value for your configured ServiceNow connection.

{
  Alert alert = jcsEmailAlertGatewayPreSendActionContext.getAlert();

  // Prevent sending the email since we want to create an incident instead
  jcsEmailAlertGatewayPreSendActionContext.setSend(false);

  // Reply to the Operator Message and acknowledge the alert
  OperatorMessage operatorMessage = alert.getOperatorMessage();
  operatorMessage.setReply("Acknowledged");
  alert.setStatus(AlertStatus.Acknowledged);

  // Set up the business key for the ServiceNow connection to use.  
  // It must be in the format "EXTConnection:<ConnectionPartition>.<ConnectionName>",  
  // EXAMPLE: EXTConnection:GLOBAL.MyServiceNowConnection
  String connectionKey = "EXTConnection:GLOBAL.MyServiceNowConnection";

  // Prepare the incident descriptions based on the object type that caused the alert
  String shortDescription = "";
  String description = "";
  SchedulerEntity schedulerEntity = operatorMessage.getSenderObject();
  if (schedulerEntity instanceof Job)
  {
    Job requestingProcess = (Job)schedulerEntity;
    shortDescription = "Job " + requestingProcess.getJobId() + " " + requestingProcess.getDescription() + " ended in status " + requestingProcess.getStatus();
    description = "Job " + requestingProcess.getJobId() + " " + requestingProcess.getDescription() + " ended in status " + requestingProcess.getStatus();
  }
  else  if (schedulerEntity instanceof ProcessServer)
  {
    ProcessServer requestingProcessServer = (ProcessServer)schedulerEntity;
    shortDescription = "Process Server " + requestingProcessServer.getName() + " is in status " + requestingProcessServer.getStatus();
    description = "Process Server " + requestingProcessServer.getName() + " is in status " + requestingProcessServer.getStatus();
  }
  else
  {
    return;
  }

  // Submit the job to create the incident
  JobDefinition jd  = BusinessKeyLookup.getJobDefinitionByBusinessKey(jcsSession, "REDWOOD.Redwood_SNOW_CreateIncident");
  Job process = jd.prepare();
  process.getJobParameterByName("connection").setInValueString(connectionKey);
  process.getJobParameterByName("shortDescription").setInValueString(shortDescription);
  process.getJobParameterByName("description").setInValueString(description);
  process.getJobParameterByName("impact").setInValueString("3 - Low");
  process.getJobParameterByName("urgency").setInValueString("3 - Low");
  process.getJobParameterByName("assignmentGroup").setInValueString("Scheduling Alerts");
}