ServiceNow Connector 1.0.0.3

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

The Redwood_SNOW_CreateIncident_Template, Redwood_SNOW_UpdateIncidentTemplate, and Redwood_SNOW_UserMessageTemplate templates let you attach files to the Service Now incident while creating/updating it. .

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)

Contents

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.

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, or if you need to run a (Undefined variable: General.Job) Definition that requires it.

2. To install the ServiceNow Connector, click its tile in the Catalog, select the version you want, and then click Install <version number>.

3. Create a ServiceNow Connection.

Process Definitions

Redwood_SNOW_CreateIncident

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

Note: Redwood_SNOW_CreateIncident requires the Redwood Automation Connector to be installed in ServiceNow.

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 Proicess 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: Redwood_SNOW_CreateIncident_Template does NOT require the Redwood Automation Connector to be installed in ServiceNow.

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

Process Definitions created from this template can create an incident from within a RunMyJobs Workflow, and then wait for a response before continuing. For example, If a Process fails, the next Step in the Chain can be a clone of this template that creates an incident in ServiceNow. The User Message Process can then wait for a response before completing.

Unlike incidents created with the Redwood_SNOW_CreateIncident Process Definition, incidents created from this template display 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 User Message response to RunMyJobs, 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.

To use this template, you must meet the following requirements:

• Redwood Automation Connector must be installed in ServiceNow.

• RunMyJobs must have connectivity to either the ServiceNow instance or a ServiceNow Mid Server.

• The user running the User Message Process must have a valid email address.

To respond to the incident from ServiceNow:

1. Navigate to Redwood Automation Connector > Incidents.

2. Open the incident and click the Process Remediation tab.

3. Choose Accept or Reject.

4. Click Execute. The response you selected will be reflected on the User Message Process in RunMyJobs.

Parameters

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.

Procedures

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

Attaching Files to a ServiceNow Incident

The following two sections describe how to attach a file to a ServiceNow incident.

Attaching Files When You Create or Update a ServiceNow Incident

To attach one or more files to a ServiceNow incident while creating or updating the incident:

1. Right-click the Redwood_SNOW_CreateIncident_Template or Redwood_SNOW_UpdateIncidentTemplate Process Definition and choose New (from Template). The New Process Definition window displays.

2. Choose a Partition and enter a Name.

3. Click the Parameters tab. The list of Parameters from the template displays.

4. Add a File Parameter for each file you want to attach to the ServiceNow incident. Set the Group Name to Attachments for each Parameter you create.

5. Save and close the Process Definition.

When you submit the resulting Process Definition, whether manually or as part of a Chain, you can specify the files on the File parameters you created.

Attaching Files to a ServiceNow Incident with a User Message

To attach one or more files to a ServiceNow incident using a User Message within a Chain:

1. Right-click the Redwood_SNOW_UserMessageTemplate Process Definition and choose New (from Template). The New User Message Definition window displays.

2. Choose a Partition, enter a Name, and do any other desired configuration for the User Message.

3. Save and close the Process Definition.

4. Create a Chain Definition with a Chain Process that produces an output file (for example, stdout.log).

5. Determine the Parameter mapping for the output file. For example, if the Chain Process that produces the output file is the first Chain Process in Step 1, the mapping would be Step 1, Job 1:stdout.log.

6. Add your User Message Process Definition to Step 2 of the Chain.

   

7. Select the User Message Chain Process in Step 2, then click the Attachments tab at the top and click to add a row.

8. To map the output from the first Chain Process to the User Message Chain Process, enter the mapping from step 5 (Step 1, Job 1:stdout.log) in the Specification column.

   

9. Repeat Step 8 for any other files you want to attach to the ServiceNow incident.

10. Save and close the Chain Definition.

When you submit the resulting Chain Definition, the output from the Chain Process in Step 1 is added to the ServiceNow Incident created by your User Message Chain Process in Step 2.