This documentation supports the 22.1 version of BMC Helix Digital Workplace Basic and BMC Helix Digital Workplace Advanced. Icons distinguish capabilities available only for the Advanced and External license levels. For more information, see License-types-and-features.

Helix ITSM connector

The Helix ITSM connector provides elements to the process designer palette that you can embed into fulfillment workflows. The elements enable you to perform, create and update actions through any BMC Helix ITSM form, as well as specific actions to create work orders and service requests, incident requests, and change requests.

Before you begin

Required license

DWP Advanced icon.png BMC Helix Digital Workplace Advanced

Related topics

Integrating-BMC-applications-with-BMC-Helix-Digital-Workplace-Catalog

Service-connector-overview

Service-connector-capabilities

Workflows-for-service-fulfillment

Connection options for the Helix ITSM connector

The following table describes the parameters required to create a connection:

Parameter

Description

Examples

Host

Name or IP address of the host Action Request System.

server-itsm-example.com

server-itsm-example

172.16.0.122

Port

Port number for service-level access.

0

2222

46262

User

Login name and password of a user with AR Administrator permission.

Allen

User password

Passw0rd&


Resource mapping capabilities

The Helix ITSM connector exposes the following resources that can be mapped to selection-type questions:

Resource

Description

Examples

Forms

Map selection-type questions to BMC Helix ITSM. Filter the returned data by using a custom query.

  • CTM:People
  • AP:Detail
  • CFG:Geography Country

Datasets

Map selection-type questions to existing SRD questions.

  • Priority
  • Type of Phone
  • Job Role

With manual data lookup questions, action triggers are not supported. For more information about selection-type questions, see Creating-selection-menus-for-question-responses.

Catalog import capabilities

The Helix ITSM connector provides the ability to import Service Request Definitions (SRDs) as services in BMC Helix Digital Workplace Catalog, and the ability to import service categories from BMC Service Request Management as categories in BMC Helix Digital Workplace Catalog. The Helix ITSM connector exposes the following items that can be imported in the Service Queue:

Importable item

Description

Service Request Definitions (SRD)

Import metadata for services, including fulfillment workflow, associated questionnaire forms, and action triggers.

Service categories

Import service categories or map BMC Service Request Management categories to existing categories in the catalog.

If you import SRDs into the BMC Helix Digital Workplace Catalog server, the services will be duplicated in the BMC Helix Digital Workplace end user console. When the end user searches a service, they will see one Catalog service and one SRD.

Important

End users can add comments with rich text formatting elements only to services created directly in BMC Helix Digital Workplace Catalog.

For more information, see Importing-service-catalog-items-from-external-systems.

Workflow actions available through the Helix ITSM connector

The following table provides an overview of all Helix ITSM connector actions:

Action category

Action

Description

Input parameters

Output parameters

Service request

Submit Service Request

Use these actions to submit a service request into a connected BMC Helix ITSM system.

The Submit Service Request With Identifiers action is similar to Submit Service Request, but includes additional output Identifier fields that can be referenced in the other actions in a workflow.

The Submit Service Request Converting Rich to Plain Text and Submit Service Request With Identifiers Converting Rich to Plain Text actions convert a rich text string into a plain text string. If the input contains inline image tags, they are converted into an attachment with an autogenerated filename in BMC Helix ITSM. For example, Replace <u>an office chair</u> attached <img src="office chair"> is converted into Replace an office chair attached (img_0.png)


Submit Service Request Converting Rich to Plain Text

Submit Service Request With Identifiers

Submit Service Request With Identifiers Converting Rich to Plain Text

Update Service Request

Entry

Create Entry

Use this action to create a record through any form in a Helix system.

When an entry is created, the system returns an Entry ID.

The returned object includes the Entry ID.

Get Entry

Use this action to retrieve a record by ID through any form in a BMC application.

The returned object includes a map with keys and values.

The specific fields that are returned depend on the specific record that is returned.

Get Entry By Query

Use this action to find a specific record that is submitted through a form, and to retrieve the specified record.

You can also use this action to retrieve some entry through a search query, so that the output result can be used in subsequent operations in a workflow.

To view the results of Get Entry by Query, use the subsequent Send In App Notification action. When a notification is sent to BMC Helix Digital Workplace Catalog, it includes JSON output with the fields IDs to retrieve.

The returned object includes field IDs and values specified in the Field IDs to retrieve.

Get Entries By Query

Use this action to find specific records submitted through a form, and to retrieve multiple records.

After you retrieve multiple data records, you can pass the data to other activities in a workflow by using a multi-instance loop. For more details about how to use a multi-instance loop to process multiple arrays of data, see Processing-data-sequentially-and-in-parallel.

The returned output includes a data array with multiple entries.

Set Entry

Use this action to update values for an existing record in any form in a connected Helix system.

The returned object includes a map with keys and values.

The specific fields that are returned depend on the specific record that is returned.

Delete Entry

