Synchronize CSP work order requests with CSGI field service requests

CSG Field Service Management is a cloud-service platform for managing field service operations. It works with billing and order management systems, and provides a set of APIs for managing data flow between CSG Field Management and the integrated applications, ensuring that data between the applications is synchronized and updated. 

BMC Helix iPaaS, powered by Jitterbit provides a pre-built integration template that enables you to create field service requests in CSG Field Service Management from BMC Helix for CSP work orders. To use the integration template with the values defined out of the box, you update the project variables with details of your systems and deploy the integration template. 

The template provides the following capabilities: 

Use case

BMC Helix for CSP

CSG

Create field service request

Creates a CSG field service request from a new BMC Helix for CSP work order, including the location, if specified in the work order.

Important:

  • Work orders are child entities for trouble tickets, so you must create a trouble ticket to be able to attach a work order. 
  • When you create a work order, make sure that you select a resource or service that has a site associated to it. You can select a resource or a service by selecting Add existing resource while creating the work order. 
  • If the location of the work order is changed after the CSG field service request is created, the corresponding CSG field service request is cancelled, and a new request is created with the updated location.

NA

Update field service request

Updates a CSG field service request from an updated BMC Helix for CSP work order

NA

Synchronize activity notes and other details

Synchronizes an activity note from the BMC Helix for CSP work order with the corresponding CSG field service request

Synchronizes the following details from the CSG field service request to the BMC Helix for CSP work order:

  • Job comment to activity note
  • Status, priority, description and title
  • DispatchStatus
  • ETADateTime, JobStartDateTime

Synchronize status

Synchronizes the Pending and Cancel status of the BMC Helix for CSP work order with the corresponding CSG field service request

Synchronizes the status of the CSG field service request with the corresponding BMC Helix for CSP work order

BMC Helix for CSP to CSG data flows

The following image gives an overview of the data flow for creating a CSG field service request from a BMC Helix for CSP work order:

221_CSP_CSG_createRequest.png

CSG to BMC Helix for CSP data flows

The following image gives an overview of the data flow for updating a BMC Helix for CSP work order from a CSG field service request:

221_CSG_CSP_updateRequest.png

Before you begin

You require the following items to successfully set up and use this integration: 

Required versions

  • BMC Helix for CSP version 21.03 and later
  • CSG Field Service Management version 

Authentication and permissions

  • A valid CSG Field Service Management license and the associated token.
  • A valid BMC Helix for CSP instance

Jitterbit Harmony subscription

A valid BMC Helix iPaaS subscription

Task 1: To download and import the integration template project file

  1. Download the Sync CSP Work Order and CSGI WFX Work Order project file to your system.
    This file contains the BMC Helix iPaaS Integration Studio project Sync CSP Work Order and CSGI WFX Work Order.

    Important

    Your ability to access product pages on the EPD website is determined by the license your company purchased.

  2. As a developer, log in to BMC Helix iPaaS and navigate to the Integration Studio.
  3. On the projects page, click Import.
  4. Click Browse and then select the Sync CSP Work Order and CSGI WFX Work Order file you downloaded.
    The Project Name and Organization fields are automatically populated depending on the values defined. 
  5. From the Environment list, select the environment to which you want to import this integration template, and then click Import.
    The project opens after the integration template is imported. 
  6. To open the project file at a later time, select the environment where the integration templates are available, and then select the Sync CSP Work Order and CSGI WFX Work Order project.

