Configure Outbound Messages with Hosted HTTP Endpoints¶

Introduction¶

This integration design pattern sets up a Salesforce workflow rule that sends an outbound message to a Hosted HTTP Endpoint 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. Hosted HTTP Endpoints can be used only with Private Agents.

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

• Part 1: In Design Studio, create a new operation and copy its hosted web service URL.
• Part 2: In Salesforce, set up a workflow rule to send an outbound message to the web service URL when an object changes, and download the WSDL file that defines the message.
• Part 3: In Design Studio, expand the new operation to receive and acknowledge the Salesforce outbound message, and map and store the changed values in a database.
• Part 4: Return to Salesforce to activate the outbound message, then test the completed integration design pattern.

Part 1: Design Studio Web Service Endpoint URL¶

1. Create a new Design Studio project.

2. In the project items list on the left, right-click on Operations, then select New Operation.

3. In the Select Type dialog, select Hosted Web Service, then click Continue.
4. In the New Operation window, set the new operation name to Accept Salesforce Request.
5. Click the down arrow next to the operation name, then select View Hosted Web Service URL.

6. In the Hosted Web Service URL dialog, in the Server field, enter the hostname or IP address where your private agent is running (123.456.789.001 in this example).

   

   Note

   If the agent is running behind a firewall, you must set up a publicly accessible tunnel or proxy, and open HTTP port 46908 (or 46909 for HTTPS).

7. Click Copy to Clipboard to save the URL for Part 2, then click Close.

8. In the New Operation window, click Save.

   The incomplete Accept Salesforce Request operation:

   

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

1. In Salesforce, select Setup > Platform Tools > Process Automation > Workflow Rules.

2. 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.

   

3. On the New Workflow Rule page, click the Object menu, select Account, then click Next.

   

4. 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.

   

5. On the Edit Rule page, click Add Workflow Action, then select New Outbound Message (highlighted in the image below).

   

6. 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: Paste the hosted web service URL copied in Part 1.
   • 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.

   

7. On the Edit Rule page, click Done.

   

8. On the Workflow Rule page, in the Immediate Workflow Actions section, click the description link for the outbound message (highlighted in the image below).

   

9. 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).

   

10. 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 change the file's extension from .xml to .wsdl after downloading.

Part 3: Design Studio Operations¶

Define a Web Service Method¶

1. In the Design Studio project started in Part 1, in the project items on the left, right-click on Web Service Methods and select New Web Service Method.

2. In the New Web Service Method window, select Select a Local WSDL File, click Browse, select the WSDL file previously downloaded, then click Next > and wait for file validation.

   

3. In the Operation step, click Next >.

   

4. In the Details step, click Finish.

   

5. Close the New Web Service Method window.

   

Define a Web Service Call¶

1. In the Accept Salesforce Request operation window, double-click the Web Service Call activity.

2. In the Select Web Service Call dialog, select New Web Service Method, then click OK.

   

3. Double-click the end transformation activity, then click Create New Transformation.

4. In the New Transformation window, set values for the following, then click Finish:

   • Name: Salesforce Response.
   • Source: (None)

5. In The Salesforce Response transformation window, expand all target nodes until the element [EV?] Ack (Boolean) is visible, then double-click it.

   

6. In the Formula Builder window, edit the script to match the following, then click OK to close the script editor:

   <trans>
   true
   </trans>
   

   

7. In the Salesforce Response transformation window, click Save, then close the window.

   

8. Double-click the middle transformation activity, then click Create New Transformation.

9. In the New Transformation window, set values for the following, then click Next >:

   • Name: Salesforce Request
   • Target: Text

   

10. In the Target step, click Available File Format Definitions, then select Create New.

11. Set values for the following, then click Create Manually.

    • Name: Salesforce Request Format
    • Select Document Type: Simple Text Document
    • Select Document Format: Character Delimited

    

12. In the Define Segment Properties section, click the New button to create a new field.

13. In Field Name, enter Blank, then click Finish.

    

14. Close the Salesforce Request transformation window.

    The incomplete Accept Salesforce Request operation:

    

Define the 'Incoming Request' Source¶

1. In the project items list on the left, right-click on Sources, then select New Source.

2. In the Select Type dialog, select Temporary Storage, then click Continue.

3. In the New Source window, enter values for the following:

   • Name: Incoming Request
   • Get Files: IncomingRequest[fileGUID].xml

   

4. Click Save, then close the window.

5. In the project items list on the left, right-click on the new Incoming Request source, then select Copy to New Target.

6. In the Incoming Request target window, click Save, then close the window.

   

7. In the Accept Salesforce Request operation window, double-click the Salesforce Request transformation.

8. In the Salesforce Request transformation window, double-click the Blank field in the target tree.

   

9. In the Formula Builder window, edit the formula to match the following, then click OK to close the script editor:

   <trans>
   $fileGUID=GUID();
   WriteFile("<TAG>Targets/Incoming Request</TAG>", GetXmlString([root$], true]));
   </trans>
   

   

10. In the Salesforce Request transformation window, click Save, then close the window.

    

Create the 'Upsert Database' Operation¶

1. In the Accept Salesforce Request operation window, select the down arrow next to the operation name, then select On Success > Operation > Create New Operation.

2. In the Select Type dialog, select Transformation, then click Continue.

3. Set the new operation's name to Upsert Database.

   

4. In the Upsert Database operation, double-click Source.

5. In the Select Source window, select Incoming Request, then click OK.

   

6. In the Upsert Database operation, double-click Target.

7. In the Select Target window, click Create New Target.

8. In the New Target window, set values for the following, click Test Connection, then close the Database window:

   • Name: Database
   • Type: Database
   • Connection Parameters: Set the parameters for your database. (A connection to a PostgreSQL server is shown in this example.)

   

9. In the Upsert Database operation, double-click Transformation.

10. In the Select Transformation window, select Create New Transformation.

11. In the New Transformation window, enter values for the following, then click Next >:

    • Name: Salesforce to Database
    • Source: Hosted Web Service Request

    

12. In the Source step, click Next >.

    

13. In 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 >.

    

14. In the Target step, click Finish.

    

15. In the Salesforce to Database transformation window, expand source and target trees, map fields by dragging and dropping, then click Save and close the transformation window.

    

16. In the Accept Salesforce Request operation window, click Save.

    

17. From the main menu, select Actions > Deploy. In the Deploy dialog, under Select a Deploy Type, select Everything, then click Deploy.

Part 4: Update Salesforce Endpoint URL and Activate¶

1. In Salesforce, select Setup > Platform Tools > Process Automation > Workflow Rules.

2. On the All Workflow Rules page, click Activate for your outbound message (highlighted in the image below).

   

Test the Integration¶

To test this integration design pattern, follow these steps:

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