Configuring external web APIs to automate processes in BMC Remedyforce

You can configure external web application programming interfaces (APIs) to automate processes in BMC Remedyforce. For example, say that you have all employee information in an LDAP server. To reset an employee password, you can either reset the password manually or configure an external web API in BMC Remedyforce to do it automatically.

The following topics are provided:

Overview of configuring external web APIs to automate processes

You can create multiple web API configurations based on your requirements. Each web API configuration contains the service URL, service type, authentication details, methods, and parameters to perform an action such as unlocking the password in an external application. After you have created web API configurations, you can automate processes in BMC Remedyforce by using any of the following options:

• Task template: Create a task template and specify the appropriate web API configuration. When staff members apply this template to a new or existing task and save the record, a corresponding web API job is created for that task.
  
• Request definition (service request): Create a request definition and include a task template in which you have specified the appropriate web API configuration. When Self Service clients submit the corresponding service request, a related task that is based on the task template is created for the service request. A corresponding web API job is also created for this related task.
• Web API Configuration field on the Task form: Share the list of web API configurations with your staff members. When working with a record such as an incident or change request, staff members can add or update a related task and specify the appropriate web API configuration. A corresponding web API job is created for this related task.  
• Custom workflow or trigger: Create custom workflows and triggers that call the appropriate web API configurations and create web API jobs.

The web API jobs that are created for various tasks are run at scheduled time intervals. You can configure the time interval to run the job scheduler and define the number of times the job scheduler must rerun failed jobs.

Creating web API configurations

To automate processes in your organization, you can create web API configurations. BMC recommends that you communicate the availability and names of these web API configurations to your staff members.

Before you begin

• Get the URL of the service that you are configuring in BMC Remedyforce.
• Create a remote site setting in Salesforce by using the service URL. For more information about creating a remote site, see the Salesforce Help.
  If you are calling a Salesforce API and you will use the service on a sandbox, create a remote site setting with the https://test.salesforce.com URL. To call a Salesforce API on any other type of Salesforce organization, create a remote site setting with the https://www.salesforce.com URL. You must also create another remote site setting for the Instance name used by the Salesforce organization. If you are calling Salesforce APIs from multiple Salesforce organizations that have different Instance names, you must create a remote site setting for each Instance name. For information about identifying the Instance name of your Salesforce organization, see https://help.salesforce.com/apex/HTViewSolution?id=000002889&language=en_US.

• Decide which service type you will use:

  Goal	Service type	Additional information
  Request a Representational State Transfer (REST) service that an application has made available	REST Service	None
  Call a Simple Object Access Protocol (SOAP) service that has only primitive data types, no custom data types, and no custom headers.	Web Service (SOAP Basic)	When you configure the web API, the methods and parameters of the service are provided.
  Call any SOAP service, including services that have primitive and custom data types, custom headers, or any other custom configuration.	Web Service (SOAP Advanced)	When you configure the web API, enter the SOAP envelope, and either provide static values for parameters or insert fields for the task and its related objects. Values of these fields are used when the service is run.