Use this action to delete a record referenced by ID.

This action might be necessary when a catalog administrator needs to perform administrative tasks like cleaning up old or orphaned records or removing after archiving.

No output parameters

Change request


Create Change Request

Use these actions to create change requests with optional attachments or through a template.

The Create Change Request With Identifiers action is similar to Create Change Request. It has the same parameters, but includes additional output Identifier fields that might be used in other actions in a workflow.

Create Change Request With Identifiers

Get Change Request By ID

Use these actions to retrieve a change request by its IDs, and return an object that contains the details of a change request.

The Get Change Request By Identifiers action is similar to Get Change Request By ID. It has the same parameters, but includes additional input Identifier fields that might be used in other actions in a workflow.

The returned output object returns all available details of a change request.

Get Change Request By Identifiers

Create Attachments For Change Request


Work order

Create Work Order

Use these actions to create work orders by defining mandatory fields (summary, description), and optional custom fields, such as attachments. You can also create a work order by applying a template.

The Create Work Order With Identifiers action is similar to Create Work Order. It has the same parameters, but includes additional output Identifier fields that might be used in other actions in a workflow.

Create Work Order With Identifiers

Get Work Order By ID

Use these actions to retrieve a work order by its IDs, and return an object that contains the work order details.

The Get Work Order By Identifiers action is similar to Get Work Order By ID. It has the same parameters, but includes additional input Identifier fields that might be used in other actions in a workflow. 


The returned output object returns all available details of a work order.

Get Work Order By Identifiers

Create Attachment For Work Order


Incident

Create Incident

Use these actions to create incidents by defining mandatory fields, and optional custom fields, such as attachments. You can also create an incident by applying a template.

The Create Incident With Identifiers action is similar to Create Incident. It has the same parameters, but includes additional output Identifier fields that might be used in other actions in a workflow.

Create Incident With Identifiers

Get Incident By ID

Use these actions to retrieve incidents by IDs.

The Get Incident By Identifiers action is similar to Get Incident By ID. It has the same parameters, but includes additional input Identifier fields that might be used in other actions in a workflow.

The returned output object returns all available details of an incident.

Get Incident By Identifiers

Create Attachments For Incident


Digital Workplace Catalog

Build Input Set

Use this action to create custom parameters to send to an activity that can receive these parameters. A single Build Input Set activity provides fields to create 10 key=value pairs. If needed, you can chain multiple Build Input Set elements to create more than 10 key=value pairs.

Important: Ensure that you use the correct form names, field names, and field IDs as inputs to this activity. 

Helix ITSM connector workflow examples

The following webinar (40:14) provides some workflow examples, best practices, and troubleshooting tips: 


icon_play.pnghttps://www.youtube.com/embed/4lhqqa79YAw 


The examples that follow show how to create different workflows.

Example 1: Create a workflow for a service that sets up a new employee's workplace

The process workflow for this service might consist of the following stages: 

  1. The department manager submits a service request to set up a workplace for a new employee. 
  2. A work order is created for the Facilities group to assign an office to the new employee.
  3. Through the Get Entry By Query action, the system retrieves the Office Number value assigned to the employee.
  4. The retrieved office number value is used as an input for other work orders assigned to teams who can perform their tasks in parallel:
    • Telecommunications group—to set up a phone 
    • Networking group—to set up the network
    • IT support—to provide a laptop with the installed software
  5. A notification is sent to the service requester when the work is completed.
  6. The service request is closed.

WorkflowNewWorkplace.png

Example 2: Create a workflow for a service that contains multiple tickets assigned to different teams

A single service might include tasks for different teams, such as a purchase, installation, provisioning, software installation, and configuration. The workflow needs to determine when steps are complete and pass the relevant information from one stage to the next, so that each team in the workflow can fulfill their assignments. 

The following workflows shows how a similar service request can be completed in different ways:

  • By using the Receive Task action

ReceiveTask.png

  • By using the Get Entry by Query action

 Get Entry By Query_Updated.png

Example 3: Create a workflow example with the Work order action

A manager wants to create a work order for IT support to add an account for a new employee. The process workflow for this service might consist of the following stages: 

  1. The manager submits the Get employee ID service and specifies the employee name in the questionnaire. 
  2. In the questionnaire, the employee name value retrieves the employee ID.
  3. By using the Create Work Order action, the system creates a work order that includes employee name and employee ID.

After the external data (employee name) is retrieved, the work order is created for IT support.

WO.png

Example 4: Create a workflow example with the Change request action

The process workflow for this service might consist of the following stages: 

  1. The manager wants to update a service request date.
  2. A change request is created through the Create Change Request With Identifiers action.
  3. A ticket is created for IT support.

Change request.png

Example 5: Create a workflow example with the Incident

The process workflow might consist of the following stages: 

  1. The end user submits a service request to fix a broken laptop.
  2. An incident with the laptop characteristics is created through the Create Incident With Identifiers action.
  3. A ticket is created for IT support.

