BMC Helix Multi-Cloud Broker connector for BMC Helix iPaaS, powered by Jitterbit

Use the BMC Helix iPaaS BMC Helix Multi-Cloud Broker connector to integrate BMC Helix ITSM with other third-party applications to broker ITSM records. A specific BMC Helix Multi-Cloud Broker connection and its activities are referred to as a BMC Helix Multi-Cloud Broker endpoint.  Use the connector to perform the following actions:

• Configure the connection to create an authenticated BMC Helix Multi-Cloud Broker connection by entering credentials.
• Configure associated BMC Helix Multi-Cloud Broker activities that interact with the connection to be used either as a source to provide data within an operation, or as a target to consume data within an operation. 
• Use the connector activities to perform the following actions: 
  • Create, retrieve, and update ITSM records
  • Retrieve attachments from the ITSM records

Supported API versions and prerequisites

The BMC Helix Multi-Cloud Broker connector requires the use of an agent version 10.1 or later. These agent versions automatically download the latest version of the connector when required.

Before you begin

Make sure you have the following items to generate access tokens and configure the connector:

• BMC Helix Single Sign-On URL that you received with your subscription
• Client ID and client secret for BMC Helix Single Sign-On that you received with your subscription
• BMC Helix iPaaS, powered by Jitterbit API URL.

  • Create an API and then use the API URL to generate tokens. To learn how to create an API, see Create a custom API.

  • Share the URL with BMC SaaS Operations so that they use the URL to set up the application in BMC Helix Single Sign-On.

To generate a refresh token and a bearer token

To configure the connector, you need the refresh and bearer tokens.

Generate the tokens by performing the following steps:

1. In Postman, open a new request.
2. On the Authorization tab, from the Type list, select OAuth 2.0.

3. In the Configure New Token section, complete the following fields:

   Field	Action
   Token Name	Enter a meaningful name for the token.
   Grant Type	Do not change the default value that is set as Authorization Code.
   Callback URL	Enter the URL of BMC Helix iPaaS, powered by Jitterbit API that you generated as a prerequisite step.
   Auth URL	Enter the BMC Helix Single Sign-On host URL that you received with your subscription in the following syntax: <Host URL>/rsso/oauth2/authorize For example; https://apexglobal.com/login/rsso/oauth2/authorize.
   Access Token URL	Enter the BMC Helix Single Sign-On host URL that you received with your subscription in the following syntax: <Host URL>/rsso/oauth2/token For example; https://apexglobal.com/login/rsso/oauth2/token.
   Client ID	Enter the client ID that you received with your subscription.
   Client Secret	Enter the client secret that you received with your subscription.
   Scope	Leave this field blank.
   State	Leave this field blank.
   Client Authentication	Do not change the default value that is set as Send as Basic Auth header.

4. Click Get New Access Token.
5. In the BMC Helix Single Sign-On login dialog box, enter the credentials that BMC has provided.
6. Authorize the URL.
   The tokens are generated and displayed in Postman.

To register an application

After you generate the client ID and secret keys, register the application with which you want to integrate BMC Helix ITSM. Register the application only if you want to use the 3-legged OAuth 2.0 authentication method.

To register an application, perform the following steps:

1. Log in to Integration Studio.
2. Click the Menu icon .
3. Select Management Console > Customizations > App Registrations.
4. On the App Registrations page, click Create new .

5. Complete the following fields:

   Section	Field	Action
   Create new app registration	Name	Enter a name for the application that you want to register.
   	Description	Enter a meaningful description for the application registration.
   	Connector	From the list, select BMC Helix Multi-Cloud Broker.
   	Client ID	Enter the client ID that you received with your subscription.
   	Client Secret	Enter the client secret key that you received with your subscription.
   	Scope	Enter online-refresh.
   Configuration	Authentication URL	Enter the BMC Helix Single Sign-On URL that you received with your subscription. <Host URL>/rsso/oauth2/authorize For example; https://apexglobal.com/login/rsso/oauth2/authorize. The authorization request is sent to this URL.
   	Access token URL	Enter the BMC Helix Single Sign-On URL that you received with your subscription. <Host URL>/rsso/oauth2/token For example; https://apexglobal.com/login/rsso/oauth2/token. The access token request is sent to this URL.
   	Refresh token URL	Enter the BMC Helix Single Sign-On URL that you received with your subscription. <Host URL>/rsso/oauth2/token For example; https://apexglobal.com/login/rsso/oauth2/token. The request for a new access token is sent to this URL.

