# Cherwell Connector

The Cherwell workflow connector allows workflow designers to create, read, and update Cherwell business objects programmatically using the Cherwell REST API.

# Cherwell Connector Configuration

The Cherwell connector uses a combination of credential authentication and session tokens to access the REST API endpoints. It calls the Cherwell login endpoint using a username and password to retrieve a session token which it stores in memory for a length of time determined by the environment's configured session timeout value. It then uses this session token to access the REST endpoints and retrieves a new token when the current token expires.

To configure the connector select: Manage > Connector Configuration > New Config from the workflow designer then select Cherwell as the Connector Type.

Example Connector Configuration:

<cherwell>
     <scenarios>
          <scenario name="CherwellTest" default="true" username="__username__" client_id="encrypted _client_id" tokenurl="https://hostname.com/CherwellAPI/token" auth_mode="Internal" baseurl="https://hostname.com/CherwellAPI/api/V1/" password="password_encrypted" authType="token" />
     </scenarios>
</cherwell>

Note -- the passwords need to be encrypted with encrypt method 2 and only one scenario should have the default = true attribute.

Each action accepts a scenario name which needs to match the given scenario name found in this XML blob. Multiple scenarios can be defined by adding additional scenario nodes to this XML structure. This allows the connector to access multiple environments and/or use different credentials. The based URL attribute should be defined as shown below:

# Cherwell Connector Actions

# Create Incident

Action Function:

The Cherwell create incident action gives the workflow designer the ability to create an incident in Cherwell.

Action Outputs:

Success

Failure

Action Properties:

Scenario -- The name of the scenario defined in the connector configuration XML. Leave blank to use the default scenario. (A default scenario must be defined and is specified by using the attribute default="true" in the connector configuration XML)

WebTimeout(sec) -- How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.

Results Variable-- A workflow variable which will hold the response of the request. The data format is JSON.

Public Id Result -- Variable which will hold the Public Id of the newly created incident.

Record Id Result -- Variable which will hold the Record Id of the newly created incident.

Error Message Variable -- A workflow variable which will hold the error message (if any).

Extra properties can be added to the action XML to pass specific field information to Cherwell when this action creates an incident. Additional property nodes need to have the attributes includeField="true" and subType = "fields".

For example, the Description field would look like this:

<property name="Description" displayname="Description" type="workflowmemo" includeField="true" subType="fields" helpstring="Description" mandatory="true"></property>

# Update Incident

Action Function

The Cherwell update incident action gives the workflow designer the ability to update an incident in Cherwell.

Action Outputs:

Success

Failure

Action Properties:

Record Id -- The busObRecId of the incident.

WebTimeout(sec) -- How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.

Results Variable-- A workflow variable which will hold the response of the request. The data format is JSON.

Error Message Variable -- A workflow variable which will hold the error message (if any).

Extra properties can be added to the action XML to pass specific field information to Cherwell when this action updates an incident. Additional property nodes need to have the attributes includeField="true" and the subType = "fields". If a field property is left blank, that field won't be updated.

# Get Business Object

Action Function:

The Cherwell get business object action gives the workflow designer the ability to get a business object in Cherwell. It returns a JSON document and an XML document describing the business object instance. This action can specifically be used to get an incident by passing in the incident business object Id.

Action Outputs:

Success

Failure

Action Properties:

Business Object Id --The Id of the business object type to get.

Type -- The type of identifier that will be used in the property Record or Public Id. There is a choice of record Id or public Id.

Record or Public Id -- The record or public Id of the instance of the specified business object.

WebTimeout(sec) -- How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.

Results Variable -- A workflow variable which will hold the response of the request. The data format is JSON.

Xml Results Variable -- An XML variable to hold the response of the request.

Error Message Variable -- A workflow variable which will hold the error message (if any).

# Get Business Object Summary

Action Function:

The Cherwell get business object summary action gives the workflow designer the ability to get a business object summary in Cherwell. It returns a JSON document describing the business object.

Action Outputs:

Success

Failure

Action Properties:

Id or Name --The Id or name of the business object type to get.

Type -- The type of identifier that will be used in the Id or Name property. There is a choice of Id or Name.

WebTimeout(sec) -- How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.

Results Variable -- A workflow variable which will hold the response of the request. The data format is JSON.

Error Message Variable -- A workflow variable which will hold the error message (if any).

# Get Business Object Summaries

Action Function:

The Cherwell get business object summaries action gives the workflow designer the ability to get multiple business object summaries in Cherwell. It returns a JSON document describing the business objects.

Action Outputs:

Success

Failure

Action Properties:

Type -- The type of business objects to return. Selecting "All" returns a lot of data.

WebTimeout(sec) -- How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.

Results Variable -- A workflow variable which will hold the response of the request. The data format is JSON.

Error Message Variable -- A workflow variable which will hold the error message (if any).

# Get Business Object Template

Action Function:

The Cherwell get business object template action gives the workflow designer the ability to get the template of a business object in Cherwell. It returns a JSON document describing the business object fields.

Action Outputs:

Success

Failure

Action Properties:

Bus. Obj. Id -- The business object Id.

Include All Fields -- Specifies whether or not to include all of the fields.

Include Required Fields -- Setting to true will return all of the required fields for the business object (unless Include All = true or Fields are specified)

Fields -- A comma delimited list of the field names that should be returned.

Web Timeout(sec) -- How long in seconds the HTTP request is given before timing out. Leave blank to use the default timeout setting.

← System Settings Microfocus HPSM Connector →