Incident request.png


Input and output parameters for actions

This section describes how you can use Helix ITSM connector actions in the workflows that you build.

Important

You do not need to use parameters in the process designer element that are not listed.

Input parameters for Submit Service Request and Submit Service Request With Identifiers actions

Both of these actions have the same input parameters described in the following table:

Required

Parameter name

Data type

Examples

Description

Required

Connection Id

String

Connection > HelixITSM

Default Connection ID for this connector.

Required

Srd Id

String

"SRD00001234"

SRD used to create the service request. The status must be Online.

Required

Requested By Login Id

String

Process context > Requested By Login Name

Login ID of the user who submitted the request.

Optional

Requested For Login Id

String

Process context > Requested For Login Name

Login ID of the user who requires the service.

If a login ID is not specified, the value for Requested By Login Id is used.

Optional

Description

String

Process input > Text variable

Details to be sent to the request handler.

Optional

Cart Id

String

Process context > Order ID

ID of the order's shopping cart.

Optional

Cart GUID

String

Process context > Order GUID

GUID of the order's shopping cart.

Optional

Cart Name

String

Process context > Order Description

Description of the order's shopping cart.

Optional 

Expected Date

Date

Process input > Date variable

User-submitted date for the service request to be completed.

If a date is not specified, the field is populated based on the SRD rules.

Optional 

Attachments

String

Process input > Text variable

String array of attachment ID values that is submitted by using a Text process input.

In the associated questionnaire, map the Text process input to an Attachment question.


Optional 

Answers

String

Process context > Questions And Answers

String representation of all questions and responses, including those assigned to process inputs and created questions.

Optional 

Correlation Id

String

General > Process Correlation ID

System-generated key that identifies the service request to the integration component. For more information, see Waiting-for-a-response.

Optional

Quantity

Integer

Process context > Requested Item Quantity

Order quantity requested by the self-service user.

Optional

One Time Cost

String

Process context > Service One Time Cost

Value of the one-time cost with the system currency appended, for example, 164.50 USD.

Optional

Monthly Cost

String

Process context > Service Monthly Cost

Value of the monthly cost with the system currency appended, for example, 12.25 USD.

Submit Service Request output parameters

Parameter name

Data type

Example

Description

Output

Object

REQ1797

Request ID—A system field that is added by default to all BMC Helix ITSM and can be used in follow-on workflow activities. The BMC Helix ITSM field ID for Request ID is 1.

Submit Service Request With Identifiers output parameters

Parameter name

Data type

Examples

Description

Output

Object

REQ1797;

SRGAA5V0GFHPPAOUA6BOOTE2HB;

000000000001789;

Request ID—A system field that is added by default to all  BMC Helix ITSM forms and can be used in follow-on workflow activities. The BMC Helix ITSM ID for Request ID is 1.

Instance ID—A field for storing a GUID. The  BMC Helix ITSM field ID for Instance ID is 179.

SysRequest—BMC Helix ITSM shows this ID to users as a service request number. The BMC Helix ITSM field ID for SysRequest is 1000000829.

Input parameters for Create Work Order and Create Work Order with Identifiers actions

Both of these actions have the same input parameters described in the following table:

Submitting custom fields

The Detail and Detail2 parameters take the output of one or more chained Build Input Set activities to assign labels and values for custom fields in the work order to be created. The custom fields are given an index number in the order that the field labels are specified. Populate up to 34 custom fields in a work order by specifying unique field labels the Build Input Set elements that populate either or both Detail or Detail2 fields.

Tip

The first 15 WO Type fields need to be appended to one input set and added to the detail input parameter, and the next 19 WO Type fields to another input set and added to the detail2 input parameter.


If a field label is declared twice in a process before creating the work order, then the process will update the value of the field that was created earlier.

Details and Details 2 field data types

The custom fields expect values in strict data types. The following table shows the data types expected for each of the 34 fields based on the field index order.

Important

Only the variable data types specified in the following list are supported with the Helix ITSM connector.


Create Work Order output parameters

Parameter name

Data type

Example

Description

Output

Object

REQ1797

Request ID—A system field that is added by default to all BMC Helix ITSM forms and can be used in follow-on workflow activities. The field ID for Request ID is 1.

Create Work Order with Identifiers output parameters

Parameter name

Data type

Examples

Description

Output

Object

000000000010792;

AGGAA5V0GFHPPAOUAGHYOTEC30T9X6;

WO10918;

Request ID—A system field that is added by default to all BMC Helix ITSM forms and can be used in follow-on workflow activities. The field ID for Request ID is 1. The Request ID in the output is from the WOI:WorkOrderInterface_Create form.

Instance ID—A field for storing a GUID. The BMC Helix ITSM field ID for Instance ID is 179. The Instance ID in the output is from the WOI:WorkOrder form.

