49
above, the source object may change after a notification is sent but before it is delivered, so the endpoint will only receive
the latest data, not any intermediate changes.
• Because a message may be delivered more than once, your listener client should check the notification IDs delivered in the
notification before processing.
Note: Instead of polling, which was required in previous releases, you can now use outbound messaging to trigger
execution logic when Salesforce raises an event. In previous versions of the API, client applications had to poll Salesforce
to find out if relevant changes had occurred. Because most changes eventually trigger workflow if a rule exists for it, you
can use this to trigger actions based on Salesforce events.
The metadata needed for outbound messaging, including the definition of the
notifications()
method, which sends the
outbound SOAP message to an external service, is in a separate WSDL.The WSDL is created and available from the Salesforce
user interface once a workflow rule has been associated with an outbound message.The fields to be delivered in the message
are also defined in this WSDL. For more information about setting up outbound messaging, see the Salesforce online help
topic "Defining Outbound Messages."
API access is limited to access to the outbound messaging WSDL.
Before you begin working with outbound messaging in the API, review the following information:
• Setting Up Outbound Messaging
• Important Security Considerations
• Understanding the Outbound Messaging WSDL
• Building a Listener
Setting Up Outbound Messaging
Before you can use outbound messaging, you must set it up via the Salesforce user interface:
• Setting Up User Profiles
• Defining Outbound Messaging
• Downloading the Salesforce Client Certificate
• Viewing Outbound Messages
• Tracking Outbound Message Status
Setting Up User Profiles
It is possible to create circular changes with outbound messaging. For example, if a user is performing integrations that trigger
workflow, and the workflow actions trigger account updates, those account updates trigger new workflow, and so on in an
endless loop. In order to prevent these circular changes in Salesforce, you can disable outbound message access for a user.
The following is another example of a circular change scenario:
1. You configure an outbound message to include a
sessionId
and specify a user in the User to send as field.The user does
not have outbound messaging disabled.
2. A change in a contact record triggers an outbound message from the specified user, with the
sessionId
to your outbound
message listener.
3. Your outbound message listener calls the Force.com API and updates the same contact record which triggered the outbound
message.
4. The update triggers an outbound message.
5. Your outbound message listener updates the record.
6. The update triggers an outbound message.
7. Your outbound message listener updates the record.
475
Setting Up Outbound Messaging
55
To disable outbound messaging for a user, select “Disable Outbound Messages" in the user's Profile.Salesforce recommends
specifying a single user to respond to outbound messages, and disabling outbound messages for this user.
Defining Outbound Messaging
To define outbound messages, use this procedure in the Salesforce user interface:
1. Click Setup
➤
Create
➤
Workflow & Approvals
➤
Outbound Messages.
2. Click New Outbound Message.
3. Choose the object that has the information you want included in the outbound message, and click Next.
4. Configure the outbound message.
a. Enter a name and description for this outbound message.
b. Enter an endpoint URL for the recipient of the message.Salesforce sends a SOAP message to this endpoint.
For security reasons,Salesforce restricts the outbound ports you may specify to one of the following:
• 80:This port only accepts HTTP connections.
• 443:This port only accepts HTTPS connections.
• 7000-10000 (inclusive):These ports accept HTTP or HTTPS connections.
c. Select the Salesforce user to use when sending the message by specifying a username in the User to send as field.The
chosen user controls data visibility for the message that is sent to the endpoint.
d. Select Include Session ID if you want a Salesforce
sessionId
to be included in the outbound message. Include the
sessionId
in your message if you intend to make API calls back to Salesforce from your listener.The
sessionId
represents the user defined in the previous step and not the user who triggered the workflow.
e. Select the fields you want included in the outbound message and click Add.
5. Click Save.
6. On the outbound message detail page, click the Click for WSDL link to view the WSDL associated with this message.
The WSDL is bound to the outbound message and contains the instructions about how to reach the endpoint service and
what data is sent to it.
Note: If you do not have these options, your organization does not have outbound messaging enabled. Contact
salesforce.com to enable outbound messaging for your organization.
Downloading the Salesforce Client Certificate
Your application (endpoint) server's SSL/TLS may be configured to require client certificates (two-way SSL/TLS), in order
to validate the identity of the Salesforce server when it takes the role of client to your server. If this is the case, you can download
the Salesforce client certificate from the Salesforce application user interface.This is the client certificate that Salesforce will
send with each outbound message for authentication.
To download the certificate, use this procedure:
•
Click Setup
➤
Develop
➤
API to display the WSDL Download page.
• In the WSDL Download page, right-click Download Client Certificate and save it to an appropriate location on your
local drive.
• Import the downloaded certificate into your application server, and configure your application server to request the client
certificate.The application server then checks that the certificate used in the SSL/TLS handshake matches the one you
downloaded.
476
Setting Up Outbound Messaging
59
Viewing Outbound Messages
To view existing outbound messages, click Setup
➤
Create
➤
Workflow & Approvals
➤
Outbound Messages in the
Salesforce user interface.
• Click New Outbound Message to define a new outbound message.
• Click View Message Delivery Status to track the status of an outbound message.
• Select an existing outbound message to view details about it or view workflow rules and approval processes that use it.
• Click Edit to make changes to an existing outbound message.
• Click Del to delete an outbound message.
Tracking Outbound Message Status
To track the status of an outbound message, click Setup
➤
Monitoring
➤
Outbound Messages in the Salesforce user
interface. Alternatively, click Setup
➤
Create
➤
Workflow & Approvals
➤
Outbound Messages, and then click View
Message Delivery Status. From this page you can perform several tasks:
• View the status of your outbound messages including the total number of attempted deliveries
• View the action that triggered the outbound message by clicking any workflow or approval process action ID.
• Click Retry to change the Next Attempt date to now.This causes the message delivery to be immediately retried.
• Click Del to permanently remove the outbound message from the queue.
Important Security Considerations
In order to safely use outbound messaging, you must ensure that no third party can send messages to the endpoint while
pretending to be from Salesforce:
• Lock down the client application’s listener to accept requests only from Salesforce's IP range.While this guarantees the
message came from Salesforce, it does not guarantee that another customer is not pointing to your endpoint and sending
messages.
• Use SSL/TLS. Using SSL/TLS provides confidentiality while data is transported across the internet.Without it, a malicious
third party can eavesdrop on your data.This issue is especially important if you pass data with privacy requirements and
you pass a
SessionId
with the message. Also, we authenticate the certificate presented on connection, ensure that it is
from a valid Certificate Authority, and check that the domain in the certificate matches the one Salesforce is trying to
connect.This prevents us from communicating with the wrong endpoint.
• If the configuration of your application (endpoint) server's SSL/TLS allows, validate the identity of the Salesforce server
when it takes the role of a client to your server, using the Salesforce client certificate. For instructions to download the
certificate, see Downloading the Salesforce Client Certificate.
• The organization
Id
is included in each message (see ID Field Type for more information about the Id field type).Your
client application should validate that messages contain your organization
Id
.
Understanding the Outbound Messaging WSDL
The rest of this topic examines relevant sections of the outbound messaging WSDL.Your WSDL may differ, depending on
the choices you made when you set up outbound messaging for a particular event on a particular object.
477
Important Security Considerations
65
notifications()
This section defines the
notifications()
call, which creates an outbound message containing specified fields and values
for a particular object or objects, and sends the values to a specified endpoint URL:
<schema elementFormDefault="qualified" xmlns="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://soap.sforce.com/2005/09/outbound">
<import namespace="urn:enterprise.soap.sforce.com" />
<import namespace="urn:sobject.enterprise.soap.sforce.com" />
<element name="notifications">
<complexType>
<sequence>
<element name="OrganizationId" type="ent:ID" />
<element name="ActionId" type="ent:ID" />
<element name="SessionId" type="xsd:string" nillable="true" />
<element name="EnterpriseUrl" type="xsd:string" />
<element name="PartnerUrl" type="xsd:string" />
<element name="Notification" maxOccurs="100"
type="tns:OpportunityNotification" />
</sequence>
</complexType>
</element>
</schema>
Use this table to understand the elements named in the notifications method definition:
Description
Type
Name
ID of the organization sending the message.
ID
OrganizationId
The workflow rule (action) that triggers the message.
string
ActionId
Optional, a session ID to be used by endpoint URL client that is responding to
the outbound message. It is used by the receiving code to make calls back to
Salesforce.
string
SessionId
URL to use to make API calls back to Salesforce using the Enterprise WSDL.
string
EnterpriseURL
URL to use to make API calls back to Salesforce using the Partner WSDL.
string
PartnerURL
Defined in the next section, contains the object datatype and its
Id
, for example
OpportunityNotification or ContactNotification.
Notification
Notification
The Notification datatype is defined in the WSDL. In the following example, a Notification for opportunities is defined,
based on the Notification entry of the
notifications()
call definition:
<complexType name="OpportunityNotification">
<sequence>
<element name="Id" type="ent:ID" />
<element name="sObject" type="ens:Opportunity" />
</sequence>
</complexType>
Each object element (in our example, opportunities) contains the subset of the fields that you selected when you created the
outbound message. Each message Notification also has the object ID, and this needs to be used to track redelivery attempts
of notifications you've already processed.
478
Understanding the Outbound Messaging WSDL
Documents you may be interested
Documents you may be interested
