Introduction

ConnectALL has added support for synchronizing Cherwell Service Management systems data to our ever-expanding application endpoint list. Cherwell® Service Management (CSM) is a configurable, scalable, Out-Of-The-Box (OOTB) service desk solution based on IT Service Management (ITSM) best practices and the ITIL framework. 

Supported Authentication

(tick) OAuth2 (Internal Mode)

Supported Entity

(tick) Major/Supporting Business Objects

Supported Functionalities

(tick) Bi-Directional Synchronization

(tick) Record filtering

(tick) Comment synchronization (JournalNotes, JournalComment, JournalHistory, and some others)

(tick) Attachment synchronization (Imported Files only)

(tick) Synchronize relationships (Parent-Child relationships)

(tick) Issue Linking

Connection

Cherwell Service Management secures the ReST APIs with OAUTH2, SAML authentication protocols

  • When using OAUTH2 protocol, CSM acts as both Identity Provider and Service Provider.
  • When using SAML protocol, CSM acts only as a Service provider, SAML protocol introduces a 3rd party Identity Provider.
  • Obtain a ClientId from CSM administrator. Read the steps to generate the client id.
  • OAuth2 provides four authentication modes "Internal", "LDAP", "SAML" and "Windows". The ConnectALL Cherwell Service Management adapter currently supports "Internal" mode authentication alone.

ConnectALL Cherwell Service Management adapter will only support the "Internal" authentication mode where the CSM acts both as an Identity provider and the service provider.

Example

Entity Mapping

Cherwell Service Management application classifies BusinessObjects as Major, Supporting, Lookup and Group. ConnectALL Cherwell Service Management adapter provides synchronization capabilities for all the "Major" business objects. These objects will be listed for mapping with the destination system in the entity mapping screen as shown below:

Date Time Format

Date Time Format

Set the below provided date and time format in the  Date Formats field (Entity Mapping>Flow Properties) for Cherwell, to ensure smoother synchronization.
M/d/yyyy,yyyy/MM/dd,M/d/yyyy hh:mm:ss a,M/d/yyyy hh:mm a 



When you create an app-link between Cherwell and any other adapter, ensure that you provide the date format for the other adapter as M/d/yyyy,yyyy/MM/dd,yyyy-MM-dd HH:mm:ss.SSS,yyyy-MM-dd HH:mm:ss,yyyy-MM-dd (in the left side application).

Date Formatting

ConnectALL allows you to configure the date formats used to read the date fields from the Cherwell Service Management business object records. When synchronizing date fields, it is advised to validate the date formats and add any additional formats required in the comma-separated string in "Date Formats" as shown above. 

The following date formats — M/d/yyyy,yyyy/MM/dd,yyyy/MM/dd'T'hh:mm:ss, M/d/yyyy hh:mm:ss a  support most of the Cherwell Service Management application date formatting needs.

Time Difference

To know how to calculate the time difference and configure it in the ConnectALL UI, please see the topic Time Difference Configuration.

Important Information

The ‘ReviewByDeadline’ date provided by the Cherwell API will provide the value as "1/1/1900 12:00:00 AM" when the value is not available in a record. If you do not want to synchronize the default value, you can add it by including ‘Value Skip’ in the value mapping configuration as illustrated in the below image.  Note that if you are mapping the values using ‘Value Skip’, adjust the time value to the UTC timezone and provide the date in the format — "YYYY-MM-dd HH:mm:ss.SSS".  This has to be done as a part of the ‘Value Skip’ configuration.

We have provided below some of the timezones and its adjusted value in the UTC.

Cherwell TimezoneData format if you are using Value Skip
PST1900-01-02 08:00:00.000
EST1900-01-02 05:00:00.000
IST1899-12-31 18:30:00.000

Custom Business Objects

ConnectALL supports synchronizing Major custom BusinessObjects that adhere to the assumptions listed below. 

  • A field with id "RecId" is available and it holds the unique record id of the Business object
  • A field with Id "LastModDateTime" is available and it holds the time the business object was last modified (Date should be in one of the formats defined as defined in Date Formatting secion)
  • For synchronizing the Parent-Child issue linking, ConnectALL expects to have 
    • A field with "ParentTypeID" holding the value of Business Object Type Id
    • A field with "ParentTypeName" holing the value of parent Business Object type
    • A field with "ParentPublicID" holding the readable record of the Parent Business object
    • A field with id as "ParentRecID" holding the unique record id of the Parent Business object
