| Description | Manage Marketing Campaign Outbounds |
| Name | ManageCampaignOutboundIn |
| Namespace | http://sap.com/xi/A1S/Global |
| Process Component Description | Campaign Management |
| Process Component Name | CampaignManagement |
| Process Component Namespace | http://sap.com/xi/AP/CRM/Global |
| Deploymnent Unit Description | Customer Relationship Management |
| Endpoint Activation | By Scoping of Process Component | Operations |
| Release Status | Deprecated |
An interface to replicate marketing campaign outbounds from a source system or file to a target system.
This web service is used to maintain campaign outbound data by external consumers.
The web service provides two operations. The MaintainBundle operation is used to create, update or delete one or more instances of marketing campaign outbounds whereas the CheckMaintainBundle operation is used to check if one or more marketing campaign outbounds could be maintained.
The signature of both operations is identical.
Technical Prerequisites:
This web service must be activated by a communication arrangement maintained for the communication scenario Manage campaign outbounds.
For perfomance reasons we recommend to upload 100 to 500 outbounds.
The web service does not support more than 1000 outbounds in one call.
Existence of transactional data:
Marketing campaigns referred in the outbound service interface must exist in the system, this service does not create or delete any marketing campaigns.
Existence of master data:
All master data are only referenced, and will not be created by the service. They must already exist in the system at the time the web service is called:
Customers
Contact Persons
Maintain Bundle operations enable external applications to maintain business document data. Check Maintain Bundle operations enable external applications to simulate maintain bundle requests without changing business document data. The intention of this operation is to run the same checks as done in the Maintain Bundle operation but without saving the changes.
Action Code is a coded representation of an instruction to the recipient of a message telling them how to process a transmitted node or element. It is modeled as an attribute (attribute name: actionCode) in structure elements of the message payload.
| Action Code | Description |
|---|---|
| 01 | Create; the system returns an error message if the node element already exists. |
| 02 | Update; the system returns an error message if the node element does not exist. |
| 03 | Delete; the system returns an error message if the node element does not exist. |
| 04 | Save; the system creates or changes the node element data. |
| 05 | Remove; the system deletes the node element. If the node element does not exist, the system does not send an error message. |
| 06 | No Action; the system does not change the node element. |
Default action code: 04 (Save).
Note: Action code 04 (Save) creates business documents if the system could not identify a matching target business document. This applies in particular if no business document ID or UUID is provided by the web service consumer. The web service consumer (external application) is responsible for providing correct business document IDs or UUIDs and avoiding accidental creation of duplicate business documents.
Example
The following code snippet illustrates the usages of action codes. It requests the creation of new outbound instance and returns an error message if the instance exists already.
Show full documentation
Show full documentation
<Outbound actionCode="01">
<CustomerInternalID>4711</CustomerInternalID>
<ContactPersonInternalID>4712</ContactPersonInternalID>
<CommunicationStatusCode>2</CommunicationStatusCode>
</Outbound>
The processing of node elements with cardinality > 1 (for example a list of texts or a list of solution proposals) can be controlled using List Complete Transmission Indicators (LCTI). The LCTI indicates whether a list of node elements is completely transmitted. The LCTI of a node element with cardinality > 1 is modeled as attribute of its parent node element (attribute name: <name of child element>ListCompleteTransmissionIndicator).
| LCTI | Description |
|---|---|
| false | The list of node elements is not completely transmitted. Hence, all node elements that are not transmitted remain unchanged. If transmitted node elements in the list can be uniquely identified, the system processes the node elements according the action code. If transmitted node elements of the list cannot be uniquely identified, the system appends the node element to the corresponding list of node elements in the target business document. |
| true | The list of elements is completely transmitted. Hence, all node elements that are not transmitted are removed. If no node element is transmitted, the complete list is removed. |
Default list complete transmission indicator: false.
Note: The LCTI refers to the completeness of the list of node elements and does not imply completeness of sub-elements.
Example
The following example demonstrates the usage of the LCTI. It deletes all existing outbounds, except the outbounds specified by the ID and creates or changes the outbounds as passed by the external application.
...
<Campaign actionCode="06" outboundListCompleteTransmissionIndicator="true">
<ID>1112</ID>
<Outbound>
<CustomerInternalID>A2001</CustomerInternalID>
<ContactPersonInternalID>CP2002</ContactPersonInternalID>
...
</Outbound>
<Outbound>
<CustomerInternalID>A2010</CustomerInternalID>
<ContactPersonInternalID>CP2012</ContactPersonInternalID>
...
</Outbound>
<Outbound>
<CustomerInternalID>A3001</CustomerInternalID>
<ContactPersonInternalID>CP3002</ContactPersonInternalID>
...
</Outbound>
</Campaign>
...
Optional leaf elements in request messages that are not transmitted within a web service request are not changed in corresponding business documents.
Example
Only the element CommunicationStatusCode of the campaign outbound is updated. The CommunicationFailureReasonCode as well as the other elements (not contained) remain unchanged.
...
<Campaign>
<ID>1112</ID>
<Outbound>
<CustomerInternalID>A2001</CustomerInternalID>
<ContactPersonInternalID>CP2002</ContactPersonInternalID>
<CommunicationStatusCode>1</CommunicationStatusCode>
</Outbound>
<Outbound>
<CustomerInternalID>A2010</CustomerInternalID>
<ContactPersonInternalID>CP2012</ContactPersonInternalID>
<CommunicationStatusCode>4</CommunicationStatusCode>
</Outbound>
</Campaign>
...
Maintain bundle and check maintain bundle operations are mass-enabled stateless synchronous web service operations. Transferring or requesting amounts of data that are too large causes communication timeouts. The web service consumer is responsible for ensuring reasonable sizes for mass operations.
Maintain bundle and check maintain bundle operations support exactly one execution (idem potency). To ensure exactly one execution of web service requests, the web service consumer must provide unique values for the elements ID or UUID of the "BasicMessageHeader" node element.
Using the change state identifier (element name "ChangeStateID"), external applications can enforce that a modifying operation is not executed because the state of the business document has changed since the external application last read its data.
The change state ID is an uninterpretable string that is provided by query and read operations, and can be utilized by all modifying operations. If the change state identifier is provided when calling a modifying operation, the system does not perform the operation if the state of the business document instance has changed since the change state ID was computed. If the change state ID is not provided by the web service consumer, the system performs the web service operation without checking the state of the business document.
The web service consumer (external application) is responsible for preventing accidental changes to business documents.
Request node elements with cardinality > 1 contain object node sender technical identifier to relate response message elements and log items to corresponding node elements in the request message.
The object node sender technical identifiers are provided as ObjectNodeSenderTechnicalID in request message types, and are referred to as ReferenceObjectNodeSenderTechnicalID in corresponding response message types.
If the object node sender technical ID is initial, the object node sender technical ID of the parent node element in the request is returned as the reference object node sender technical ID. If the object node sender technical IDs of all parent node elements are initial, the reference object node sender technical ID is returned as initial as well.
Note: The values specified in the ObjectNodeSenderTechnicalID are transient values that establish the correspondence between elements only for a single call. The web service consumer is not required to specify them, or to use the same values for different calls. Also, the service provider does not interpret these values at all. Instead, the service provider returns them to the web service consumer in the ReferenceObjectNodeSenderTechnicalID elements.
Note: The ObjectNodeSenderTechnicalID is also used to identify failed business document modifications in a mass operation.
Example
Request:
<Root>
<Child>
<ObjectNodeSenderTechnicalID>999_A<ObjectNodeSenderTechnicalID>
<Content>
Child A: Some correct content
</Content>
</Child>
<Child>
<ObjectNodeSenderTechnicalID>999_B<ObjectNodeSenderTechnicalID>
<Content>
Child B: Some erroneous content
</Content>
</Child>
Response:
<Log>
<Item>
<ReferenceObjectNodeSenderTechnicalID>999_B</ReferenceObjectNodeSenderTechnicalID>
<Note>Error message for Child B</Note>
</Item>
</Log>
The structure of the response message consists of two parts:
A business document-specific part containing information about IDs and UUIDs of the created and changed business documents
Log items containing system messages including errors, warnings, and information messages raised by the system during processing of the web service request
You can find general information about Web services, their structure and consumption in the Web Services documentation.
A typical use case for using this web service is the execution of marketing campaigns in external system. The information about the identifiers of customers and contact persons and any status information of active marketing campaigns is transmitted back to the system by using this web service:
Create marketing campaigns and export marketing campaigns to external systems
Execute marketing campaign in external systems
Transmit information about customers, contact persons and status back to the system.
Example
Create new marketing campaign outbounds based on the marketing campaign executed in an external system.
Request:
<n0:CampaignOutboundBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
<BasicMessageHeader>
<ID>00163E01277C1EE186B9834511A002AB</ID>
</BasicMessageHeader>
<Campaign>
<ID>1112</ID>
<Outbound>
<ObjectNodeSenderTechnicalID>1001</ObjectNodeSenderTechnicalID>
<CustomerInternalID>A2001</CustomerInternalID>
<ContactPersonInternalID>CP2002</ContactPersonInternalID>
<CommunicationStatusCode>1</CommunicationStatusCode>
<CampaignExecutionCommunicationChannelTypeCode>INT</CampaignExecutionCommunicationChannelTypeCode>
</Outbound>
<Outbound>
<ObjectNodeSenderTechnicalID>1002</ObjectNodeSenderTechnicalID>
<CustomerInternalID>A2010</CustomerInternalID>
<ContactPersonInternalID>CP2012</ContactPersonInternalID>
<CommunicationStatusCode>2</CommunicationStatusCode>
<CampaignExecutionCommunicationChannelTypeCode>INT</CampaignExecutionCommunicationChannelTypeCode>
</Outbound>
<Outbound>
<ObjectNodeSenderTechnicalID>1003</ObjectNodeSenderTechnicalID>
<CustomerInternalID>A2020</CustomerInternalID>
<ContactPersonInternalID>CP2022</ContactPersonInternalID>
<CommunicationStatusCode>2</CommunicationStatusCode>
<CampaignExecutionCommunicationChannelTypeCode>INT</CampaignExecutionCommunicationChannelTypeCode>
</Outbound>
</Campaign>
</n0:CampaignOutboundBundleMaintainRequest_sync>
Response:
<nm:CampaignOutboundBundleMaintainConfirmation_sync xmlns:nm="http://sap.com/xi/SAPGlobal20/Global">
<Campaign>
<ChangeStateID>20120524092946.0950140</ChangeStateID>
<ReferenceObjectNodeSenderTechnicalID> </ReferenceObjectNodeSenderTechnicalID>
<UUID>00163e02-8b30-1ed1-a9b0-5fcd149ccb2e</UUID>
<ID>1112</ID>
</Campaign>
<Log/>
</nm:CampaignOutboundBundleMaintainConfirmation_sync>
| Description | Maintain campaign outbounds |
| Name | MaintainBundle |
| Synchronous | yes |
| Release Status | Deprecated |
To create, update or delete one or more campaign outbound data using imported structured data.
The MaintainBundle operation is used to create, update or delete one or more instances of marketing campaign outbounds whereas the CheckMaintainBundle operation is used to check if one or more marketing campaign outbounds could be maintained.
The request message of the operation MaintainBundle contains a BasicMessageHeader node element, as well as a Campaign node element containing the marketing campaign outbound data to be created, updated or deleted.
The detailed structure of the campaign node will be explained in the following sub-chapters. The campaign node can occur multiple times in the request message, meaning that outbound data for multiple marketing campaigns be created, updated or deleted by a single web service call.
The response message of the operation MaintainBundle contains log items, processing information, and a marketing campaign-specific node with ReferenceObjectNodeSenderTechnicalID, ChangeStateID, as well as marketing campaign ID and marketing campaign UUID (Note: Identifiers of marketing campaigns not of marketing campaign outbounds).
Both operations MaintainBundle and CheckMaintainBundle are allowed for one of the marketing campaign execution type codes only:
| 1 | E-Mail using file export |
| 2 | Fax using file export |
| 3 | Letter using file export |
| 4 | Phone Call using file export |
| 7 | External Execution |
The Campaign message node consists of two elements needed to identify existing marketing campaigns.
ID: Identifier of a marketing campaign in the actual system
ReferenceID: Identifier for a unique reference to a marketing campaign in an external system.
Either ID or ReferenceID has to be used for specifying a marketing campaign which shall be updated.
Only the value 06 (No Action) is allowed for action codes. If the external application do not pass the action code 06 it will be defaulted.
The Outbound message node contains information about the customer and contact persons addressed by the marketing campaign and their communication status.
CustomerUUID, CustomerInternalID: Identifier of a customer; specify either the customer UUID or the customer internal ID
ContactPersonUUID, ContactPersonInternalID: Identifier of a contact person; specify either the contact person UUID or the contact person internal ID.
CreationDateTime: Original outbound creation time stamp, the input of the creation date time is a time stamp (time zone UTC) in the format CCYY-MM-DDThh:mm:ss(.sss)Z
LastChangeDateTime: Time stamp when the campaign was last changed. The input of the last change date time is a time stamp (time zone UTC) in the format CCYY-MM-DDThh:mm:ss(.sss)Z
CommunicationStatusCode: Code for a communication status
CommunicationFailureReasonCode: Code to specify the reason for the failure of the communication (if communication status is Communication Failed). A reason for a failed communication might be a wrong e-mail address. It should be used for errors appearing during the execution of matketing campaigns only. Whenever errors occur after execution of markting campaigns one of the specialized operation MaintainFailedDeliveryStatusBundle or CheckMaintainFailedDeliveryStatusBundle of the service interface ManageCampaignInboundIn should be used for processing marketing campaign failed delivery status data (bounces).
CampaignExecutionCommunicationChannelTypeCode: A coded representation of the type of a communication channel that is used to contact a customer or a contact person of a customer during the campaign execution.
actionCode: All action codes are supported
Few elements are mandatory for the identification of marketing campaigns outbound instances. Please specify one of the customer and contact person identifiers. Valid elements for identification of marketing campaign outbound instances are:
One of the customer identifiers (UUID or InternalID) and one of the contact person identifiers (UUID or InternalID) or
One of the customer identifiers (UUID or InternalID) in case the outbound instance does not have a contact person
Code lists
Codes for the CommunicationStatusCode
| Type Code | Description |
|---|---|
| 1 | Not Yet Communicated |
| 2 | Communicated Successfully |
| 3 | Communication Failed |
| 4 | Not Relevant |
Codes for the CommunicationFailureReasonCode when the CommunicationStatusCode is Communication Failed.
| Type Code | Description | Use in this interface |
|---|---|---|
| 1 | Account Not Active | Yes |
| 2 | Contact Not Active | Yes |
| 3 | Contacting Member Not Permitted | Yes |
| 4 | E-mail Address Missing | Yes |
| 5 | Fax Number Missing | Yes |
| 6 | Letter Address Incomplete | Yes |
| 7 | Fax Number Invalid | Yes |
| 8 | E-mail Address Invalid | Yes |
| 9 | Account Does Not Exist | Yes |
| 10 | Contact Does Not Exist | Yes |
| 11 | Contact for Account Incorrect | Yes |
| 12 | Technical Problems | Yes |
| 13 | Phone Number Missing | Yes |
| 14 | Phone Number Invalid | Yes |
| 15 | Bounce: E-mail Address Invalid | Not relevant |
| 16 | E-mail Consent Withdrawn | Not relevant |
| 17 | Bounce: Mailbox Error | Not relevant |
| 18 | Bounce: Other undefined Error | Not relevant |
Codes for the CampaignExecutionCommunicationChannelTypeCode
| Type Code | Description |
|---|---|
| FAX | Fax |
| INT | |
| LET | Letter |
| SMS | SMS |
| TEL | Telephone |
| VIS | Visit |
Example for the creation of marketing campaign outbounds
<n0:CampaignOutboundBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
<BasicMessageHeader>
<ID>00163E01277C1EE186B9834511A002AB</ID>
</BasicMessageHeader>
<Campaign>
<ObjectNodeSenderTechnicalID>1000</ObjectNodeSenderTechnicalID>
<ID>960</ID>
<Outbound>
<ObjectNodeSenderTechnicalID>1001</ObjectNodeSenderTechnicalID>
<CreationDateTime>2012-08-23T12:00:00.0019050Z</CreationDateTime>
<CustomerUUID>00300571-CE9B-1DED-89DF-29DCE9BE1CAB</CustomerUUID>
<ContactPersonUUID>00300571-CE9B-1DDD-89DD-FEB454B21BDF</ContactPersonUUID>
<CommunicationStatusCode>2</CommunicationStatusCode>
</Outbound>
<Outbound>
<ObjectNodeSenderTechnicalID>1002</ObjectNodeSenderTechnicalID>
<CreationDateTime>2012-08-23T12:00:00.0019050Z</CreationDateTime>
<CustomerInternalID>MC9794</CustomerInternalID>
<ContactPersonInternalID>MCP9794</ContactPersonInternalID>
<!-- Defaulting of the Communication Status Code -->
</Outbound>
<Outbound actionCode="01">
<ObjectNodeSenderTechnicalID>1003</ObjectNodeSenderTechnicalID>
<CustomerUUID>00000000-0001-02DC-AED2-5ED1A0AD80A0</CustomerUUID>
<ContactPersonInternalID>CP2000_1</ContactPersonInternalID>
<CommunicationStatusCode>1</CommunicationStatusCode>
</Outbound>
<Outbound actionCode="01">
<ObjectNodeSenderTechnicalID>1004</ObjectNodeSenderTechnicalID>
<CustomerInternalID>AXUS-C132</CustomerInternalID>
<ContactPersonUUID>00300571-C924-02DB-B8C5-73444EA1C21E</ContactPersonUUID>
<CommunicationStatusCode>3</CommunicationStatusCode>
<CommunicationFailureReasonCode>3</CommunicationFailureReasonCode> <!-- Contacting Member Not Permitted -->
</Outbound>
<Outbound actionCode="01">
<ObjectNodeSenderTechnicalID>1005</ObjectNodeSenderTechnicalID>
<CustomerInternalID>MC13803</CustomerInternalID>
<CommunicationStatusCode>2</CommunicationStatusCode>
</Outbound>
</Campaign>
</n0:CampaignOutboundBundleMaintainRequest_sync>
The corresponding response in case the campaign outbounds has been created successfully:
<nm:CampaignOutboundBundleMaintainConfirmation_sync xmlns:nm="http://sap.com/xi/SAPGlobal20/Global">
<Campaign>
<ChangeStateID>20120712151832.0667510</ChangeStateID>
<ReferenceObjectNodeSenderTechnicalID>1000</ReferenceObjectNodeSenderTechnicalID>
<UUID>00163e02-8b2e-1ee1-b386-9acee7cc326f</UUID>
<ID>960</ID>
</Campaign>
<Log/>
</nm:CampaignOutboundBundleMaintainConfirmation_sync>
Example for deletion of an outbound instance
<n0:CampaignOutboundBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
<BasicMessageHeader>
<ID>00163E028B341ED1BB9F9748EDB6E40C</ID>
</BasicMessageHeader>
<Campaign>
<ObjectNodeSenderTechnicalID>1000</ObjectNodeSenderTechnicalID>
<ID>960</ID>
<Outbound actionCode ="03">
<ObjectNodeSenderTechnicalID>1001</ObjectNodeSenderTechnicalID>
<CustomerInternalID>MC9794</CustomerInternalID>
<ContactPersonInternalID>MCP9794</ContactPersonInternalID>
</Outbound>
</Campaign>
</n0:CampaignOutboundBundleMaintainRequest_sync>
| Description | Check campaign outbounds |
| Name | CheckMaintainBundle |
| Synchronous | yes |
| Release Status | Deprecated |
To check whether one or more campaign outbounds can be created, updated or deleted without errors using imported structured data.
The web service request and response message types of the CheckMaintainBundle operation are the same as those of the MaintainBundle operation.
The explanations given can therefore also be applied to the CheckMaintainBundle operation.
Check the creation of new campaign outbounds based on campaigns executed in an external system.
<n0:CampaignOutboundRequestBundleCheckMaintainQuery_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
<BasicMessageHeader>
<ID>00163E01277C1EE186B9834511A002AB</ID>
</BasicMessageHeader>
<Campaign>
<ID>942</ID>
<Outbound actionCode="01">
<ObjectNodeSenderTechnicalID>1001</ObjectNodeSenderTechnicalID>
<CustomerUUID>00300571-CE9B-1DED-89DF-29DCE9BE1CAB</CustomerUUID>
<ContactPersonUUID>00300571-CE9B-1DDD-89DD-FEB454B21BDF</ContactPersonUUID>
<CommunicationStatusCode>2</CommunicationStatusCode>
</Outbound>
<Outbound actionCode="01">
<ObjectNodeSenderTechnicalID>1002</ObjectNodeSenderTechnicalID>
<CustomerInternalID>MC9794</CustomerInternalID>
<ContactPersonInternalID>MCP9794</ContactPersonInternalID>
<CommunicationStatusCode>2</CommunicationStatusCode>
</Outbound>
</Campaign>
<Campaign>
<ID>938</ID>
<Outbound>
<ObjectNodeSenderTechnicalID>2001</ObjectNodeSenderTechnicalID>
<CustomerInternalID>XYZ9794</CustomerInternalID> <!-- Invalid identfiers -->
<ContactPersonInternalID>XYZ9794</ContactPersonInternalID>
<CommunicationStatusCode>2</CommunicationStatusCode>
</Outbound>
<Outbound>
<ObjectNodeSenderTechnicalID>2009</ObjectNodeSenderTechnicalID>
<CustomerInternalID>AXUS-C132</CustomerInternalID>
<ContactPersonUUID>00300571-C924-02DB-B8C5-73444EA1C21E</ContactPersonUUID>
<CommunicationStatusCode>2</CommunicationStatusCode>
</Outbound>
<Outbound>
<ObjectNodeSenderTechnicalID>1010</ObjectNodeSenderTechnicalID>
<CustomerInternalID>MC13803</CustomerInternalID>
<CommunicationStatusCode>2</CommunicationStatusCode>
</Outbound>
</Campaign>
</n0:CampaignOutboundRequestBundleCheckMaintainQuery_sync>
The corresponding response in case the check for creation of campaign outbounds failed:
<nm:CampaignOutboundRequestBundleCheckMaintainResponse_sync xmlns:nm="http://sap.com/xi/SAPGlobal20/Global" xmlns:prx="urn:sap.com:proxy:ALP:/1SAI/TAE945629D0C6E54C1F7811:804"> <Log> <MaximumLogItemSeverityCode>3</MaximumLogItemSeverityCode> <Item> <TypeID>001(/CM_A2X_MNG_CMPG_OUTB/)</TypeID> <CategoryCode>SEI.SCV</CategoryCode> <SeverityCode>3</SeverityCode> <ReferenceObjectNodeSenderTechnicalID> 2001</ReferenceObjectNodeSenderTechnicalID> <Note>Account XYZ9794 does not exist</Note> </Item> <Item> <TypeID>002(/CM_A2X_MNG_CMPG_OUTB/)</TypeID> <CategoryCode>SEI.SCV</CategoryCode> <SeverityCode>3</SeverityCode> <ReferenceObjectNodeSenderTechnicalID> 2001</ReferenceObjectNodeSenderTechnicalID> <Note>Contact person XYZ9794 does not exist</Note> </Item> <Item> <TypeID>040(/MBF_A2X_CORE/)</TypeID> <CategoryCode>BPR.PUR</CategoryCode> <SeverityCode>3</SeverityCode> <ReferenceObjectNodeSenderTechnicalID>2001</ReferenceObjectNodeSenderTechnicalID> <Note>Only list complete transmission (LCTI) allowed for segment CAMPAIGN-OUTBOUND</Note> </Item> </Log> </nm:CampaignOutboundRequestBundleCheckMaintainResponse_sync>