ServiceNow Connector 1.0.0.0

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.

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.

• 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).

Contents of the Component

Note: The Redwood Automation Connector application must be installed in the target ServiceNow instance before the Process Definitions can be used.

Redwood_SNOW_CreateIncident

Creates a ServiceNow Incident. Provide the details required to create the incident, and the new Incident Number is returned as an Output Parameter after the Process completes successfully.

Parameters

Redwood_SNOW_GetIncident

Fetches incident information from a ServiceNow instance. Provide the Incident Number of the incident to fetch, and its details will be printed to the stdout.log file and also in a job file called IncidentInfo.rtx which can be used if downstream processing is required.

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 will 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.

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");
}