Cherwell

Introduction

Cherwell Service Management is a cloud-based IT service management solution that helps IT teams in organizations to implement, automate and upgrade service and support processes.

OpsRamp configuration

Configuration involves:

1. Installing the integration.
2. Configuring the integration.

Step 1: Install the integration

To install:

1. From All Clients, select a client.
2. Go to Setup > Integrations > Integrations.
3. From Available Integrations, select Collaboration > Cherwell.
4. Click Install.

Step 2: Configure the integration

Configure the following: - Inbound - Outbound - Monitoring of Integration - Audit Logs

Inbound

To send entities from Cherwell to OpsRamp:

1. Authentication: Configure the authentication to call Cherwell APIs.
   1. Select Authentication Type Basic from the drop-down and click Save.
   2. Take note of the Tenant Id and Token. This would be used while creating and updating ticket in Cherwell.

      

2. Map Attributes: Map Cherwell attributes with OpsRamp entity attributes.
   1. Select OpsRamp entity from the drop-down menu.
   2. Click Map against respective attribute, provide the mapping details and click Save.

Outbound

To send entities to Cherwell from OpsRamp:

1. Integration Basic Configuration: Configure notification details to trigger integration events.
   1. Notification type: REST API
   2. Base URL: http://opsramp.demo.cherwell.com/CherwellAPI/token?auth_mode=Internal
   3. Authentication type: OAUTH2
   4. Click Save.
   5. Take note of Tenant Id, Key, and Secret. These would be used to configure REST API clients in Cherwell.

      

2. Map Attributes: Map OpsRamp entity attributes with Cherwell attributes.
   1. Select OpsRamp entity as Incident and OpsRamp property as Priority from the drop-down.
   2. Click Map against the respective attribute. Create Integration Mapping window appears.
   3. Provide the values and click Save.

      

3. Integration Events: Events are for sending notifications whenever an action is performed on OpsRamp entities.
   1. Click Add to add an integration event. Add Integration Event page appears.
   2. Provide a name for the integration event.
   3. Select Service Desk from the drop-down and then select entity type and action.
   4. Select Parent Configuration to assign the basic integration details configured in step 1.
   5. Provide endpoint URL.
   6. Select the web method, provide the header name and value.
   7. Provide the payload and click Save.

      

      • To parse the properties returned in response for the payload, select the OpsRamp property from the drop-down and provide the value.
      • A custom field that is already configured as response payload attribute for a given integration is not available for configuration in any other integrations. You need to remove the existing mapping from the integration to make the custom field available to map on response payload of any other integration.
4. Verify Integration: Validate if the integration is successful.
   1. Select the event from the drop-down and provide the JSON payload.
   2. Click Verify to verify the integration.
5. Integration Failures: In the case of failure in integration, a message is sent to the user about the failure.
   • Select notification type Email, provide the email address and then click Save.

Integration Event Payloads

The following are field and example payloads to create incidents.

Create incident

Request

The following is a sample request:

{
	"busObId": "6dd53665c0c24cab86870a21cf6434ae",
	"busObName": "Incident",
	"fields": [{
			"fieldId": "93e8ea93ff67fd95118255419690a50ef2d56f910c",
			"name": "ShortDescription",
			"value": "$incident.subject",
			"dirty": "true"
		},
		{
			"fieldId": "252b836fc72c4149915053ca1131d138",
			"name": "Description",
			"value": "$incident.impact",
			"dirty": "true"
		},
		{
			"fieldId": "83c36313e97b4e6b9028aff3b401b71c",
			"name": "Priority",
			"value": "[@$incident.priority.name@]",
			"dirty": "true"
		},
		{
			"fieldId": "5eb3234ae1344c64a19819eda437f18d",
			"name": "Status",
			"value": "[@$incident.status.name@]",
			"dirty": "true"
		},
		{
			"fieldId": "933bd530833c64efbf66f84114acabb3e90c6d7b8f",
			"name": "CustomerRecID",
			"value": "9337c2322a087296f7322a481d8858300e3f6e1dbb",
			"dirty": "true"
		},
		{
			"fieldId": "936725cd10c735d1dd8c5b4cd4969cb0bd833655f4",
			"name": "Service",
			"value": "Account Management",
			"dirty": true
		},
		{
			"fieldId": "ae05c132527e48bd95d063c445622df7",
			"name": "Impact",
			"value": "Department",
			"dirty": true
		},
		{
			"fieldId": "29d741aae8bf461f8aafa3c9eb4dc822",
			"name": "Urgency",
			"value": "Medium",
			"dirty": true
		},
		{
			"fieldId": "943f9d35d7ec5d7dc0921a41609d8e93b03a62d190",
			"name": "OpsRamp Inc ID",
			"value": "$incident.uniqueId",
			"dirty": true
		},
		{
			"fieldId": "9339fc404e4c93350bf5be446fb13d693b0bb7f219",
			"name": "Owned By",
			"value": "Andrew Simms",
			"dirty": true
		}
	]
}

