Asynchronous Processing

Using the Correct Endpoint

There are two endpoints available for integrations in the ExactTarget production environment:

• on.exacttarget.com
  If you use this endpoint, your traffic is routed intelligently between data centers for high availability in case of failure.
• webservice.exacttarget.com
  If you use this endpoint, your calls will fail and return an error if the S1 data center goes down. If you have backup email systems that you want to use in case of failure, you should use this endpoint.

Asynchronous processing works with all other API endpoints (including any pre-production endpoints), but your calls do not receive the same benefits as those calls using on.exacttarget.com. 

Methods

The following methods support asynchronous processing

• Create, passing a properly configured CreateOptions object
• Update, passing a properly configured UpdateOptions object
• Delete, passing a properly configured DeleteOptions object
• Perform, passing a properly configured PerformOptions object

Objects

All objects available in the WSDL can be processed asynchronously. Objects that you include in a conversation should use CustomerKey or SubscriberKey instead of ID or ObjectID.

Objects that have full CRUD Support with CustomerKey or SubscriberKey include:

• TriggeredSendDefinition
• ImportDefinition
• EmailSendDefinition
• SubscriberKey
• DataExtension

The following objects are ideally suited for asynchronous processing because of the nature of the tasks for which they are used:

• TriggeredSend
• SMSTriggeredSend
• VoiceTriggeredSend
• DataExtensionObject

Use CustomerKey for all objects unless your current integration requires PartnerKey. While the application supports PartnerKey, ExactTarget prefers the use of CustomerKey.

Anatomy of the Options base object

Several properties influence asynchronous processing:

• CallsInConversation: Specifies the number of calls in the conversation (optional, but requires ConversationID)
• ConversationID: Specifies a unique identifier that can be used to coordinate conversations and result processing (optional)
• CorrelationID: This property specifies a unique identifier for Subscriber sub-objects on a triggered send and can be used for tracking purposes. This property has no uniqueness constraints. (optional)
• RequestType: Determines the type of request to make -- Asynchronous or Synchronous. (required for Asynchronous processing to occur)
• ScheduledTime: Specifies when the call should be processed (optional)
• SendResponseTo: Defines how responses are returned and under what conditions (optional)
  • ResponseType: How will responses be returned to the caller:
    • None - No response is sent.  You must use Retrieve to get the response.
    • email - An email message that contains the response is sent.
    • FTP - Reserved for future use.
    • HTTPPost - An HTTP POST request will be made that contains the response.
  • ResponseAddress: The address to send the response to.
    • If ResponseType is email, this must be an email address.
    • If ResponseType is HTTPPost, this must be the URL to POST to.
  • RespondWhen: Under what circumstances should notifications be sent:
    • Never - Never sent.
    • OnError - Sent only if an error occurs.
    • Always - Always sent.
    • OnConversationError - Sent if an error occurs within a conversation.
    • OnConversationComplete - Sent when all parts of the conversation have completed processing.
    • OnCallComplete - Sent when a call completes.
  • IncludeResults: Specify true or false to control whether the XML serialized Result objects will be returned.  If ResponseType is email, this information will be supplied as an email attachment.
  • IncludeObjects: Specify true or false to control whether the Object property will be populated in the result XML.  If IncludeResults is false, this property is ignored.
  • OnlyIncludeBase: Specify true or false to control whether the Object property will be populated with the entire object that was received or if only the APIObject properties will be present.  If IncludeObjects is false, this property is ignored.
• SequenceCode: Specifies the processing sequence of a multi-step conversation (optional, but requires ConversationID)

Conversation

Conversations group API calls to be processed in sequence. You provide a unique ConversationID value for each grouping of calls and a sequence number to indicate the order within the conversation. ConversationID is a string value that is specified by the web service client and is unique for the account. You can choose a ConversationID value that matches another unique identifier in your system, so that you can associate the ConversationID activity with other data for reporting.

The system will not process a ConversationID that has been used before. For example, if you send a group of API calls with the ConversationID 1234 and lose connectivity during the send, you can resend ConversationID 1234 when you regain connectivity. If the conversation was processed previously, it will not be processed again.

A conversation will fail if one of the calls in the conversation returns an Error status. If the processing of a conversation fails during one of the sequenced calls, you cannot resubmit the conversation ID to process the remaining calls. You must identify the calls that did not complete and resubmit them with a new ConversationID.

Conversations begin processing after all parts of the conversation are received. If SequenceCode and CallInConversation are not sent, the application assumes the conversation has only one part to process and begins processing immediately. If a conversation fails while processing a request, the entire conversation goes to error and subsequent calls in the conversation are not processed.

SequenceCode must start at 1 and be sequential (you cannot skip values).  The parts can be sent in any order but they will be processed in SequenceCode order.

When a conversation fails, it's important to record the ConversationID and the Sequence code, as the exception logic of the web service client is expected to process the error message and create a new conversation with the remaining steps. As a result, a conversation may take multiple roundtrips and a few different conversationIDs to fully process. For example, if your conversation consists of 3 Create calls that each have 10 Subscriber objects and the first call fails while it is being processed, you will need to create a new conversation with a different ConversationID that consists of the last 2 Create calls.

If you take more than 5 minutes between sending parts, the conversation will be placed into an Error state, it will not be processed and you must start a new conversation with a different ConversationID.

CorrelationID

A CorrelationID identifies individual top-level objects in a call. Use the CorrelationID to provide an identifier to determine the results of an individual top-level object with a call. CorrelationID must be unique per object within a call. Different calls can reuse CorrelationID values.

For example, a Create call containing a List object to be processed asynchronously can have that object identified in the results as having the CorrelationID of "X". Subsequent calls can also have an "X" CorrelationID.

ConversationID is not required to specify CorrelationID. If ConversationID is not specified for a call, then RequestID is what the integration must use to get the results.

The CorrelationID replaces the array index when passing in multiple objects into a call for asynchronous processing. The Correlation ID allows reporting on individual top-level objects in a call.

CorrelationID is exposed via:

• Retrieving ResultItems
• Async Results Data Extract
• Email response when the results are included based on setting inn the Options parameter of the call