• Understand how to handle special characters in a SOAP envelope or REST body and validate content:

  Content type	Action
  XML	If you paste or write static values in a SOAP envelope or REST body, you must use escaping for special characters (such as <, >, and &) in parameter values. For example, consider the Description parameter of a SOAP envelope with special characters: <tem:Description><![CDATA[smi><&th]]></tem:Description> To validate XML content, you can use validation tools, such as http://www.xmlvalidation.com. For REST Service and SOAP Advanced service types, to insert field (dynamic) values, use CDATA internally. For service type SOAP Basic, to insert whole parameter (static and dynamic) values, use CDATA internally.
  JSON	If you paste or write static values in a REST body, you must use JSON encoding for special characters such as double quotes (") and backslash (\). For the inserted field (dynamic) values, the application handles JSON encoding internally. To validate JSON content, you can use validation tools, such as http://jsonformatter.curiousconcept.com.

To create a web API configuration

1. Click the Remedyforce Administration tab.
2. On the Home page, click the Integrations tile, and from the menu, select Web API Configuration.
3. Click .
4. In the Web API Configuration Name field, enter a unique name for the configuration; for example, Reset password.
5. Select a service type from the list.

   For descriptions of the service types, see Before you begin.

6. In the Service URL field, provide the URL of the service that you want to call.

   Note

   Ensure that you enter the generic domain name, https://<YourSalesforceSubdomainName>.salesforce.com/services/apexrest/BMCServiceDesk/1.0/Incident, in the Service URL field even if the custom domain is defined. For example, if the custom domain is defined as xyz-company.salesforce.com, the Service URL field should be https://cs57.salesforce.com/services/apexrest/BMCServiceDesk/1.0/Incident.

7. (For REST Service only) Perform the following actions:

   • From the Request Content Type list, select the content type of the request.
     If you select XML, ensure that you use XML escaping for special characters (such as <, >, or &) when you specify parameter values. The Request Content Type field is displayed only if you select REST Service in the Service Type list.

   • (Optional) If you want to pass a field value in the service URL, click , and select the field for which you want to pass a value.
     For example, say the client has raised an incident to restart a virtual machine (VM). The objects related to Task must have a field to store the VM details; for example VM ID. In the Insert Field window, select the VM ID field. If the VM ID field is available on the Incident object, in the Insert Field window, select BMCServiceDesk__FKIncident__r >, then select VM ID, and click Insert.

8. In the Authentication section, from the Security Type list, select a security type based on the service configuration.

   • None: Select this option when no authentication is required to call a service.

   • Basic Authentication: Select this option when web server has basic authentication enabled to communicate with a service.

   • Salesforce Session: Select this option if you are calling Salesforce API to communicate with a Salesforce organization.

9. If you have selected the Basic Authentication or Salesforce Session security type, enter the user name and password to authenticate the request with the service provider application.
   For the Salesforce Session security type, if you have enabled a security token in your Salesforce organization, append the security token to your password. For example, if your password is mypassword and your security token is XXXXXXXXX, enter mypasswordXXXXXXXXX in the Password field. 
10. (Optional) To send a request to a service to communicate with a Salesforce sandbox, select the Is Sandbox check box.
11. (Optional) To send a request to a service that requires a certificate name to authenticate, select the Required Certificate check box and enter a name in the Certificate Name field.
12. (Optional) To send a request to a service even after the task that is calling the service is closed, perform the following actions:
    1. Select the Call Web API on Task Closed check box.
    2. In the Hours box, enter the number of hours for which the request continues to be sent to the service even after the task is closed.
       For example, if you close a task at 3:00 p.m., and enter 4 in the Hours field, whenever the job scheduler runs until 7:00 p.m., the service is requested.

13. Click Method Configuration.
    The fields shown depend on the option that you selected in the Service Type field. Based on that option, perform the actions listed in the following table:
    

    Use cases	Actions
    Web Service (SOAP Basic)
    Example: Custom service on a server that has primitive data types	After entering the service URL, click Load Methods. Select a SOAP method. If parameters are required for the selected method, a parameters list is shown. Enter or select parameter values. You can provide static values for these parameters, or you can assign a field value that is used as the parameter value when the service is run. For example, say the parameter is City. You can either enter a static value of New York or select a client city by clicking . In the Insert field window, select {{BMCServiceDesk__Task__r, and then select BMCServiceDesk__FKClient__r.City}}. Click . The following figure shows an example web API configuration of SOAP Basic service type.
    Web Service (SOAP Advanced)
    Reset password of a Salesforce organization	From a web service testing tool such as the SoapUI application, copy the SOAP envelope. In the SOAP Envelope field, paste the SOAP envelope. The following example shows a SOAP envelope: If you are configuring a web API call for a Salesforce service and the call requires that the Salesforce session ID be in the request header, enter ##SESSIONID## in the Session ID header of the SOAP envelope. In the same example, say that you want to send an email message to the client for whom you are resetting the password. In this case, specify 1 for the <urn:triggerAutoResponseEmail> tag, and set the appropriate values for the <urn:triggerotherEmail>. Click .
    REST Service
    Get BMC Client Management device details Export a specific BMC Client Management view, create the output path, create a file in which the requested data is exported, and make the file available for import into the database of an external integration. Get the account information of an incident for which a task is created and a web API configuration is requested in the task.	When you select REST Service in the Service Type field, ensure that you also select a value in the Request Content Type field. For example, to get the device details, select JSON. From the Request Method list, select the operation that you want to perform. For example, to get the device details, select GET. In the Request Body field, enter the body of the request. To make a field value available in the request, click . For example, say that you were requesting a REST service that exports a specific BMC Client Management view, creates the output path, creates a file to which the requested data is exported, and makes the file available for import into the database of an external integration. In this case, in the request body, you must provide the view that you are exporting; for example, {"view":"Atrium_CMDB_ComputerSystem"}. Click . The following figure shows an example web API configuration of service type REST. Note: If you want to specify a Request Header, enter a value in the Request Header field in the <Key>::<Value> format. Ensure that the key and value are separated by using two colons (::). Separate multiple keys by using two semicolons (;;). To make a field value available in the request, click . For example: Key1::Value1;;Key2::{{BMCServiceDesk__Task__r.BMCServiceDesk__AD_Username__c}}.

Configuring the job scheduler to run web API jobs

After you define the web API configurations, you must start the job scheduler. The web API jobs that are created from the web API configurations are run at scheduled time intervals. By default, the Salesforce job scheduler runs web API jobs every 15 minutes. You can configure the job scheduler to run at a time difference (in minutes) that you specify in the WebAPISchedulerInterval custom setting. You can also define the number of times the job scheduler must rerun failed jobs.

Based on your requirements, perform the following actions:

• To start or stop the job scheduler
• To update the number of times to rerun failed jobs
• To configure the time interval to run the job scheduler

To start or stop the job scheduler

1. Click the Remedyforce Administration tab.
2. On the Home page, click the Integrations tile, and from the menu, select Web API Configuration.
3. Click .
4. Perform one of the following actions:
   • To start the scheduler, click Start.
   • To stop the scheduler, click Stop.

To update the number of times to rerun failed jobs

1. Click the Remedyforce Administration tab.
2. On the Home page, click the Integrations tile, and from the menu, select Web API Configuration.
3. Click .
4. In the Retry Count field, enter the number of times, up to 30, that you want to rerun failed jobs.
5. Click .

To configure the time interval to run the job scheduler

1. Click the Remedyforce Administration tab.
2. On the Home page, click the Application Settings tile, and from the menu, select Custom Settings.
3. On the Custom Settings page, click Manage for Remedyforce Settings.
4. Click Edit for the WebAPISchedulerInterval setting.
5. In the value field, type a time interval.
   If you enter a value less than 5, the scheduler will run at an interval of minimum 5 minutes. 
6. Click Save.

Enabling staff members to use web API configurations in tasks

You can share with your staff members the availability and names of web API configurations that you have created. While creating a record such as an incident or change request, staff members can add a related task and specify a web API configuration. However, the Web API Configuration field is not displayed on the Task form by default. You must add this field to the Console - Task Details field set in the Task object.

To enable staff members to use web API configurations in tasks

1. Click the Remedyforce Administration tab.
2. On the Home page, click the Manage Objects tile, and from the menu, select Create and Edit Objects.
3. In the Label column, click Task.
4. On the Task page, navigate to the Field Sets section.
5. In the Action column next to Console - Task Details, click Edit.
6. From the palette, drag Web API Configuration to the In the Field Set list.
7. Click Save.
   In the Remedyforce Console, the Web API Configuration field is now displayed in the Task Details section of the Task form.

Enabling staff members to view the status of web API jobs

When a web API configuration is specified in a task record, corresponding web API jobs are created for the task. You can enable staff members to view the status of these web API jobs. If a job is rerun multiple times before it is successful, staff members can view the failure messages for each run of that job and the number of times the job was rerun.

To enable staff members to view the status of web API jobs

1. Click the Remedyforce Administration tab.
2. On the Home page, click the Manage Objects tile, and from the menu, select Create and Edit Objects.
3. In the Label column, click Task.
4. In the Page Layouts section, click Edit in the Action column for the Remedyforce Task Console version 1.0 page layout.
5. In the palette, click Related Lists and drag Web API Jobs to the layout.

6. In the Web API Jobs related list, click .

7. In the Related List Properties - Web API Jobs window, select the following fields from the Available Fields list, and click the right arrow to move them to the Selected Fields list:
   
   • Success Response
   • Failed Response
   • Retry Count
8. In the Selected Fields list, use the up and down arrows to order the fields based on your requirements.
9. Click the Buttons section, and in the Standard Buttons area, clear the New check box.  
10. To save your changes and close the Related List Properties - Web API Jobs window, click OK.
    In the Remedyforce Console, staff members can now click Record Details on the Task form to view web API jobs created for a task, and the status of each job.

Automating processes in BMC Remedyforce by using web API configurations

The following table provides an overview of the actions you must perform to automate processes in BMC Remedyforce based on the selected option. Before you begin, ensure that you have created the appropriate web API configurations and started the job scheduler.

For information about creating custom workflows and triggers, see the Salesforce Help.