Work Order ID — BMC Helix ITSM shows this ID to users as a work order number. The BMC Helix ITSM field ID for Work Order ID is 1000000182. The Work Order ID in the output is from the WOI:WorkOrder form.

Get Work Order By ID input parameters

Required

Parameter name

Data type

Example

Description

Required

Connection ID

String

Connection > HelixITSM

Default Connection ID for this connector.

Required

Work Order ID

String

"WO10918"

BMC Helix ITSM shows this ID to end users as a work order number.

The BMC Helix ITSM field ID for Work Order ID is 1000000182.

Get Work Order By Identifiers

Required

Parameter name

Data type

Example

Description

Required

Connection ID

String

Connection > HelixITSM

Default Connection ID for this connector.

At least one of the parameters is required

Work Order ID

String

"WO10918"

BMC Helix ITSM shows this ID to end users as a work order number.

The BMC Helix ITSM field ID for Work Order ID is 1000000182.

Request ID

String

"000000000010792"

A system field added by default to all BMC Helix ITSM forms. It might be useful in certain follow-on workflow activities. The BMC Helix ITSM field ID for Request ID is 1.

Instance ID

String

"AGGAA5V0GFHPPAOUAGHYOTEC30T9X6"

A field for storing a GUID.

The BMC Helix ITSM field ID for Instance ID is 179.

Input parameters for Create Incident and Create Incident With Identifiers actions

Both of these actions have the same input parameters described in the following table:

Required

Parameter name

Data type

Example

Description

Required

Connection Id

String

Connection > HelixITSM

Default Connection ID for this connector.

Required

Login

String

Process context > Requested For Login Name

Login ID of the user who requires the service.

Required

Service Type

String

Process input > Selection variable:

  • User Service Restoration
  • User Service Request
  • Infrastructure Restoration
  • Infrastructure Event

Specify the most appropriate value, or offer the user a selection.

Tip: In the questionnaire, you can build a list of values by using Map to Dataset to select a list that matches the parameter name.

Optional

Service Request ID


Process Variables > SB Context > Service Request > Service Request ID variable

ID of the service request from BMC Helix Digital Workplace Catalog. Service Request ID is not directly applied to a created incident. It is used to set the value of the SBServiceRequestID field in the SB:ServiceRequestStub form entry. This form entry associates the service request with the created incident.

If the SBServiceRequestID value is absent in the SB:ServiceRequestStub form entry, potential issues may arise, such as the status not being aligned and comments failing to pass from the incident to the service request. 

Best practice: If the Create Incident or Create Incident With Identifiers action is added as a part of the main process flow, your workflow automatically sets the value of the SBServiceRequestID field in the SB:ServiceRequestStub form entry.

If the Create Incident or Create Incident With Identifiers action is deeply nested in the workflow or is part of another process that is invoked by using a Call Activity, the workflow fails to automatically determine the Service Request ID and passes an empty value for the SBServiceRequestID field in the SB:ServiceRequestStub form entry. In this case, we recommend that you define the Service Request ID input parameter to ensure that the SBServiceRequestID value is defined. 

Optional 

Status

String

Process input > Selection variable:

  • New
  • Assigned
  • In Progress
  • Pending
  • Resolved
  • Closed
  • Cancelled

Default: Assigned

Specify the most appropriate value, or offer the user a selection.

Tip: In the questionnaire, you can build a list of values by using Map to Dataset to select a list that matches the parameter name.

Required

Impact

String

Process input > Selection variable:

  • 1-Extensive/Widespread
  • 2-Significant/Large
  • 3-Moderate/Limited
  • 4-Minor/Localized

Specify the most appropriate value, or offer the user a selection.

Tip: In the questionnaire, you can build a list of values by using Map to Dataset to select a list that matches the parameter name.

Required

Urgency

String

Process input > Selection variable:

  • 1-Critical
  • 2-High
  • 3-Medium
  • 4-Low

Specify the most appropriate value, or offer the user a selection.

Tip: In the questionnaire, you can build a list of values by using Map to Dataset to select a list that matches the parameter name.

Required

Reported Source

String

Process input > Selection variable:

  • Direct Input
  • Email
  • External Escalation
  • Fax
  • Systems Management
  • Phone
  • Voice Mail
  • Walk In
  • Web
  • Other
  • BMC Impact Manager Event

Specify the most appropriate value, or offer the user a selection.

Example: Most self-service requests should be reported as from Web or Direct Input.

Tip: In the questionnaire, you can build a list of values by using Map to Dataset to select a list that matches the parameter name.

Required

Summary

String

Process input > Text variable

Summary to be sent to the request handler.

Optional

Notes

String

Process input > Text variable

Notes field to be sent to the request handler.

Optional

Submitter

String

Process context > Requested By Login Name

Login ID of the user who submitted the request.

If a login ID is not specified, the value for Requested By Login Id is used instead.

Optional

Template Name

String

<Project template name>

Name of an incident template to use. For more details about how these templates are created in BMC Helix ITSM, see Configuring Incident Management templates.

