Configuring web requests in a business process

You can connect your application with the REST API web services of another application in a codeless way. After creating the RESTful web service request definitions and configuring the authentication credentials for the REST API service, developers can manage the data that comes from a web request or is sent to a web request. You must configure the Web Request element in the BMC Helix Innovation Studio Process designer to invoke web API requests as required by the application's business logic. You can also send or receive attachments from other applications by configuring the Web Request element. 

For example, if you want to connect to a JIRA RESTful service to get details of a JIRA issue in your application, you must configure the Web Request element to use the required values from the body of the JIRA REST API.

Before you begin

• If you want to use the PUT or POST methods, ensure that you have configured the Create Document element in the Process designer. The Create Document element enables you to use the object metadata from the appropriate document definition as input to the web request. 
  For more information, see Creating a document instance
• Ensure that you have created the RESTful web service request definition. 
  For more information, see Creating a REST API web service request definition
• Ensure that you have configured the authentication credentials of the RESTful web service. 
  For more information, see Configuring the authentication credentials of REST API web services

To configure the Web Request element in a process

1. Log in to BMC Helix Innovation Studio. 
2. From the Workspace tab, navigate to the application that you want to connect to a REST API web service. 
3. Perform one of the following tasks:
   
   • If you want to add the Web Request element to a new process, select Processes > New. 
   • If you want to add the Web Request element to an existing process, click the Processes tab and click the name of process.

4. From the Palette, on the canvas, drag the Web Request element to the canvas at that point in the process where you want to invoke the web API request. 

   Note

   If you are using the PUT or POST method, typically, you place the Web Request element after the Create Document element.

5. In the Element properties  tab, in the Label field, type a meaningful name for the web request, such as Create Issue.

6. In the INPUT MAP section, from the Connection list, select the connection that you want to use for this web request, such as JIRA.

7. From the Web API list, select the REStful web service request definition that you created earlier, such as JIRA APIs.

8. From the Request list, select the web request that you created in this web service request definition, such as Create Issue.
9. (Only for PUT or POST methods) In Document, click Click to build an expression, and from the Web Request node, select the request body. 

10. (Optional) In Query Parameters, click Click to build an expression, and from the Web Request node, select any of the following web API metadata:

    • Reason—Describes the reason behind the status of the web API, for example, the reason for the web API failure.

    • Status code—A number indicating the status of the web API.
      For example, if the status code is 200, it indicates that the web API call is successful.

    • Status family—A range of status codes that indicates the web API status.
      For example, a status code from 200-299 indicates a successful web API call. Whereas, a status code from 300-399 indicates that the web API call is redirected.

    • Header—A web API response header, for example, date, time, cache, and so on.
      

    Note

    The web API response metadata fields are displayed only when you clear the Error on Unsuccessful Response check box while creating the web API service request definition.

    Example of using the web API response metadata in a process

    Consider a scenario, where you are connecting your application with JIRA and you configure a web API request definition that searches for a JIRA ticket. When the web API is run, the Error 404: Not found error occurs, which indicates that the required JIRA ticket is not found, and the process is terminated.

    To ensure that the process is run despite the error, you specify the following key details:

    • While creating the web API service request definition, you clear the Error on Unsuccessful Response check box.

    • While configuring the process, in Query Parameters, you specify the Status code = 404 condition and add the Create Record element to create the required JIRA ticket.

11. Click Save. 

After you save the process, an alias is created for the web service request. An alias is a placeholder for a tenant-specific configuration and is required to map with the appropriate Web API connection. 

To create an attachment from binary content

If your web API response is JSON with an embedded attachment (Base64 encoded bytes), then you must use the Create Attachment element to convert the attachment into a string.

1. Log in to BMC Helix Innovation Studio and navigate to the Workspace tab.

2. Select the required application.

3. Perform one of the following tasks:

   • If you want to add the Create Attachment element to a new process, select Processes > New. 

   • If you want to add the Create Attachment element to an existing process, click the Processes tab and click the name of the process.

4. From the palette, drag the Create Attachment element on the canvas, and specify the fields as described in the following table:

   Field	Action
   Contents	Enter the contents for the attachment. You get the contents from the JSON response or any binary data from a Base64 encoded file.
   Attachment Name	Enter the file name of the attachment that is displayed in the JSON response or any binary data from a Base64 encoded file.
   Decode Contents	Enter true or false based on whether you want to perform a Base64 decode action on the contents of an attachment. Specify true only when you get binary data from a Base64 encoded file, and you want to convert and store that data as an attachment in BMC Helix Innovation Studio.

5. Click Save.

To send an attachment as binary content

By using the Encode Attachment element, you can send an attachment as a binary data.

1. Log in to BMC Helix Innovation Studio and navigate to the Workspace tab.

2. Select the required application.

3. Perform one of the following tasks:

   • If you want to add the Encode Attachment element to a new process, select Processes > New. 

   • If you want to add the Encode Attachment element to an existing process, click the Processes tab and then click the name of the process.

4. From the palette, drag the Encode Attachment element on the canvas.

5. In the Properties section, in Attachment, specify the attachment that you want to encode as a binary data.

6. Click Save.

To rename an attachment

When you download or upload an attachment, you can also rename the attachment. 

To rename an attachment, perform the following steps:

1. Log in to BMC Helix Innovation Studio and navigate to the Workspace tab.

2. Select the required application.

3. Perform one of the following tasks:

   1. If you want to add the Rename Attachment element to a new process, select Processes > New. 

   2. If you want to add the Rename Attachment element to an existing process, click the Processes tab and then click the name of the process.

4. From the palette, drag the Rename Attachment element on the canvas.

5. In the Properties section for the element, complete the following fields:

   • New name—Specify the name of the attachment.

   • Attachment—Specify the attachment that you want to rename.

6. Click Save.

Where to go from here

Mapping the REST API web service request alias to an appropriate connection