6. Click Save .
7. On the App Registrations page, next to the application you configured, click Advanced options and perform the following steps:

   1. On the Authentication request tab, under Parameters, enter the following details:

      Field	Action
      Key	Enter response_type.
      Value	Enter code.
      Send in	Select Request URL.

   2. On the Token policy tab, enable the toggle keys and enter the expiration time for the tokens, as shown in the following image:
      

      Important

      The value you specify for token expiration should be the same as the value specified for token expiration in BMC Helix Single Sign-On.

      Learn more about setting the token expiration value in Configuring token timeout for OAuth clients in the BMC Helix Single Sign-On documentation.

To configure the BMC Helix Multi-Cloud Broker connection

1. From the design canvas, open the Connectivity tab of the design component palette.
2. Perform one of the following actions
   • To configure a new BMC Helix Multi-Cloud Broker connection, use the Show option to filter the connectors. Then, click the BMC Helix Multi-Cloud Broker connector block:
     
   • To configure an existing BMC Helix Multi-Cloud Broker connection, use the Show option to filter the endpoints. Then, click the BMC Helix Multi-Cloud Broker connector block:
     

3. On the connection page, in Connection Name, enter a name to identify the BMC Helix Multi-Cloud Broker connection.

   The name must be unique for each BMC Helix Multi-Cloud Broker connection and must not contain forward slashes (`/`) or colons (`:`). This name is also used to identify the BMC Helix Multi-Cloud Broker endpoint, which refers to both a specific connection and its activities.