Important Information
  • When you choose the LastModifiedDateTime field, you will have to choose the corresponding data type as 'LastUpdatedDt' from the Field Configuration screen as shown below. By default, the datetime option will be selected. If the LastModifiedDateTime field is not configured, an error will be displayed, prompting you to configure it.
  • If the custom object does not have the LastModifiedDateTime field, you will need to choose a date field manually that should be considered as LastUpdatedDt in the below screen.
  • If a field called LastModifiedDateTime exists along with LastModDateTime, choose the LastUpdatedDt datatype on the field that you want to use as the change date.

Rich Text Fields

By default, the data type will be PlainText for Comments and Description. If you want the rich text fields to be supported, please select the Data Type as InlineHTML in the above screen. This will allow the formatting to synchronize successfully.

Use Custom Journal Objects to Synchronize as Comments 

By default, ConnectALL supports synchronizing comments from ‘JournalNote’, 'JournalHistory', and ‘JournalComment’. ConnectALL also allows you to use custom Journal objects for synchronizing as comments. Synchronizing comments through these custom Journal objects can now be achieved by adding them to the connection information you create for the Cherwell instance. To include a Journal object comment on the Cherwell connection, follow the below procedure:

  1. Click Connections in the top navigation bar. The Manage Connections screen will be displayed. 

  2. Click the cogwheel icon (1) against the connection. The following screen will be displayed.


  3. Enter the Property Key (2) and Property Value (3) in the respective fields as shown in the image. Enter "commentFieldIds" for the Property Key. Enter your fully qualified custom object name in Cherwell for the Property Value. (i.e., enter the parent group object's internal name, a dot ("."), followed by the custom journal object's internal name.)
    • To find the internal name in the Cherwell Service Management Administrator, edit the business object, and click the “Bus Ob Properties” button. The value in the "Internal name" field is the Journal Object name to be configured in the property value, prefixed with the parent object's internal name. The same approach may be used to find the parent object's internal name.
    • If you want to enter more than one property value (for multiple custom Journal comment objects), you can enter the values separated by commas. For example: "journal.JournalCustom,Journal.Journalbussobj2,JournalIncidents.Incidents_Default"
  4. Click Save Properties to save the advanced properties. If you want to add more properties use the ‘+’ icon.

The field is now added to your Cherwell connection instance. As Cherwell fields API does not provide the fields such as journal comments or the journal custom objects, the fields have to be added in the User Fields Configuration screen. This enables them to appear on the Field Mapping screen. To add these objects as a field in the User Fields screen:

  1. Click the cogwheel icon on the right side of the navigation bar and click User Fields from the drop-down list. The User Fields screen will be displayed.
  2. Click the Connection tab (1).



  3. Click the Application Type drop-down list (2), select Cherwell Service Management, and click Search. The connections for Cherwell will be displayed.
  4. Click on the Cherwell Instance (3) in which you have added the property value and property key.
  5. Add the field as shown in the Configured Fields section (4) and click Add Field. The Id will be the same as the Property Key used above. Name can be any descriptive name that you wish.

You have successfully added the field. And it will now appear in the Field Mapping section.

Poll Query

ConnectALL provides a way to filter the records that are pulled from the Cherwell Service Management application using the "poll query" feature as shown below:

Poll Query Formatting

Poll queries are written as a concatenated string of multiple "FilterInfo" components. Each "FilterInfo" components takes the format [<fieldname>{<op>}'<value>']. For more information on Operators and Filters refer Cherwell Service Management documentation

FormatExampleRemarks
[<fieldname>{<op>}'<value>']
CODE 
[priority{eq}'1']
CODE
Filter records with Priority as 1
[<fieldname1>{<op1>}'<value1>'][<fieldname2>{<op2>}'<value2>']
CODE 
[priority{eq}'1'][LastModifiedDateTime{gt}'2019-04-09T13:05:21']
CODE
Filter records with Priority as 1 and Modified after 2019-04-09T13:05:21 
[<fieldname1>{<op1>}'{<value1>'][<fieldname1>{<op2>}'{<value2>']
[<fieldname2>{<op3>}'{<value3>']
CODE 
[priority{eq}'1'][priority{eq}'3']
[LastModifiedDateTime{gt}'2019-04-09T13:05:21']
CODE
Filter records with Priority as 1 or 3 and Modified after 2019-04-09T13:05:21