Optional

Attachments

String

Process input > Text variable

String array of attachment ID values that is submitted by using a Text process input.

In the associated questionnaire, map the Text process input to an Attachment question.

Important: If you specify this field, you must also specify the Work Info Type field.

Optional

Work info notes

String

"Attachment for an incident entry"

When attachments are submitted, the default value is: Attachment for an incident entry.

Optional

Work info type

String

Process input > Selection variable:

Customer Inbound

  • Customer Communication
  • Customer Follow-up
  • Customer Status Update

Customer Outbound

  • Closure Follow Up
  • Detail Clarification
  • General Information
  • Resolution Communications
  • Satisfaction Survey
  • Status Update

General

  • Incident Task / Action
  • Problem Script
  • Working Log
  • Email System
  • Paging System
  • BMC Impact Manager Update
  • Chat

Vendor

  • Vendor Communication

Default: None

Specify the most appropriate value, or offer the user a selection.

Tip: In the questionnaire, you can build a list of values by using Map to Dataset to select a list that matches the parameter name.


Optional

Correlation Id

String

General > Process Correlation ID

System-generated key that identifies the service request to the integration component. For more information, see Waiting-for-a-response.

Optional

Product Name

String

Microsoft Word

A term used to reference a product. This depends on the options selected for Product Category Tier 1, 2, and 3.

For more information, seeConfiguring product catalog information.

Optional

Product Model Or Version

String

2007

Product models and versions are used to differentiate the various models or versions that are available for a given product.

For more information, seeConfiguring product catalog information.

Optional

Product Manufacturer

String

Microsoft

Name of the company that manufactures the product. Each product can have only one manufacturer, but each manufacturer can have multiple products.

For more information, seeConfiguring product catalog information.

Optional

Resolution Details

String

<List of steps>

Steps that resolved the incident.

For more information, seeConfiguring Incident Management templates.

Optional

Resolution Product Name

String

Microsoft Word

Name of the company that manufactures the product provided as part of the resolution.

Optional

Resolution Product Model Or Version

String

2010

The product model or version of the product provided as part of the resolution.

Optional

Resolution Product Manufacturer

String

Microsoft

The manufacturer of the product provided as part of the resolution.

Optional

Operational Category Tier1

String

Add

Operational categories are used to list the operational services that a typical help desk provides.

Tier 1 determines which tier 2 categories are available, and tier 2 determines which tier 3 categories are available.

For more information, seeConfiguring operational catalogs.

Optional

Operational Category Tier2

String

User

Optional

Operational Category Tier3

String

Account

Optional

Resolution Operational Category Tier1

String

Add

Resolution operational categories are used to list the resolution for incidents.

Tier 1 determines which tier 2 categories are available, and tier 2 determines which tier 3 categories are available.

For more information, seeConfiguring generic catalog information .

Optional

Resolution Operational Category Tier2

String

User

Optional

Resolution Operational Category Tier3

String

Account

Optional

Resolution Product Category Tier1

String

Software

Resolution categorizations are associated with existing operational and product categorization.

Tier 1 determines which tier 2 categories are available, and tier 2 determines which tier 3 categories are available.

For more information, seeConfiguring generic catalog information.




Optional

Resolution Product Category Tier2

String

Application

Optional

Resolution Product Category Tier3

String

Productivity

Optional

Other Fields

String

Key5 = "Urgency"

Value5 = "3-Medium"

Specify any other input mappings that are not available in the default input map list and BMC Service Request Management. This parameter consumes the inputs of the Build Input Set activity. You can create any number of custom parameters through Build Input Set and feed them into the Create Incident or Create Incident With Identifiers activities.

To add custom parameters though Other Fields:

  1. Add the Build Input Set activity to the canvas, and click it.
  2. Add Key-Value pairs (for example, Key1 = "Vendor Ticket Number", Value1 = "55501").
    Use double quotes to indicate strings.
  3. In the Create Incident or Create Incident With Identifiers activity, select Other Fields > Activities > Build Input Set > Output > Inputs.
    Bind the inputs that you have created in Build Input Set.

Important: Although Build Input Set has only ten Key-Value pairs, you can chain as many of them as you want (add Build Input Set 1 to the canvas, feed the output of Build Input Set into Input Set1 of Build Input Set 1 ; the output of Build Input Set 1 can be fed into Create Incident or Create Incident With Identifiers ).

Create Incident output parameters 

Parameter name

Data type

Examples

Description

Output

Object

REQ1797

Request ID—A system field that is added by default to all BMC Helix ITSM forms and can be used in follow-on workflow activities. The field ID for Request ID is 1.

Create Incident With Identifiers output parameters 

Parameter name

Data type

Examples

Description

Output

Object

000000000010792;

AGGAA5V0GFHPPAOUAGHYOTEC30T9X6;

WO10918;