Response

The following is a sample response:

{
	"busObPublicId": "102375",
	"busObRecId": "943f5ba5a1cb1fe68918764510ba96442c3a85e5d0",
	"cacheKey": null,
	"fieldValidationErrors": [],
	"notificationTriggers": [],
	"errorCode": null,
	"errorMessage": null,
	"hasError": false
}

Cherwell configuration

Configuring Cherwell incidents with OpsRamp involve the following:

• Configuring REST API Client.
• Configuring Web Services Manager.
• Configuring One-Step.

Step 1: Configure the REST API client

Cherwell Service Management(CSM) Administrator supports OAuth2 protocol to authenticate and authorize calls to the REST API. The OAuth2 protocol enables third-party clients to get access to HTTP services.

To configure the REST API client:

1. Login to Cherwell Service Management Administrator.
2. Click Categories and then click Security.
3. Select Edit REST API client settings from the Pick a task menu.

   

4. Click the Plus icon to create new REST API client.
5. Provide the following:
   • Name: Provide a name (Example: OpsRamp REST API)
   • Culture: Default value
   • Description: Provide details (Example: To configure CSM OAuth details in OpsRamp to call Cherwell APIs)
   • Client Key: Auto-generated value (Use the Client Key from the OpsRamp outbound configuration.)
   • Token Lifespan: Default value
   • Refresh Token Lifespan: Default value
   • API access is enabled: Active
   • Allow anonymous access: Active

     

6. Click OK to save the details.

Step 2: Configure the Web Services Manager

Configure OpsRamp REST API details in Web Services Manager. Cherwell uses these details to call OpsRamp APIs to integrate respective entities.

To configure Web Services Manager:

1. Click Categories and then click Browser and Mobile.
2. Select Web Services Manager.

   