Task 2: To update the project variables for the integration template

  1.  Next to the Environment name, click the ellipsis ... and select Project Variables.
  2. Update the following project variables:  

    • Access points and authentication details for CSG, BMC Helix ITSM, and BMC Helix iPaaS applications

      Project variables

      Action

      BMC Helix for CSP

      CSP_Host

      Enter the URL of the BMC Helix for CSP instance.

      CSP_User_Name

      Enter the User ID to access BMC Helix for CSP.

      CSP_User_Password

      Enter the password of the user to access BMC Helix for CSP.

      CSG

      CSG_Host

      Enter the URL of the CSG Field Service Management instance.

      CSG_Token

      Enter token provided for your CSG Field Service Management instance.

      For details about obtaining the token, see the Application registration section in the Before you beginsection.

      BMC Helix iPaaS

      BHIP_Host

      Enter the URL to access BMC Helix iPaaS.

      BHIP_User_Name

      Enter the user ID to access BMC Helix iPaaS.

      BHIP_User_Password

      Enter the password of the user to access BMC Helix iPaaS.

    • Webhook API variables

      Project variables

      Value

      BHIP_API_Name

      Enter a name for the Webhook API that is created in BMC Helix iPaaSto handle requests from BMC Helix for CSP and CSG Field Service Management.

      This API receives the BMC Helix for CSP Webhook requests.

      BHIP_CSP_API_Profile_User_Name

      For security profile type BASIC, enter the password for the CSP security profile created. 
      The Jitterbit API and the Webhook API use this password for authentication while accessing CSP.

      BHIP_CSP_API_Profile_User_Password

      For security profile type BASIC, enter the password for the BMC Helix for CSP security profile created. 
      The Jitterbit API and the Webhook API use this password for authentication while accessing BMC Helix for CSP.

      BHIP_Vendor_API_Profile_ApiKey_Name

      For the vendor API profile type APIKEY, enter a name for the APIKEY.

      BHIP_Vendor_API_Profile_Type

      Enter a security profile type.

      You can set the following values for this variable:

      • BASIC
      • APIKEY
      • ANONYMOUS

      The default value is BASIC.

      Security Profile Type defines the authentication type to be used by the Webhook API while accessing CSG. This value is added in the BMC Helix iPaaS Jitterbit API.

      Important:

      • For profile types supported by the CSG application, the security profiles are automatically created by the integration template when you enable the integration. 
      • BMC Helix iPaaS does not support OAuth authentication for this application.

      BHIP_Vendor_API_Profile_User_Name

      For security profile type BASIC, enter the user name to be used to create the security profile.
      The Jitterbit API and the Webhook API use this user name for authentication while accessing CSG.

      BHIP_Vendor_API_Profile_User_Password

      For security profile type BASIC, enter the password for the security profile created. 
      The Jitterbit API and the Webhook API use this password for authentication while accessing CSG.

      BHIP_API_User_Roles

      Enter comma-separated values of the user roles assigned for the BMC Helix iPaaS API.

      Only a user with these roles can access the APIs. Leave this value blank to restrict access only to administrators.

    • Email notification configurations

      Project variable

      Value

      Jitterbit_To_Email_Address

      Enter the email address to which you want to send the notification emails.

      Jitterbit_From_Email_Address

      Enter the email address from which the notification emails must be sent.

      BHIP_Email_Enabled

      To disable email notifications, change the default value to false.

      By default, the value is set to true. 

(Optional) Task 3: To review and update out-of-the-box field mappings

The integration templates provide default field mappings between the two applications.

To modify the field mappings between the two applications, update the Update Request transformation element of the Update CSP WO Data operation in the CSG Workflow workflow.

For additional information about the workflow, see Workflows included in the integration template.

BMC Helix for CSP to CSG Field Service Management field mappings

The following out-of-the-box fields are mapped in the Update Request for the Update CSP WO Data operation.

BMC Helix for CSP fields

CSG Field Service Management fields

ID

WOnum

WO Display ID

WO Display ID

Priority

Job.SkillPriorityOverride

Description + Title

Job.WFXComment

Status

Job.Status

Dispatch Status

Job.DispatcherStatusCd

Dependent On

Job.OrderNum

Scheduled Start Time

Job.TimeSlotStartDateTime

Scheduled End Time

Job.TimeSlotEndDateTime

Agreed Start Date

Job.ETADateTime

Actual Start Date

Job.JobStartDateTime

Site

JobCustomer.LastName

Address

JobLocation.Address.AddrLine1

Country

JobLocation.CountryCd

State

JobLocation.Address.State

City

JobLocation.Address.City

Zip Postal Code

JobLocation.Address.ZipCode

Latitude

JobLocation.Latitude

Longitude

JobLocation.Longitude

Height

JobLocation.LocationCustomFields.LocationCustom1

Location Notes

JobLocation.HouseComment

Notes (Related Records)

Job.JobComment

To update out-of-the-box CSP to CSG field mappings

  1. Open the Sync CSP Work Order and CSGI WFX Work Order project.
  2. In the CSG Workflow, scroll to the Update CSP WO data operation.
  3. Click the Update Request transformation element, and then click View/Edit.
  4. In the Target pane, from the View menu, select Mapped.
  5. From the Variables tab in the Source pane, drag a variable to a field mapping you want to update in the Mappings section.
  6. Click Return to workflow return_to_workflow.png.

Important

If the integration template is already deployed, you must deploy it again after you make changes to the mappings.

Instructions for deploying the integration template are provided in Task 4: To deploy and enable the project.

Task 4: To deploy and enable the project