Request ID—A system field that is added by default to all BMC Helix ITSM forms and can be used in follow-on workflow activities. The BMC Helix ITSM field ID for Request ID is 1.

Instance ID—A field for storing a GUID. The BMC Helix ITSM field ID for Instance ID is 179.

Incident Number—BMC Helix ITSM shows this ID to users as an incident number. The BMC Helix ITSM field ID for Incident Number is 1000000161.

Get Incident by ID input parameters

Required

Parameter name

Data type

Example

Description

Required

Connection Id

String

Connection > HelixITSM

Default Connection ID for this connector.

Required

Incident Number

String

"INC1221"

BMC Helix ITSM shows this ID to users as an incident number.

The BMC Helix ITSM field ID for Incident Number is 1000000161.

Get Incident by Identifiers input parameters

Required

Parameter name

Data type

Example

Description

Required

Connection Id

String

Connection > HelixITSM

Default Connection ID for this connector.

At least one of the parameters is required

Incident Number

String

"INC1221"

BMC Helix ITSM shows this ID to users as an incident number.

The BMC Helix ITSM field ID for Incident Number is 1000000161.

Request ID

 String

"000000000001097"

A system field that is added by default to all BMC Helix ITSM forms and can be used in follow-on workflow activities.
The BMC Helix ITSM field ID for Request ID is 1.


Instance ID

String

"AGGAA5V0GFHPPAOUAHB4OTEDGQTKB4"

A field for storing a GUID. The BMC Helix ITSM field ID for Instance ID is 179.


Input parameters for Create Change Request and Create Change Request With Identifiers actions

Both of these actions have the same input parameters described in the following table:

Required

Parameter name

Data type

Example

Description

Required

Connection Id

String

Connection > HelixITSM

Default Connection ID for this connector.

Required

Login


Process context > Requested For Login Name

Login ID of the user who requires the change.

Required

Company


Calbro Services

Company must exist in the Action Request System.

Optional

Service Request ID


Process Variables > SB Context > Service Request > Service Request ID variable

ID of the service request from BMC Helix Digital Workplace Catalog. Service Request ID is not directly applied to a created change request. It is used to set the value of the SBServiceRequestID field in the SB:ServiceRequestStub form entry. This form entry associates the service request with the created change request.

If the SBServiceRequestID value is absent in the SB:ServiceRequestStub form entry, potential issues may arise, such as the status not being aligned and comments failing to pass from the change request to the service request. 

Best practice: If the Create Change Request or Create Change Request with Identifiers action is added as a part of the main process flow, your workflow automatically sets the value of the SBServiceRequestID field in the SB:ServiceRequestStub form entry.

If the Create Change Request or Create Change Request with Identifiers action is deeply nested in the workflow or is part of another process that is invoked by using a Call Activity, the workflow fails to automatically determine the Service Request ID and passes an empty value for the SBServiceRequestID field in the SB:ServiceRequestStub form entry. In this case, we recommend that you define the Service Request ID input parameter to ensure that the SBServiceRequestID value is defined. 

Optional 

Status


Process input > Selection variable

  • Draft
  • Request For Authorization
  • Request For Change
  • Planning In Progress
  • Scheduled For Review
  • Scheduled For Approval
  • Scheduled
  • Implementation In Progress
  • Pending
  • Rejected
  • Completed
  • Closed
  • Cancelled

Default: Scheduled

Specify the most appropriate value, or offer the user a selection.

Tip: In the questionnaire, you can build a list of values by using Map to Dataset to select a list that matches the parameter name.

Optional 

Priority

String

Process input > Selection variable

  • Critical
  • High
  • Medium
  • Low

Default: Low

Specify the most appropriate value, or offer the user a selection.

Tip: In the questionnaire, you can build a list of values by using Map to Dataset to select a list that matches the parameter name.

Optional 

Desc


Process input > Text variable

Notes field to be sent to the change handler.

Required

Summary


Process input > Text variable

Summary to be sent to the change handler.

Optional 

Location Company

String

Calbro Services US

The Location Company must exist in the Action Request System. The Location Company is defined in the Company+ field in the Create Change Request form.

Optional 

Template Name


Project template name

Name of a template to use when creating the change request. For more details about how these templates are created in BMC Helix ITSM, seeCreating templates for Change Management.

Optional 

Attachments


Process input > Text variable

String array of attachment ID values that is submitted by using a Text process input.

In the associated questionnaire, map the Text process input to an Attachment question.

Important: If you specify this field, you must also specify the Work Info Type field.

Optional 

Work info notes


Attachment for a change request entry

When attachments are submitted, the default value is: Attachment for a change request entry.

Optional 

Work info type


Process input > Selection variable

Requirements

  • Business Justification
  • Requirements

Analysis

  • Change Assessment
  • Potential Problems
  • Risk Assessment
  • Service Impact Assessment

Build

  • Backout Plan
  • Business Design
  • Development
  • Install Plan
  • Technical Design
  • Test Plan