3. Click the Plus button to create a new Web Service.
4. Go to General to configure a web service, provide the following and click OK.:
   • Name: Provide a name to web service (Example: OpsRamp Incident API)
   • Description: Provide details about web service (Example: API to create/update incident in OpsRamp)
   • URL: Provide OpsRamp API URL. (Example: https://api.vistanet.jp)
   • Service Type: REST
   • Security Type: Basic
   • Always call web service from Cherwell Server: Default value
   • Log calls to this web service: Select Active

     

5. Go to Method > Create Incident, click Add to configure a create incident API:
6. Go to Method > Update Incident, click Add to configure an update incident API:

Create incident method

To configure OpsRamp create incident APIs:

1. From Methods > Create Incident, click Add.

   

2. Provide the following:
   • Name: Provide a name to the method (For example: Create Incident)
   • Description: Give details about method (For example: OpsRamp create incident API details)
   • End point: api/basic/tenants/{OpsRamp client Id}/incidents 
     For example: api/basic/tenants/client_392/incidents
   • Result Type: JSON
   • Request Type: POST

     

   • Parameters:
     • Payload:
       • Name: payload
       • Data Type: text
       • Param Type: Standard
       • Is content: Active
     • Content-Type
       • Name: Content-Type
       • Data Type: text
       • Param Type: Header
     • Authorization
       • Name: Authorization
       • Data Type: text
       • Param Type: Header
3. Click OK to save the method.

Create update method

To configure OpsRamp update incident APIs:

1. From Methods > Update Incident, click Add.
2. Provide the following:
   • Name: Provide a name to the method (For example: Update Incident)
   • Description: Provide details about method
     For example: OpsRamp update incident API details
   • End point: api/basic/tenants/{OpsRamp client Id}/incidents/{opsRampIncidentId} 
     For example: api/basic/tenants/client_392/incidents/{opsRampIncidentId}
   • Result Type: JSON
   • Request Type: POST

     

   • Parameters:
     • Payload:
       • Name: payload
       • Data Type: text
       • Param Type: Standard
       • Is content: Active
     • Content-Type
       • Name: Content-Type
       • Data Type: text
       • Param Type: Header
     • Authorization
       • Name: Authorization
       • Data Type: text
       • Param Type: Header
     • OpsRamp Incident Id
       • Name: opsRampIncidentId
       • Data Type: text
       • Param Type: Endpoint
3. Click OK to save the method.

Step 3: Configure One-Step

One-Step consists of a series of actions and can be simple (a few actions) or complex (multiple actions that run under conditional circumstances).

To configure One-Step:

1. Ensuring that the prerequisites are completed.
2. Creating an incident.
3. Updating an incident.

Sub-step 1: Perform prerequisites

The following steps are required before configuring One-Step:

• Create a custom field (OpsRamp Inc ID) to save the OpsRamp incident Id in Cherwell incident table.
• Configure lookup tables for priority and status to map OpsRamp attributes with Cherwell attributes.

Sub-step 2: Create incidents

To create an incident:

1. Click One-Step and then click One-Step Manager.

   

2. From the Association drop-down, select Incident.
3. Click the Plus button to create new One-Step.
4. Provide the following:
   • Name: Provide name (Example: OpsRamp Create Incident)
   • Description: Provide details of One-Step (Example: One-Step to call OpsRamp Incident REST API)

     

5. Click OK. One-Step editor window appears.
6. Configure the following actions and click Ok:

Action-1: Configure Step details

1. General: Details provided while creating new One-Step will be auto-populated. Edit if required.
2. Conditions: Optional

   

Action-2: Configure web service details

1. Click Advanced Actions and then click call a web service to configure web service details.
2. Add the General information:
   • Name: Provide a name to the web service (Example: Call a web service)
   • Service: Select the web service created in CSM administrator. (OpsRamp Incident API)
   • Account: Select the authentication account created in CSM administrator. (OpsRamp Account)
   • Store result as: RestResult
   • Store return code as: ReturnCode
   • Store header as: WebHeader
   • Don’t stop One-Step on error: Not applicable

     

3. Add the Method information and click OK.
   • Method: Select the web service method created in CSM administration portal. (Create Incident). Select Set Value.
   • Parameters: Provide the field values and payload information.
   • Annotation: Default value.

Field values:

Payload:

{
    "subject": "Incident.Short Description",
    "description": "Incident.Description",
    "priority": "Incident.OpsRamp Priority",
    "extTicketId": "Incident.Incident ID"
}

Action-3: Update a Business Object

Updating a Business Object parses OpsRamp incident Id from a response and saves OpsRamp incident as Cherwell incident. Before configuring this action, create a custom field for the incident (OpsRamp Inc ID).

1. Go to Advanced Actions > Update a Business Object to configure details.
2. Add the General information:
   • Name: Provide a name (Example: Save OpsRamp Incident Id)
   • Business Object: Incident
   • Reload business object before update: Default value
   • Save business object after action: Default value

     

3. In the Fields section, click OpsRamp Inc ID and select Template.
4. Provide the value as RestResult, select RestResult, right click and select Modifiers, and provide the following:
   • Modifier: Select Find Object
   • Text: Provide value (Id)
   • Annotation: Default values
5. Click OK to save the details.

Sub-step 3: Update incidents

To update an incident using One-Step:

1. Click One-Step and then click One-Step Manager.
2. From the Association drop-down, select Incident.
3. Click the Plus button to create new One-Step.
4. Provide the following:
   • Name: Provide name (Example: OpsRamp Update Incident)
   • Description: Provide details of One-Step (Example: OpsRamp Update Incident One Step)
5. Click OK. One-Step editor window appears.
6. Configure the following actions and click OK.

Action-1: Configure Step details**

• General: Details provided while creating new One-Step will be auto-populated. Edit if required.
• Conditions: Optional

Actions-2: Configure Web Service details**

1. Go to Advanced Actions > call a web service to configure web service details.
2. Add the General information:
   • Name: Provide a name to the web service (Example: Call a web service)
   • Service: Select the web service created in CSM administrator. (OpsRamp Incident API)
   • Account: Select the authentication account created in CSM administrator. (OpsRamp Account)
   • Store result as: Not applicable
   • Store return code as: Not applicable
   • Store header as: Not applicable
   • Don’t stop One-Step on error: Not applicable
3. Add the Method information:
   • Method: Select the web service method created in CSM administration portal. (Create Incident). Select Set Value.
   • Parameters: Provide the field values and payload.
4. Click Ok.

Field values

Payload:

{
    "subject": "Incident.Short Description",
    "description": "Incident.Description",
    "priority": "Incident.OpsRamp Priority",
    "extTicketId": "Incident.Incident ID"
}

External references

• About One-Steps