4. In Authentication Mechanism, select Credential-Based Auth or OAuth.

   Tip

   Fields with a variable icon  support using global variables, project variables, and Jitterbit variables. Begin either by typing an open square bracket [ into the field or by clicking the variable icon to display a list of the existing variables to choose from.

5. Perform one of the following actions based on your selection in step 4:

   1. If you selected Credential- Based Auth, complete the following fields:

      Field Name	Action
      IS Host	Enter the BMC Helix Innovation Studio host URL.
      Use proxy per endpoint	If you are using a private agent, select this check box if you want the agent to use proxy settings. Important: Specify the following proxy settings: jitterbit-utils --set-http-proxy-host <hostname>[<port>] jitterbit-utils --set-http-proxy-exceptions <exceptions>
      Username	Enter the user name to log in to BMC Helix Multi-Cloud Broker.
      Password	Enter the password for the username to log in to BMC Helix Multi-Cloud Broker.
      Basic Authentication	By default, this check box is selected and basic authentication is used for the connector. Clear this check box if you do not want to use basic authentication and then complete the fields for the OAuth 2.0 authorization.
      RSSO Host	Enter the BMC Helix Single Sign-On host URL that you received with your subscription.
      CLIENT ID	Enter the client ID that you received with your subscription.
      CLIENT SECRET	Enter the client secret that you received with your subscription.
      REFRESH TOKEN	Enter the token value that you received in the task to generate a refresh token.
      BEARER TOKEN	Enter the token value that you received in the task to generate a bearer token. Important: Contact the BMC SaaS Operations team to extend the expiration time of the bearer token.
      EXPIRES IN (MILLISECONDS)	By default, the value of this field is set to 86400. Enter the expires_in value that you received after generating a refresh token. This is the time in milliseconds after which a session for the generated token expires.

   2. If you selected OAuth, complete the following fields:

      Field Name	Action
      Application	Select the application for which you want to configure the authentication. Important: The Application list is displayed only if you have registered multiple applications. Otherwise, you can click the Log in with Multi-Cloud Broker option so that the connector uses the single application that you have registered.
      IS Host	Enter the BMC Helix Innovation Studio host URL.
      Use proxy per endpoint	If you are using a private agent, select this check box if you want the agent to use proxy settings.
      Log in with Multi-Cloud Broker	Click this option to log in to BMC Helix Multi-Cloud Broker via BMC Helix Single Sign-On. If the login is successful, verify the connection by clicking the Test option.
      Receive Inactivity Notification	These fields are auto-populated based on the selections you made in step 7b while registering the application. Important: If you change the values of these fields, the same values are displayed in the fields in step 7b.
      Days for Inactivity Notification
      Receive Expiration Notification
      Days for Expiration Notification
      Test	Click this option to test the connection.

6. Click Save Changes.
   After configuring the BMC Helix Multi-Cloud Broker connection, configure one or more associated activities with that connection.
   For more information about creating an activity, see Creating a BMC Helix Multi-Cloud Broker Create activity.
7. (Optional) To reset the connector configuration, click Discard Changes and enter the values again.

8. (Optional) To remove the connector configuration, click Delete.

   Important

   If you click Delete while creating a new connection, an error is displayed. For more information, see Component Dependencies, Deletion, and Removal.

To create a BMC Helix Multi-Cloud Broker activity

1. From the design canvas, open the Connectivity tab  of the design component palette:

2. To display activities that are available to be used with BMC Helix Multi-Cloud Broker connection, use Show to filter on Endpoints, and then click the BMC Helix Multi-Cloud Broker connector block:
   
   
   The following activities are available. For more information about configuring these activities, see the specific activity sections.

   Activity name	Description
   Create	Places an object into a BMC Helix Multi-Cloud Broker endpoint and is intended to be used as a target in an operation.
   Get	Finds an object at a BMC Helix Multi-Cloud Broker endpoint and is intended to be used as a source in an operation.
   Get Attachments	Finds an object at a BMC Helix Multi-Cloud Broker endpoint and is intended to be used as a source in an operation.
   Update	Places an object into a BMC Helix Multi-Cloud Broker endpoint and is intended to be used as a target in an operation.

3. To create an activity that can be configured, drag the activity block from the palette to the operation.

For more information about the parts of an operation and adding activities to operations, see Operation Creation and Configuration . 

To configure a BMC Helix Multi-Cloud Broker Create activity

A BMC Helix Multi-Cloud Broker Create activity places an object into a BMC Helix Multi-Cloud Broker endpoint and is intended to be used as a target to consume data in an operation. After configuring a BMC Helix Multi-Cloud Broker connection, you can configure as many BMC Helix Multi-Cloud Broker activities as you like for each BMC Helix Multi-Cloud Broker connection. The Create activity supports only the following BMC Helix ITSM objects:

• Incident
• Change
• Problem
• Work Order
• Known Error
• Vendor data
• Worklog
• Flow transaction
• Service unavailability
• Service notification

The Create activity also supports any custom fields for the supported list of objects.

To configure a BMC Helix Multi-Cloud Broker Create activity, complete the following steps:

1. After you add the activity to an operation, double-click the activity block.

2. On the configuration screen, enter a name and specify the following activity settings:

   Field Name	Action
   Name	Enter a name to use to identify the BMC Helix Multi-Cloud Broker Create activity. The name must be unique for each BMC Helix Multi-Cloud Broker Create activity and must not contain forward slashes (`/`) or colons (`:`).
   Select an Object for the resource	This section displays the objects available in the BMC Helix Multi-Cloud Broker endpoint. When reopening an existing activity configuration, only the selected service code is displayed instead of reloading the entire service code list.
   Selected Object	After an object is selected, it is listed here. Within the table, click anywhere on a row to select an object. Only one object can be selected. The information available for each object is fetched from the BMC Helix Multi-Cloud Broker endpoint: Name: The object name from BMC Helix Multi-Cloud Broker. Description: A short description of the selected object. Important: If the table does not populate with available objects, the BMC Helix Multi-Cloud Broker connection may not be successful. Ensure you are connected by reopening the connection and retesting the credentials
   Search	Enter any part of the object name into the search box to filter the list of objects. The search is not case-sensitive. If the objects are already displayed within the table, the table results are filtered in real time with each keystroke. To reload the list of objects from the endpoint when searching, enter search criteria and then refresh, as described below.

   

3. Click Next.
4. Review the request and response data schemas displayed.
   The data schemas list the fields available for the BMC Helix Multi-Cloud Broker Create activity. If the operation uses a transformation, the data schemas are displayed again later during the transformation mapping process. In the transformation mapping process, map target fields by using source objects, scripts, variables, custom values, and more.
5. Click Finished.
   After the activity is created, menu actions for that activity are accessible from the project pane in either the Workflows or the Components tab, and from the design canvas. For more information, see Activity Actions Menu.

To complete the configuration of the operation, add and configure other activities, transformations, or scripts as steps in an operation. You can also configure an operation's settings, which include the ability to chain operations together that are in the same or different workflows.

BMC Helix Multi-Cloud Broker Create activity operation patterns

BMC Helix Multi-Cloud Broker Create activities can be used as a target with these operation patterns:

• Transformation Pattern
• Two-Transformation Pattern (as the first or second target)

Other patterns are not valid using BMC Helix Multi-Cloud Broker Create activities. See the validation patterns on the Operation Validity page.

A typical use case is to use a BMC Helix Multi-Cloud Broker Create activity in the Two-Transformation Pattern. In this example, the first transformation (BMC Helix Multi-Cloud Broker Create Request) creates a request structure that is passed to the BMC Helix Multi-Cloud Broker Create activity. The second transformation (BMC Helix Multi-Cloud Broker Create Response) receives the response structure, which is then written to a variable by a Variable Write activity (Write BMC Helix Multi-Cloud Broker  Create Response) and a message is then logged by the Write to Operation Log script:

When ready, deploy and run the operation and validate behavior by checking the Operation logs.

To configure a BMC Helix Multi-Cloud Broker Update activity

A BMC Helix Multi-Cloud Broker Update activity places an object into a BMC Helix Multi-Cloud Broker endpoint and is intended to be used as a target to consume data in an operation. After configuring a BMC Helix Multi-Cloud Broker connection, you can configure as many BMC Helix Multi-Cloud Broker activities as you like for each BMC Helix Multi-Cloud Broker connection.

The Update activity supports the following objects:

• Incident
• Change
• Problem
• Work Order
• Known Error
• Vendor data

The Update activity also supports any custom fields for the supported list of objects.

To configure a BMC Helix Multi-Cloud Broker Update activity, complete the following steps:

1. After you add the activity to an operation, double-click the activity block.

2. On the configuration screen, enter a name and specifcy the following activity settings:

   Field Name	Action
   Name	Enter a name to use to identify the BMC Helix Multi-Cloud Broker Get activity. The name must be unique for each BMC Helix Multi-Cloud Broker Get activity and must not contain forward slashes (`/`) or colons (`:`).
   Ticket GUID	Enter the record instance ID for which you want to get the details.
   Select an Object for the resource	This section displays the objects available in the BMC Helix Multi-Cloud Broker endpoint. When reopening an existing activity configuration, only the selected service code is displayed instead of reloading the entire service code list.
   Selected Object	After an object is selected, it is listed here. Within the table, click anywhere on a row to select an object. Only one object can be selected. The information available for each object is fetched from the BMC Helix Multi-Cloud Broker endpoint: Name: The object name from BMC Helix Multi-Cloud Broker. Description: A short description of the selected object. Important: If the table does not populate with available objects, the BMC Helix Multi-Cloud Broker connection may not be successful. Ensure you are connected by reopening the connection and retesting the credentials

   

3. Click Next. 
4. Review the request and response schema. 
   The data schemas list the fields available for the BMC Helix Multi-Cloud Broker Update activity. If the operation uses a transformation, the data schemas are displayed again later during the transformation mapping process. In the transformation mapping process, map target fields by using source objects, scripts, variables, custom values, and more. 
5. Click Finished.
   After the activity is created, menu actions for that activity are accessible from the project pane in either the Workflows or the Components tab, and from the design canvas. For more information, see Activity Actions Menu.

To complete the configuration of the operation, add and configure other activities, transformations, or scripts as operation steps. You can also configure an operation's settings, which include the ability to chain operations together that are in the same or different workflows.

BMC Helix Multi-Cloud Broker Update activity operation patterns

BMC Helix Multi-Cloud Broker Update activity can be used as a target with these operation patterns:

• Transformation Pattern
• Two-Transformation Pattern (as the first or second target)

Other patterns are not valid using BMC Helix Multi-Cloud Broker Update activities. See the validation patterns on the Operation Validity page. 

A typical use case is to use a BMC Helix Multi-Cloud Broker Update activity in the Two-Transformation Pattern. In this example, the first transformation (BMC Helix Multi-Cloud Broker Update Request) creates a request structure that is passed to the BMC Helix Multi-Cloud Broker Update activity. The second transformation (BMC Helix Multi-Cloud Broker Update Response) receives the response structure, which is then written to a variable by a Variable Write activity (Write BMC Helix Multi-Cloud Broker  Update Response) and a message is then logged by the Write to Operation Log script:

To use the activity with scripting functions, write the data to a temporary location and then use that temporary location in the scripting function.

When ready, deploy and run the operation and validate behavior by checking the Operation Logs.

To configure the BMC Helix Multi-Cloud Broker Get activity

A BMC Helix Multi-Cloud Broker Get activity finds an object at a BMC Helix Multi-Cloud Broker endpoint and is intended to be used as a source to provide data to an operation. After configuring a BMC Helix Multi-Cloud Broker connection, you can configure as many BMC Helix Multi-Cloud Broker activities as you like for each BMC Helix Multi-Cloud Broker connection.

The Get activity supports any object from the Ticket Brokering library in BMC Helix Multi-Cloud Broker.

To configure the BMC Helix Multi-Cloud Broker Get activity, complete the following steps:

1. After you add the activity to an operation, double-click the activity block.

2. On the configuration screen, enter a name and specifcy the following activity settings:

   Field Name	Action
   Name	Enter a name to use to identify the BMC Helix Multi-Cloud Broker Get activity. The name must be unique for each BMC Helix Multi-Cloud Broker Get activity and must not contain forward slashes (`/`) or colons (`:`).
   Ticket GUID	Enter the record instance ID for which you want to get the details.
   Select an Object for the resource	This section displays the objects available in the BMC Helix Multi-Cloud Broker endpoint. When reopening an existing activity configuration, only the selected service code is displayed instead of reloading the entire service code list.
   Selected Object	After an object is selected, it is listed here. Within the table, click anywhere on a row to select an object. Only one object can be selected. The information available for each object is fetched from the BMC Helix Multi-Cloud Broker endpoint: Name: The object name from BMC Helix Multi-Cloud Broker. Description: A short description of the selected object. Important: If the table does not populate with available objects, the BMC Helix Multi-Cloud Broker connection may not be successful. Ensure you are connected by reopening the connection and retesting the credentials

   

3. Click Next.
4. Review the request and response schema.
5. The data schemas list the fields available for the BMC Helix Multi-Cloud Broker Get activity. If the operation uses a transformation, the data schemas are displayed again later during the transformation mapping process. In the transformation mapping process, map target fields by using source objects, scripts, variables, custom values, and more.
6. Click Finished.
   After the activity is created, menu actions for that activity are accessible from the project pane in either the Workflows or the Components tab, and from the design canvas. For more information, see Activity Actions Menu.

To complete the configuration of the operation, add and configure other activities, transformations, or scripts as operation steps. You can also configure an operation's settings, which include the ability to chain operations together that are in the same or different workflows.

BMC Helix Multi-Cloud Broker Get activity operation patterns

BMC Helix Multi-Cloud Broker Get activity can be used as a source with these operation patterns:

• Transformation Pattern
• Two-Target Archive Pattern (as the first source only)
• Two-Transformation Pattern (as the first or second source)

Other patterns are not valid using BMC Helix Multi-Cloud Broker Get activities. For more information about the validation patterns, see the Operation Validity
page.

A typical use case is to use a BMC Helix Multi-Cloud Broker Get activity in the Two-Transformation Pattern. In this example, the first transformation (BMC Helix Multi-Cloud Broker Get Request) creates a request structure that is passed to the BMC Helix Multi-Cloud Broker Get activity. The second transformation (BMC Helix Multi-Cloud Broker Get Response) receives the response structure, which is then written to a variable by a Variable Write activity (Write BMC Helix Multi-Cloud Broker Get  Response) and a message is then logged by the Write to Operation Log script:

When ready, deploy and run the operation and validate behavior by checking the Operation Logs.

To configure the BMC Helix Multi-Cloud Broker Get Attachments activity

A BMC Helix Multi-Cloud Broker Get Attachments activity finds an attachment at a BMC Helix Multi-Cloud Broker endpoint and is intended to be used as a source to provide data to an operation. BMC Helix Multi-Cloud Broker extracts all the related attachments to the attachment group, by the attachment group ID. After configuring a BMC Helix Multi-Cloud Broker connection, you can configure as many BMC Helix Multi-Cloud Broker activities as you like for each BMC Helix Multi-Cloud Broker connection.

To configure a BMC Helix Multi-Cloud Broker Get Attachments activity, complete the following steps:

1. After you add the activity to an operation, double-click the activity block.

2. On the configuration screen, enter a name and specifcy the following activity settings:

   Field Name	Action
   Name	Enter a name to identify the BMC Helix Multi-Cloud Broker Get Attachments activity. The name must be unique for each BMC Helix Multi-Cloud Broker Get Attachments activity and must not contain forward slashes (`/`) or colons (`:`).
   Attachment Group ID	When a work note with an attachment is created in a ticket, an entry in the worklog record definition in BMC Helix Multi-Cloud Broker is also created. The entry in the worklog record contains an ID for the attachments.

   

3. Click Next.
4. Review the request and response schema.
   The data schemas list the fields available for the BMC Helix Multi-Cloud Broker Get Attachments activity. If the operation uses a transformation, the data schemas are displayed again later during the transformation mapping process. In the transformation mapping process, map target fields by using source objects, scripts, variables, custom values, and more.
5. Click Finished.
   After the activity is created, menu actions for that activity are accessible from the project pane in either the Workflows or the Components tab, and from the design canvas. For more information, see Activity Actions Menu.

To complete the configuration of the operation, add and configure other activities, transformations, or scripts as operation steps. You can also configure an operation's settings, which include the ability to chain operations together that are in the same or different workflows.

BMC Helix Multi-Cloud Broker Get Attachments activity operation patterns

BMC Helix Multi-Cloud Broker Get Attachments activity can be used as a source with these operation patterns:

• Transformation Pattern
• Two-Target Archive Pattern (as the first source only)
• Two-Transformation Pattern (as the first or second source)

Other patterns are not valid using BMC Helix Multi-Cloud Broker Get Attachments activities. See the validation patterns on the Operation Validity page.

A typical use case is to use a BMC Helix Multi-Cloud Broker Get Attachments activity in the Two-Transformation Pattern. In this example, the first transformation (BMC Helix Multi-Cloud Broker  Get Attachments Request) creates a request structure that is passed to the BMC Helix Multi-Cloud Broker Get Attachments activity. The second transformation (BMC Helix Multi-Cloud Broker Get Attachments Response) receives the response structure, which is then written to a variable by a Variable Write activity (Write BMC Helix Multi-Cloud Broker Get Attachments Response) and a message is then logged by the Write to Operation Log script:

When ready, deploy and run the operation and validate behavior by checking the operation logs.