Configure Outbound Messages with an API Manager API¶

Introduction¶

This integration design pattern sets up a Salesforce workflow rule that sends an outbound message to an API Manager API when an object changes (in this example, the Account object). A Design Studio project processes the Salesforce outbound message, maps the object's data, and saves it to a database.

Note

Send Changed Salesforce Object Records to a Database via API Manager is a similar integration design pattern that uses Cloud Studio.

To set up this pattern, follow these sections in order:

Part 1: In Salesforce, set up a workflow rule to send an outbound message when an object changes, and download the WSDL file that defines the message.
Part 2: In Design Studio, set up an operation chain to receive the Salesforce outbound message, and store the mapped values in a database.
Part 3: In API Manager, set up an API as an endpoint for Salesforce.
Part 4: Return to Salesforce to update the outbound message's endpoint URL, activate the outbound message, then test the completed integration design pattern.

Part 1: Set Up a Salesforce Workflow Rule and Download the WSDL File¶

In Salesforce, select Setup > Platform Tools > Process Automation > Workflow Rules.
On the Workflow Rules page, click the New Rule button (highlighted in the image below). If a Try It in Flow Builder dialog opens, click Continue with Workflow Rules.
On the New Workflow Rule page, click the Object menu, select Account, then click Next.
On the Account page, enter values for the following, then click Save & Next:
- Rule Name: Your choice of name.
- Description: (Optional) A description for this rule.
- Evaluation Criteria: Created, and Every Time It's Edited.
- Rule Criteria: Click Run This Rule If the, then select Formula Evaluates to True.
- In the formula field, enter true.
On the Edit Rule page, click Add Workflow Action, then select New Outbound Message (highlighted in the image below).
On the New Outbound Message page, enter values for the following, then click Save:
- Name: Your choice of name.
- Unique Name: This name is automatically generated based on the value for Name and the field's naming rules.
- Description: (Optional) A description for this outbound message.
- Endpoint URL: example.com. This temporary URL is updated later.
- User to Send As: Enter the user that sends the outbound message. The value defaults to your Salesforce username.
- Protected Component: Not selected.
- Send Session ID: Not selected.
- Account Fields to Send: Select the object fields to send. In this example, only Name and Phone are selected. The Id field is selected automatically, because it is the key field for the object.
On the Edit Rule page, click Done.
On the Workflow Rule page, in the Immediate Workflow Actions section, click the description link for the outbound message (highlighted in the image below).
In the message's Workflow Outbound Message Detail page, click the link Click for WSDL in the row labeled Endpoint WSDL (highlighted in the image below).
An XML file opens in a new browser window. Save the file with a .wsdl extension. Depending on your operating system, you may have to set the file's extension after downloading.

Part 2: Design Studio Operations¶

Define the 'Salesforce Outbound Message' Operation¶

Create a new Design Studio project.
In the project items list on the left, right-click on Operations, then select New Operation.
In the Select Type dialog, select Script, then click Continue.
In the Operations window, set the operation name to Salesforce Outbound Message.
Double-click the operation's Script activity, then click Create New Jitterbit Script.
In the New Script window, set values for the following, click Save, then close the script window:
- Name: Receive Salesforce Outbound Message
- Edit the script to match the following:
```
<trans>
$org.api.salesforce.request=$jitterbit.api.request.body;
</trans>
```
This creates a global variable and sets it to the value of the predefined global variable jitterbit.api.request.body.
In the Salesforce Outbound Message operation window, click Save.
In the project items list on the left, right-click on Sources, then select New Source.
In the Select Type dialog, select Global Variable, then click Continue.
In the New Source window, set values for the following, click Save, then close the source window:
- Name: Salesforce API Request
- Type: Global Variable
- Global Variable Name: org.api.salesforce.request

Define the 'Send API Response' Operation¶