After you enable the integration, when a work order is created in BMC Helix for CSP, a corresponding field service request is created in CSG Field Service Management. Any updates made to the status of the work order are synced with the CSG field service request.

Changes made to the following fields in the CSG field service request are updated in the BMC Helix for CSP work order:

  • Job comment to activity note
  • Status, priority, description and title
  • DispatchStatus
  • TimeSlotStartDateTime, TimeSlotEndDateTime, ETADateTime, JobStartDateTime

(Optional) Task 5: To set the time for API debug mode

By default, the debug mode is set to 2 hours after you run the integration. Debug logs are updated for the time set for the debug mode. To increase the debug mode for a longer period of time, perform the following steps:

  1. In BMC Helix iPaaS, select API Manager > My APIs.
  2. Open the required API.
  3. Select Enable Debug Mode Until: and set it for the required date and time.
  4. Save and publish the API.

Workflows included in the integration template

The following workflows are defined as a part of the integration template. Refer to the following details for an overview of the tasks defined in the workflow operations and configurations defined within each workflow.

Enable Integration

Set up the required details for the integration.

BHIP Operations

This workflow defines the operations required to enable the integration after all the required project configurations are completed. The following operations are included in this workflow:

Operation name

Actions performed

3.1 BHIP Login

Logs in to BMC Helix iPaaS by using the credentials provided in the project variables.

3.2 BHIP Get API details

Verifies if any custom APIs or security profiles exist for the CSG integration.

3.3 BHIP Delete API

Deletes existing APIs, if required.

3.4 BHIP Delete API Profile

Deletes existing security profiles, if required.

3.5 BHIP Create API Profile

Creates the security profiles and REST APIs in BMC Helix iPaaS.

3.6 BHIP Get Operation ID

Retrieves the 

3.7 BHIP Get User Roles

Gets the details of the user roles that have access to this template.

3.8 BHIP Create API

Creates the APIs in BMC Helix iPaaS.

3.9 BHIP Publish API

Publishes the custom APIs to BMC Helix iPaaS and CSG.

3.10 BHIP Rest API Variables

Resets all API variable values in BMC Helix iPaaS.

CSP Webhook

This workflow creates the Webhook API required for BMC Helix for CSP. The following operations are included in this workflow:

Operation name

Actions performed

4.1 CSP Webhook Wrapper

Creates the details for the Webhook APIs for the integration. 

4.2 Create Webhook Driver

Creates all the required Webhook APIs for the integration.

4.2 CSP Login

Logs in to BMC Helix for CSP by using the credentials provided in the project variables.

4.3 CSP Get Webhook Details

Retrieves Webhook API configurations that exist in BMC Helix for CSP for the integration.

4.4 CSP Delete Webhook

If the Webhook API configuration exists, deletes this configuration.

4.5 Register Webhook 

Updates the Webhook API configuration.

4.6 CSP Toggle Webhook Status

Enables the Webhook API configuration.

CSG Workflow

This workflow defines the data flow between BMC Helix for CSP and CSG Field Service Management.

Operation name

Actions performed

5.0 CSG Flow Controller

Enables all the API entry points by using the details provided in the project variables for CSG Field Service Management.

5.1 CSG FSM Driver

Enables the required field service management drivers for the integration.

5.2 Update CSP WO Data

Gets details of the CSG work order to create the corresponding work order in BMC Helix for CSP.

5.3 Post comment in CSP WO

Gets details of the comment data from the CSG work order to add to the corresponding CSG work order.

CSP Workflow

This workflow creates the CSG work order when a BMC Helix for CSP work order is created or updated. The following operations are included in this workflow:

Operation name

Actions performed

6.0 CSP Flow Controller

Enables all the API entry points by using the details provided in the project variables for BMC Helix for CSP.

6.1 CSP Driver

Enables the required CSP drivers for the integration.

6.2 Get CSP WO details

For a new BMC Helix for CSP work order, maps the required CSP fields to the CSG work order fields to create a new work order in CSG.

6.3 Query CSP WO Resource Location 

Get the resource location of the CSP work order.

6.4 CSG WFX WO Operation

Creates a Work Flow Express operations for the work order.

6.5 Update CSP ExternalSystem Request 

Updates the CSG work order. The following operations are performed:

  • When a BMC Helix for CSP work order is updated, queries CSG for a corresponding work order request
  • Maps the BMC Helix for CSP fields to the CSG fields
  • Updates the existing CSG work order with the updated values

6.6 Get WO Location Details

Fetches the location details of the CSP work order to update to the CSP work order. 

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*