This page describes an approach for configuring outbound messages using Hosted HTTP Endpoints in Design Studio. This applies to Salesforce outbound messaging as well as to Autodesk evented webhooks and generic webhooks.
To demonstrate configuring outbound messages using Hosted HTTP Endpoints, we use an example of sending an outbound message from Salesforce to Jitterbit that is triggered whenever the Account object is updated in Salesforce. Jitterbit then processes the outbound message request and inserts and/or updates Account information in an Oracle database to keep the information synced. Refer to the Jitterpak Outbound_Message_Hosted_HTTP_Endpoint.jpk for the example setup.
Step 1 – Configure Firewall Ports
In order for the Private Agent to communicate with systems that can post to endpoints, the firewall on the machine where the Private Agent resides must allow access through the appropriate ports. The ports that need to remain open are 46908 for HTTP and 46909 for SSL (if SSL is used).
This allows the call from the system (such as Salesforce) to the Private Agent, as well as the confirmation call back to the system.
Step 2 – Create Workflow Rule and Outbound Message to Obtain WSDL (Salesforce)
An outbound message must be triggered to call to the Private Agent. In Salesforce, this can be set up using a workflow rule that triggers the outbound message.
- Log in to your Salesforce account and open your Workflow Rules.
- Go to Setup > Process Automation > Workflow Rules.
- Or, from Setup, use the Quick Find box to find Workflow Rules.
You should be on the screen showing All Workflow Rules. Click the button for a New Rule.
The New Workflow Rule screen will take you through a series of steps to set up your new rule. In the first step, Step 1: Select object, select the Salesforce object that you will be working with in Jitterbit. Click Next.EXAMPLE: In the example, we used the Salesforce object "Account."
- Next is Step 2: Configure Workflow Rule:
Edit Rule: Give your rule a Rule Name. It is best practice to include the name of the Salesforce object that the rule applies to in the rule name. Optionally, enter a Description of your rule.EXAMPLE: In the example, we named our rule "Jitterbit-Account," used to push Salesforce account updates to Jitterbit.
Evaluation Criteria: Select the evaluation criteria for your specific use. If you need to create and not update, select the first "created" option. If you are going to use synchronization in your operation, select the second "created, and every time it's edited," option. If you have a timed event, select the third option ,"created, and any time it's edited to subsequently meet criteria."EXAMPLE: In the example, we selected "created, and every time it's edited" because we want the Salesforce "Account" object to synchronize.
Rule Criteria: In order to prevent an infinite loop when objects are updated, it is strongly suggested to exclude the Salesforce username that is configured on the Salesforce Org in Jitterbit. Under Field, use the dropdown to select "Current User: Username," with the Operator specified as "not equal to," and the Value as the Salesforce username for the Salesforce Org used in Jitterbit. Click Save & Next to continue.
Next, in Step 3: Specify Workflow Actions, you will need to define the action that should happen when the rule is triggered. Under Immediate Workflow Actions, use the Add Workflow Action dropdown to select New Outbound Message.
Give your outbound message a Name and optionally a Description.
EXAMPLE: In the example, we named our outbound message "Jitterbit-Account Update," defining the fields to send to Jitterbit.
NOTE: The Unique Name can be left as the name that is automatically generated unless another outbound message with the same unique name has previously been used on your Salesforce account.
Enter the Endpoint URL obtained from Jitterbit. To determine this, see Finding the Endpoint URL. Make sure to leave the operation open or save it because you will need to configure this same operation later during the Design Studio steps.
NOTE: The Endpoint URL is unique to each operation within Jitterbit, so you must use the same operation associated with the Endpoint URL later in this process.
Select the Available Fields that you want to use in your Jitterbit operation and add them to the Selected Fields side using the arrows. The "Id" field will be selected automatically. When you are done, click the Save button.
NOTE: It is recommended to include all desired fields that you want to sync in the outbound message in order to cut down on the number of API requests.
This is because a workflow rule can apply to only one object in Salesforce. Therefore an outbound message is for a single object. Note that you cannot use an outbound message to edit and then send the account and all the contacts into a database. Instead you can send the ID field in the outbound message into Jitterbit, and then query back into Salesforce to pull all the desired records (see Salesforce Query Wizard).
This should return you to the Step 3: Specify Workflow Actions screen. From here, within Immediate Workflow Actions, click on the name of the outbound message you have just created. On the next screen, under Workflow Outbound Message Details, next to Endpoint URL, use the "Click for WSDL" link and save the file, being sure to change the file extension from .xml to .wsdl. You may also wish to change the name of the WSDL file to reflect the specific outbound message.EXAMPLE: In the example, we named our WSDL file "jitterbit-account-outbound.wsdl."
Step 3 – Create Web Service Method (Design Studio)
Now you are ready to create the Web Service Method within Design Studio. This will be used later in the Hosted Web Service operation.
Within your Design Studio project, create a new web service method. This can be done in several ways described in Creating a Web Service Method. One way is to right-click on Web Service Methods in the project items list on the left, and and select New Web Service Method.
You will be brought to the first step of the Web Service Method Wizard: Name & WSDL. Give your Web Service Method a meaningful name and specify the location of your WSDL file. Then click Next to continue.EXAMPLE: In the example, this is the WSDL file we downloaded from Salesforce for our outbound message, so we selected the button "Select a local WSDL file," and browsed to the location where we saved the WSDL.
You will be brought to the second step of the wizard: Operation. If you have multiple available methods under the dropdown menu, select the appropriate one here. You can determine which one you need by looking at the request and response structures. Click Next to continue.EXAMPLE: For a Salesforce outbound message, nothing needs to be modified, so we just click Next.
The final step of the wizard is Details. If you have additional information to include, you can specify it here. Then click Finish when complete.EXAMPLE: In the example, we had nothing to add, so we just clicked Finish.
- Your Web Service Method is now created. Close the Web Service Methods tab.
Step 4 – Create Hosted Web Service Operation (Design Studio)
Next, you need to configure the operation you created when Finding the Endpoint URL to enter in Salesforce. The Endpoint URL is unique to the operation, so the same operation must be used.
Within your Hosted Web Service operation, double-click the Web Service Call box and select your newly created Web Service Method. Or, from the tree on the left, simply drag your Web Service Method into your operation.NOTE: Notice that there are two separate Transformation boxes in this operation. The first transformation occurs when a message is received from Salesforce. This transformation is used to map account data. The second transformation replies to Salesforce, communicating that you have received the record.
Right-click on the Transformation box on the far right side of the operation (the second transformation), and click Create New Transformation.NOTE: It does not matter which transformation you configure first; we do the second one first since it is simpler.
You will be brought to the first step of the Transformation Wizard: Name. Enter a meaningful Name and set the Source to "(None)." Then click Finish.
NOTE: The Source step of the Transformation Wizard is no longer applicable when the Source is set to "(None)," and the Target is already configured, so the wizard is now complete.EXAMPLE: In the example, we named our second transformation "SF Account - Response" because the second transformation replies to Salesforce, communicating that you have received the record.
The Transformations tab will display. On the right side (target side), fully expand the tree and double-click on "[EV?] Ack (Boolean)."
The Formula Builder will display. Type the word "true" (no quotes) between the <trans> tags and click OK. Then save and close the Transformations tab.NOTE: The "true" lets Salesforce know the record was received successfully. If "true" were not received, then Salesforce would continue trying to send the record for 24 hours increasing the time between attempts.
Right-click on the Transformation box in the middle of the operation. This should be the only item still left unmodified in this operation. Click Create New Transformation.
You will be brought to the first step of the Transformation Wizard: Name. Enter a meaningful Name and select a Target for the data that you are going to pull from Salesforce. Then click Next.NOTE: It is a common practice in Jitterbit to use an initial Target of "Text" to create a default CSV that just has one column so that we can later pull the data using a script.EXAMPLE: In the example, we named our first transformation "SF Account - Request" and selected "Text" as the Target. We will create a separate operation later in order to write the information to a database.
The next step in the wizard is Target. To create a default CSV to later use for scripting, select New File Format, give the new file a Name, and click the button Create Manually.NOTE: The Source step is skipped because the transformation is already configured to use a Web Service Request.
On the next screen under Define Segment Properties, click the New button and add a new Field Name so that you have a field available. Then click Finish.EXAMPLE: In the example, we called our new field name "Blank" as a default.
Now you can create a new Source that will serve as the input for the database update. We will set up the mappings in a little while. For now, right-click on Sources in the tree and select New Source. For the Type, select Temporary Storage. Then click Continue.
On the next screen, give the new Source a name. Under Get Files, type the following (recommended): IncomingRequest.[fileGUID].xml. This will be used later in this process as the source of a new upsert operation. Then save and close out of the Sources tab.NOTE: Using a global variable such as fileGUID is highly recommended. This will insert a GUID to create unique file names so you won't inadvertently overwrite files from a different operation if there are multiple calls. The variable fileGUID will be defined later in the process.
Now right-click on your new Source and select Copy to New Target. This will create the same setup for the Target. This will be used later in this process to save the contents of the request. Save and close out of the Targets tab.
Go back to the Transformations tab, and on the right side (target), double-click the default field name you created to open the Formula Builder.EXAMPLE: In the example, we named this field "Blank."
<trans>tags, enter the following. As you type, select the appropriate choices in the popup boxes to populate the arguments. The [root$] in the below example is obtained from double-clicking the "root" folder under the tree on the right side of the page. You may also need to manually remove or replace other text to match that below. Then click OK, save, and close the Transformations tab.NOTE: If you're going to be running a query back into Salesforce to pull your data, you can use $sf.id=root$transaction$body$notifications$Notification.sObject$Id$ in your script.
Step 5 – Create Upsert Operation (Design Studio)
Next you are ready to configure another operation that will write to the database.
Return to the Operations tab and right-click on the operation or on the down arrow next to the operation title. Navigate through the menus: On Success > Operation > Create New Operation.
Select Transformation as the type. Then click Continue. A new operation will appear within the Operations tab.
Within the new operation, double-click on the Source and set to the source you created.EXAMPLE: In the example, ours was called "Incoming Request."
Within the new operation, double-click the Target icon and configure for your desired final target. Select an existing target that is configured for the Salesforce data that you are pulling, or create a new target. See additional instructions for targets under Targets. After filling out the details, make sure to test your connection and then click Next.EXAMPLE: In the example, we used the wizard to set up a new Oracle database as the target.
- Within the new operation, double-click on the Transformation and select Create New Transformation. The Transformation Wizard will open.
On the Name screen, give your transformation a Name. For Source, choose Hosted Web Service Request. Click Next to continue.
On the Source screen, select the Web Service Method that you set up earlier in this process. Click Next to continue.
On the Target screen, click the button to Download List of Tables. Filter or look through the Available Tables and select the one you want to use, then use the arrows to add it to the Selected Tables list. Click Next to continue.
Next, choose the Insert/Update Mode that fits your needs. Insert/Update is for new records and record updates, Insert Only is for new records only, and Update Only is for record updates only. Then click Finish at the bottom of the screen.EXAMPLE: In the example, we chose Insert/Update (upsert) because we want to create new records and update existing records.
The Transformations tab will open, allowing you to create your mappings by dragging and dropping from the source (left side) to the target (right side). After you create the mappings, be sure to save.NOTE: The red text in the image below indicates a required field; however, it's OK that this field is not mapped because the ID field will be generated on the database side.
You are now ready to deploy the project to your selected Harmony Environment. Click the deploy icon.NOTE: Don't stop here. There is one final step to complete after deploying!
Step 6 – Activate Outbound Message Trigger (Salesforce)
You are now ready to turn on the rule that triggers the outbound message to Jitterbit.
In Salesforce, return to your Workflow Rules and click on the rule you would like to use. Then click the Activate button to activate the trigger.
Other Ways to Configure Outbound Messages
Using Hosted HTTP Endpoints to configure outbound messages as described on this page is not the preferred approach.
Instead, it is recommended to use a custom Jitterbit Harmony API. Refer to Configuring Outbound Messages with Harmony API for the recommended approach. An additional example using a custom Jitterbit API is provided at Capturing Data Changes with a Harmony API or HTTP Endpoint.
NOT RECOMMENDED: Another approach that is not recommended uses the web service response from the outbound message WSDL to catch the values as variables; then, at the end of the field has the boolean "true" which will go back as an acknowledgment to Salesforce that the message has been received.
The problem with this approach is that there will be a popup that asks, "Do you want to change the mapping to use the first instance for each source?"
- If you click "Yes," and there is more than one record coming in through the outbound message, only the first one will be processed.
- If you click "No," then the value for the variable where the source field is being captured will be an array. If this is not scripted for, then it causes problems.