Field Mapping

ConnectALL Cherwell Service Management adapter has the capability to read the schema of the business object chosen and populate the field list for mapping as shown below:

Value Mapping

ConnectALL will dynamically fetch the allowed values for a given field from "Lookup Objects" when performing value mapping of a selected mapped field.

Comment Synchronization

Cherwell Service Management tracks the comment and record modifications as a "Journal" object which is a Group. "Journal Group" has multiple children. JournalNote and JournalComment are among them. These two objects provide the comment handling behavior of the Cherwell Service Management application. ConnectALL provides the capability to synchronize comments from destination systems in one of these objects. 

As on date Comment edit feature is not supported by Cherwell Service Management adapter, i.e., any edits to existing comments will be synchronized as new comments

Comment Field Mapping

Attachment Synchronization

Cherwell Service Management has the capability of attaching:

  • files as third-party URLs
  • attaching other business objects within the system
  • files by importing the file content into the system

ConnectALL currently supports the import file feature of Cherwell Service Management only. Any URL attachments or attached business objects will be ignored.

Note: Avoid including '+' character in the attachment's file name, as it will affect the synchronization. This is due to a limitation in the Cherwell application. 

The Cherwell Service Management adapter does not currently support 'Attachment Delete'. Any attachments deleted in the destination system will not be deleted in the Cherwell Service Management application.

Attachment Field Mapping

Relationship Synchronization

ConnectALL allows you to synchronize parent-child relationships between Cherwell Service Management and destination systems. A typical use case is as follows: An IT support engineer receives an Incident request from a customer logged into Cherwell Service Management. After the analysis, the support engineer will log a "Problem" in Cherwell Service Management which will be synchronized by ConnectALL as a Jira issue. As the engineering team starts to work on the Jira issue, any subtasks created under the Jira issue are to be synchronized as Cherwell Service Management tasks under the associated problem. 

Issue Linking

Issue linking is supported in Cherwell. Let's say you want to synchronize issue links in an app-link between Jira and Cherwell, To do that,

  1. Create two app-links: 
    1. 1st app-link — between Task (Jira) ↔ Incident (Cherwell). 
    2. 2nd app-link — between Bug (Jira) ↔ Problem (Cherwell). 
  2. In the 1st app-link, do the field Mappings as shown below:

  3. Click the pencil icon against the row and select 'incident links problem' on the Cherwell side that links incident and the problem. 



  4. In the second app-link, create a field mapping between Summary and Description.

          The above example illustrates one to one linking where an Incident is linked to a Problem (see the chosen option in the above image). You can also link one 'Incident' to similar 'Incidents'. If you want to do that, then choose the option as shown in the below image:

         

Configuration 

ConnectALL associates these relationships when a field mapping to "Parent TypeId" or "Parent TypeName" fields is present. 
 

 

"ParentTypeId" expects a hex value like "6dd53665c0c24asdfaca6123421cf6434ae" while the "ParentTypeName" expects a readable object name like "Incident".

Mapping "ParentTypeId" has a significant performance boost. That removes the need for ConnectALL to resolve the ID during synchronization.

Similar to the "ParentType" field, you can also configure "Parent Record fields" to a custom field. So, ConnectALL can associate the relationships based on the value in the field.
Users can choose to map either the Public Id or Rec Id fields to the custom field as given below. 

"ParentRecId" expects a hex value like "6dd53665c0c24asdfaca6123421cf6434ae" while the "ParentPublicId" expects a readable record no. like "10045".

ConnectALL can automatically recognize the "ParentRecId" when it is configured to synchronize the Parent artifacts, without the need of the Record Id field mappings; as long as the destination application supports similar parent-child relationships.

Automatic User Value Mapping

ConnectALL supports Automatic user value mapping for Cherwell.  Below is a screenshot that illustrates this; where

id= Login ID

name=Full Name

email=E-mail

For more information on automatic user value mapping and to find out how it works, click here.