Execution

  • Backout Results - Details
  • Install Results - Details
  • Test Results - Details

Closure

  • Cancellation Information
  • Post implementation Review

Audit

  • Configuration Audit
  • SLM Compliance Audit
  • SLM Process Review

General

  • General Information
  • Rejection Information
  • Email System
  • Paging System
  • Chat

A known value from the list must be specified.

Optional 

Correlation Id

String

General > Process Correlation ID

System-generated key that identifies the service request to the integration component. For more information, see Waiting-for-a-response.

Optional

Product Name

String

Microsoft Word

A term used to reference a product. This depends on the options selected for Product Category Tier 1, 2, and 3.

For more information, seeConfiguring product catalog information.

Optional

Product Model Or Version

String

2007

Product models and versions are used to differentiate the various models or versions that are available for a given product. For more information, seeConfiguring product catalog information .


Optional

Product Manufacturer

String

Microsoft

Name of the company that manufactures the product. Each product can have only one manufacturer, but each manufacturer can have multiple products.

For more information, seeConfiguring product catalog information.

Optional

Product Category Tier1

String

Software

Product categories are used for categorization of products, and can be used for setting associations with different processes for different companies. It can represent hardware, software, or a service.

Tier 1 determines which tier 2 categories are available, and tier 2 determines which tier 3 categories are available.

For more information, seeConfiguring product catalog information .

Optional

Product Category Tier2

String

Application

Optional

Product Category Tier3

String

Productivity

Optional

Operational Category Tier1

String

Add

Operational categories are used to list the operational services that a typical help desk provides.

Tier 1 determines which tier 2 categories are available, and tier 2 determines which tier 3 categories are available.

For more information, see Configuring operational catalogs .

Optional

Operational Category Tier2

String

User

Optional

Operational Category Tier3

String

Account

Optional

Class

String

Normal

Used to specify the impact of the change request.

For more information, seeCreating templates for Change Management .

Optional

Timing Reason

String

Customer need

Used to specify the reason for the timing of the change request.

Optional

Change Reason

String

Upgrade

Used to specify the reason for the change request.

For more information, seeCreating templates for Change Management .

Optional

Urgency

String

Critical

Used to specify the level of urgency.

For more information, seeCreating templates for Change Management.

Optional

Risk Level

String

Level 3

Used to specify the level of risk.

For more information, seeCreating templates for Change Management .

Optional

Other fields

String

Key5 = "Vendor Ticket Number"

Value5 = "abc"

Specify any other input mappings that are not available in the default input map list and BMC Service Request Management. This parameter consumes the inputs of the Build Input Set activity. You can create any number of custom parameters through Build Input Set and feed them into the Create Change Request and Create Change Request With Identifiers activities.

To add custom parameters through Other Fields:

  1. Add the Build Input Set activity to the canvas, and click it.
  2. Add Key-Value pairs (for example, Key1 = "Description", Value1 = "Other field").
    Use double quotation marks to indicate strings.
  3. In the Create Change Request or Create Change Request With Identifiers activity, select Other Fields > Activities > Build Input Set > Output > Inputs.
    You have bound the inputs of Build Input Set with the Change Request activity.

Although Build Input Set has only ten Key-Value pairs, you can chain as many of them as you want. (Add Build Input Set 1 to the canvas, feed the output of Build Input Set into Input Set1 of Build Input Set 1 . The output of Build Input Set 1 can be fed into Create Change Request or Create Change Request With Identifiers .)

Create Change Request output parameters

Parameter name

Data type

Examples

Description

Output

Object

REQ1797

Request ID—A system field added by default to all BMC Helix ITSM forms that can be used in follow-on workflow activities. The BMC Helix ITSM field ID for Request ID is 1.

Create Change Request With Identifiers output parameters

Parameter name

Data type

Examples

Description

Output

Object

000000000010792;

AGGAA5V0GFHPPAOUAGHYOTEC30T9X6;

CR10918;

Request ID—A system field that is added by default to all BMC Helix ITSM forms and can be used in follow-on workflow activities. The BMC Helix ITSM field ID for Request ID is 1.

Instance ID—A field for storing a GUID. The BMC Helix ITSM field ID for Instance ID is 179.

Infrastructure Change ID—BMC Helix ITSM shows this ID to users as an change request number. The BMC Helix ITSM field ID for Infrastructure Change ID is 1000000182.

Get Change Request by Id input parameters

Required

Parameter name

Data type

Example

Description

Required

Connection Id

String

Connection > HelixITSM

Default Connection ID for this connector.

Required

Request Id

String

000000000000646

A system field that is added by default to all BMC Helix ITSM forms and can be used in follow-on workflow activities. The BMC Helix ITSM field ID for Request ID is 1.

Get Change Request by Identifiers input parameters

Required

Parameter name

Data type

Example

Description

Required

Connection Id

String

Connection > HelixITSM

Default Connection ID for this connector.