Create a new operation of type Transformation. Set the operation name to Send API Response.
Double-click Transformation. In the Select Transformation dialog, click Create New Transformation.
In the New Transformation window's NAME step, enter values for the following, then click Next >:
- Name: Send API Response.
- Source: (None).
- Target: SOAP/WSDL Response.
In the TARGET step, select Select a Local WSDL File, click Browse..., select the WSDL file previously downloaded, then click Next > and wait for file validation.
In the TARGET step, click Next >.
On the Options page, click Finish.
In the Send API Response transformation window, expand all nodes until the element [EV?] Ack (Boolean) is visible, then double-click it.
In the Formula Builder, edit the script to match the following, then click OK to close the script editor:
```
<trans>
true
</trans>
```
This is the response to the Salesforce SOAP request.
In the Send API Response transformations window, click Save, then close the window.
In the Send API Response operation window, right-click on the Target element, select Use API Response, then click Save:

The Salesforce Outbound Message operation:
Open the Salesforce Outbound Message operation, select the down arrow next to the operation name, then select On Success > Operation > Select Existing....
In the Select Success Operation dialog, select Send API Response, then click OK.
In the Salesforce Outbound Message operation window, click Save.

Define the 'Upsert Database' Operation¶

Create a new operation of type Transformation. Set the operation name to Upsert Database.
Double-click the Source activity.
In the Select Source dialog, select Salesforce API Request, then click OK.
Double-click the Target element.
In the Select Target dialog, click Create New Target.
In the New Target window, set values for the following, click Test Connection, then close the Database window:
- Name: Database Endpoint.
- Type: Database.
- Connection Parameters: Set the parameters for your database. (A connection to a PostgreSQL server is shown in this example.)
Double-click the Transformation element.
In the Select Transformation dialog, click Create New Transformation.
In the New Transformation window, enter values for the following, then click Next >:
- Name: Upsert Database.
- Source: SOAP/WSDL Request.
In the SOURCE step, select Select an Existing WSDL File, then select the previously uploaded WSDL file, then click Next > and wait for file validation.
When the file is validated, click Next >.
On the options page, click Next >.
On the TARGET step, click Download List of Tables. Select the target database table, click the right arrow to move it to the Selected Tables list, then click Next >.
In the TARGET step, make sure that Insert/Update is selected, then click Finish.
In the Upsert Database transformation window, expand source and target trees, map fields by dragging and dropping, then click Save and close the transformation window.
In the Upsert Database operation window, click Save and close the window.
In the Salesforce Outbound Message operation, double-click the Receive Salesforce Outbound Message activity.

In the script window, edit the script to match the following, then click Save and close the window:

<trans>
$org.api.salesforce.request=$jitterbit.api.request.body;
RunOperation("<TAG>Operations/Upsert Database</TAG>")
</trans>

In the Salesforce Outbound Message operation window, click Save.
Select Actions > Deploy. In the Deploy dialog, under Select a Deploy Type, select Everything, then click Deploy.

Part 3: API Manager API¶

In API Manager, select My APIs, then click New API.
In step 1 of the Publish New API page, enter values for the following, then click Next:
- API Name: Enter a name for the API.
- Environment: Select the environment where the Design Studio project was deployed to.
- Service Root: Leave the initial value derived from the API name.
- Version Number: (Optional) Enter an API version number.
- Description: (Optional) Enter a description for this API.
In step 2, select Custom API as the Service Type and then click Add API Service. For the new API service, enter these values for the following fields, click Save, and then click Next:
- Request Method: Use the menu to select the POST request method for the API service. By default, the request method is set to GET.
- Service Name: Enter a service name.
- In the Operation tab, select these values:
  - Assign Project: From the menu, select your Cloud Studio project.
  - Assign Operation(s):
    - Operation: Selcect the Salesforce Outbound Message operation.
    - Response Type: Select Final Target as the response type.
In step 3, click Skip This Step.
In step 4, click Save & Publish.
In the dialog titled All Set, Your API is Live!, click Copy URL, then click Dismiss.

Part 4: Update Salesforce Endpoint URL and Activate¶

In Salesforce, select Setup > Platform Tools > Process Automation > Workflow Actions > Outbound Messages.
On the Outbound Messages page, click Edit for your outbound message.
Replace the contents of Endpoint URL field (highlighted in the image below) with the URL copied at the end of the previous section, then click Save.
In the Workflow Rules Using This Outbound Message section, click Activate for the rule (highlighted in the image below).

Test the Integration¶

To test this integration design pattern, follow these steps:

In Salesforce, open the Service app, and select the Accounts tab.
Edit an account contact, then save it.
Log into your database and query the target table.