At least one of the parameters is required

Request Id

String

"000000000000646"

A system field that is added by default to all BMC Helix ITSM forms and can be used in follow-on workflow activities. The BMC Helix ITSM field ID for Request ID is 1.


Infrastructure Change ID 

String

"CR005678"

BMC Helix ITSM shows this ID to users as a change request number. The BMC Helix ITSM field ID for Infrastructure ID is 1000000182.

Instance ID

String

"AGGAA5V0GFHPPAOUAFP5OTEBUST9UE"

A field for storing a GUID. The BMC Helix ITSM field ID for Instance ID is 179.

Create Entry input parameters

Required

Parameter name

Data type

Example

Description

Required

Connection Id

String

Connection > HelixITSM

Default Connection ID for this connector.

Required

Form Name

String

"WOI:WorkOrderInterface"

Form name to use for creating a record.

Required

Field Values

Input Set

Build Input Set > Output > Inputs

Object that contains custom field labels and values to populate fields that the form requires. See Building-a-custom-input-map-in-a-workflow.

Optional

Correlation Id

String

General > Process Correlation ID

System-generated key that identifies the service request to the integration component. For more information, see Waiting-for-a-response.

Get Entry input parameters

Required

Parameter name

Data type

Example

Description

Required

Connection Id

String

Connection > HelixITSM

Default Connection ID for this connector.

Required

Form Name

String

"WOI:WorkOrderInterface"

BMC Helix ITSMform with data to retrieve.

Required

Request Id

String

"0001234"

ID of record with data to retrieve.

Get Entry by Query input parameters

Required

Parameter name

Data type

Example

Description

Required

Connection Id

String

Connection > Connection ID

Default Connection ID for this connector.

Required

Form Name

String

"SRD:ServiceRequestDefinition"

BMC Helix ITSM form with data to retrieve.

Required

Query

String

"'SRD_Title'LIKE ""%SRD%"""

Search query.
The example shows a search query that returns all entries that have "SRD" characters in the SRD title.

Important: This action type uses BMC Helix ITSM query syntax. For more information about this query syntax, see Operators, wildcards, keywords, and NULL values.

Optional 

Retrieve option

String

Process input > Selection variable:

  • FIRST
  • SINGLE

One of the following options:

  • FIRST (the default) returns only the first results from the list.
  • SINGLE validates the result list of entries, and displays an error if there is more than one entry.

Tip: Uppercase and lowercase characters are accepted.

Optional

Field IDs to retrieve

String

Activity > Build Input Set > Output > Inputs

"{""First Name"":1234567890,""Last Name"":1234567891}"

Specify a single or multiple fields by providing the field name and field ID in JSON format. 

If this field is blank, by default, all fields from the BMC Helix ITSM form are displayed. 

The output is displayed in JSON format. You can use it in the output map or in the next activity of your workflow.

Important: The Field IDs to retrieve field accepts integer values without quotes.

Get Entries by Query input parameters

Required

Parameter name

Data type

Example

Description

Required

Connection Id

String

Connection > Connection ID

Default Connection ID for this connector.

Required

Form Name

String

"SRD:ServiceRequestDefinition"

BMC Helix ITSM form with data to retrieve.

Optional

Query

String

"'SRD_Title'LIKE ""%SRD%"""

Search query.
The example shows a search query that returns all entries that have "SRD" characters in the SRD title.

Important: This action type uses BMC Helix ITSM query syntax. For more information about this query syntax, see Operators, wildcards, keywords, and NULL values.

Optional

Limit

Integer

"100"

Maximum number of fields to retrieve.

If not specified, 100 is the default value.

Optional

Field IDs to retrieve

String

Activity > Build Input Set > Output > Inputs

"{""First Name"":1234567890,""Last Name"":1234567891}"

Specify a single or multiple fields by providing the field name and field ID in JSON format. 

If this field is blank, by default, all fields from the BMC Helix ITSM form are displayed. 

The output is displayed in JSON format. You can use it in the output map or in the next activity of your workflow.

Important: The Field IDs to retrieve field accepts integer values without quotes.

Set Entry input parameters

Required

Parameter name

Data type

Example

Description

Required

Connection Id

String

Connection > Connection ID

Default Connection ID for this connector.

Required

Form Name

String

"WOI:WorkOrderInterface"

BMC Helix ITSM form to update.

Required

Request Id

String

"0001234"

ID of record to update.

Required

Field Values

Input Set

Build Input Set > Output > Inputs

Object that contains custom field labels and values to populate fields required by the form.

See Building-a-custom-input-map-in-a-workflow.

Delete Entry input parameters

Required

Parameter name

Data type

Example

Description

Required

Connection Id

String

Connection > Connection ID

Default Connection ID for this connector.

Required

Form Name

String

"WOI:WorkOrderInterface"

BMC Helix ITSM form to delete.

Required

Request Id

String

"0001234"

ID of record to update.