| Description | Manage Target Groups |
| Name | ManageTargetGroupIn |
| 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 target groupss from a source system or file to a target system.
This web-service is used to create, modify and delete existing target groups.
It has the MaintainBundle and CheckMaintainBundle operations. The MaintainBundle is used to update one or more instances of the Target Group business object. The CheckMaintainBundle is used to check if the one or more instances of the Target Group business object can be maintained.
This example structure shows the possible elements and attributes:
<n0:TargetGroupBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <TargetGroup actionCode="1" memberListCompleteTransmissionIndicator="true"> <ObjectNodeSenderTechnicalID>Token 14</ObjectNodeSenderTechnicalID> <ChangeStateID>Token 15</ChangeStateID> <UUID>12345678-90AB-CDEF-0123-456789ABCDEF</UUID> <ID>121</ID> <Description>A description</Description> <LifeCycleStatusCode>1</LifeCycleStatusCode> <Note actionCode="1"> <ObjectNodeSenderTechnicalID>Token 24</ObjectNodeSenderTechnicalID> <ContentText>A note</ContentText> </Note> <Member actionCode="1"> <ObjectNodeSenderTechnicalID>Token 27</ObjectNodeSenderTechnicalID> <UUID>12345678-90AB-CDEF-0123-456789ABCDEF</UUID> <CustomerUUID>12345678-90AB-CDEF-0123-456789ABCDEF</CustomerUUID> <CustomerInternalID>Token 32</CustomerInternalID> <ContactPersonUUID>12345678-90AB-CDEF-0123-456789ABCDEF</ContactPersonUUID> <ContactPersonInternalID>Token 35</ContactPersonInternalID> </Member> </TargetGroup> </n0:TargetGroupBundleMaintainRequest_sync>
Customer and contact person master data are referenced by target group members. However, they cannot be created by these service operations. They must exist in the system already at the time the service is called.
Action codes represent an instruction to the recipient of the web service request how to process transmitted message node elements. It is modeled as an attribute (Attribute name: actionCode) in every structure element 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. |
The ActionCodes "01" (Create), "02" (Change), "03" (Delete), and "06" (No Action) model strict semantics that lead to errors at the recipient if the elements corresponding to the actions requested by the sender exist ("01") or do not exist ("02", "03", "06") at the recipient. Using strict semantics, therefore, requires that the sender has and uses information about the messages it has already sent.
The ActionCodes "04" (Save) and "05" (Remove) model soft semantics that do not lead to errors if the respective elements do not exist at the recipient. These soft semantics, therefore, do not require that the sender has and uses information about the messages it has already sent.
Note: If no ActionCode is provided for a respective node, the system defaults it with value ‘04’.
Request node elements with cardinality > 1 contain an 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 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 for only 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, but returns them to the web service consumer instead in the "ReferenceObjectNodeSenderTechnicalID" elements.
Using 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 read its data.
The change state ID is a not interpretable 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 service consumer, the system performs the service operation without checking the state of the business document.
The service consumer (external application) is responsible for preventing accidental changes to business documents.
The processing of node elements with cardinality > 1 can be controlled using List Complete Transmission Indicators (LCTI). The LCTI indicates whether a list of node elements is transmitted completely. The LCTI of a node element with cardinality > 1 is modeled as an attribute of its parent node element (attribute name: <name of child element>ListCompleteTransmissionIndicator).
False (default value): The list of node elements is not transmitted completely and hence all node elements that are not transmitted remain unchanged. If transmitted node elements in the list can be identified uniquely, the system processes the node elements according to the action code. If transmitted node elements in the list cannot be identified uniquely, the system appends the node element to the corresponding list of node elements in the target business document.
True: The list of elements is transmitted completely and hence all node elements that are not transmitted are removed. If no node element is transmitted, the complete list is removed.
Example: The Target Group node has a memberListCompleteTransmissionIndicator. If a target group has already 100 members in the system and the consumer wants to add two additional ones s/he should pass these two new members with ActionCode 01 in the message payload and should set the memberLCTI to false. Then the two members are added and the already existing 100 members are kept. If the consumer wants to remove all members except those two just added s/he should again pass these two members but should set the memberLCTI to true. Then all members are removed which are not contained in the message payload.
Optional elements in request messages that are not transmitted within a service request are not changed in corresponding business objects.
Example(1): Description is set to initial:
<TargetGroup actionCode="02"> <ID>431</ID> <Description></Description> <LifeCycleStatusCode>3</LifeCycleStatusCode> </TargetGroup>
Example(2): Description is not changed:
<TargetGroup actionCode="02"> <ID>431</ID> <LifeCycleStatusCode>3</LifeCycleStatusCode> </TargetGroup>
Generally target groups with status "obsolete" cannot be changed. They can only be deleted or set to a status which allows further changes such as, "active" or "blocked".
This restriction applies to the maintenance of target groups using this web service as well:
It is not possible to set a target troup to "obsolete" and to submit further changes, for example, maintenance of root or member data, in one step. First the maintenance operations should be submitted; in a second service call the target group can be set to "obsolete".
It is not possible to set back a target group from "obsolete" and to submit further changes, for example, maintenance of root or member data, in one step. First the target group status should be set to a value different than "obsolete"; in a second service call the maintenance operations can be submitted.
You can find general information about Web services, their structure and consumption in the Web Services documentation.
In this example scenario the consumer wants to create a target group and a campaign using this target group.
First the target group needs to be created using this service. The target group ID delivered in the response is then used to create a campaign using the service “Manage Campaign In”.
Step1: Create a target group with 2 members
Request:
<n0:TargetGroupBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>00300571D06B1DED9EE4723F124207BC</ID> </BasicMessageHeader> <TargetGroup actionCode="01"> <Description>Description of TG</Description> <Member actionCode="01"> <CustomerInternalID>MC9785</CustomerInternalID> <ContactPersonInternalID>MCP9785</ContactPersonInternalID> </Member> <Member actionCode="01"> <CustomerInternalID>MC9786</CustomerInternalID> <ContactPersonInternalID>MCP9786</ContactPersonInternalID> </Member> </TargetGroup> </n0:TargetGroupBundleMaintainRequest_sync>
Response:
<nm:TargetGroupBundleMaintainConfirmation_sync xmlns:nm="http://sap.com/xi/SAPGlobal20/Global" xmlns:prx="urn:sap.com:proxy:ALP:/1SAI/TAS220EB8A27B8B07382875:804"> <TargetGroup> <ReferenceObjectNodeSenderTechnicalID /> <ChangeStateID>20120627145254.4922380</ChangeStateID> <UUID>00163e02-8b2e-1ed1-b08c-f7f96602c11b</UUID> <ID>443</ID> </TargetGroup> <Log /> </nm:TargetGroupBundleMaintainConfirmation_sync>
Step2: Create a campaign using the new target group
Request:
Show full documentation
Show full documentation
<n0:CampaignBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
<BasicMessageHeader>
</BasicMessageHeader>
<Campaign>
<Description>A2X Manage Bundle In 2012/06/13</Description>
<PlannedStartDate>2012-06-13</PlannedStartDate>
<PlannedEndDate>2012-07-27</PlannedEndDate>
<LifeCycleStatusCode>1</LifeCycleStatusCode>
<ExecutionStep>
<TargetGroupID>443</TargetGroupID>
<ExecutionTypeCode>1</ExecutionTypeCode>
</ExecutionStep>
</Campaign>
</n0:CampaignBundleMaintainRequest_sync>
Response:
<nm:CampaignBundleMaintainConfirmation_sync xmlns:nm="http://sap.com/xi/SAPGlobal20/Global" xmlns:prx="urn:sap.com:proxy:ALP:/1SAI/TAE6FD14FD49A2246F547C3:804"> <Campaign> <ChangeStateID>20120627074556.5579770</ChangeStateID> <ReferenceObjectNodeSenderTechnicalID /> <UUID>00163e02-8b34-1ee1-afed-037b699d9b3d </UUID> <ID>711</ID> </Campaign> <Log /> </nm:CampaignBundleMaintainConfirmation_sync>
| Description | Manage target groups |
| Name | MaintainBundle |
| Synchronous | yes |
| Release Status | Deprecated |
To create, update or delete one or more target groups using imported structured data.
The request message of the operation MaintainBundle contains a BasicMessageHeader node element as well as a target group node element that contains the data to be maintained. The detailed structure of the node will be explained in the following sub-chapters. The node can occur multiple times in the request message – this means that multiple target groups can be maintained through a single web service request.
This is the root node for each data being passed in the request. The following are the attributes and elements of this node:
| Attributes | Description |
|---|---|
| actionCode | Refer „General Rules‟ section for more details. |
| memberListCompleteTransmissionIndicator | Refer „General Rules‟ section for more details. |
| Elements | Description |
|---|---|
| ObjectNodeSenderTechnicalID | Refer „General Rules‟ section for more details. |
| ChangeStateID | Refer „General Rules‟ section for more details. |
| UUID | To identify a target group for modification |
| ID | To identify a target group for modification |
| Description | |
| LifeCycleStatusCode | Status |
| <Root Extension Fields> | If configured by the key user root extension fields can be maintained by the service |
Code vales for LifeCycleStatusCode:
| Code value | Description |
|---|---|
| 1 | active |
| 2 | blocked |
| 3 | obsolete |
To update or delete target groups they can either be identified by the UUID or the ID element.
Only target groups with status obsolete can be deleted.
Example (1): Create a target group
Request:
<n0:TargetGroupBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>00300571D06B1DED9EE4723F124207BC</ID> </BasicMessageHeader> <TargetGroup actionCode="01"> <Description>Description of TG</Description> <LifeCycleStatusCode>1</LifeCycleStatusCode> </TargetGroup> </n0:TargetGroupBundleMaintainRequest_sync>
Example (2): Update a target group
Request:
<n0:TargetGroupBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>00300571D06B1DED9EE4723F124207BC</ID> </BasicMessageHeader> <TargetGroup actionCode="02"> <ID>431</ID> <Description>updated: Description</Description> <LifeCycleStatusCode>3</LifeCycleStatusCode> </TargetGroup> </n0:TargetGroupBundleMaintainRequest_sync>
The node element note contains mainly the text of a note for a target group
| Attributes | Description |
|---|---|
| actionCode | Refer „General Rules‟ section for more details. |
| Elements | Description |
|---|---|
| ObjectNodeSenderTechnicalID | Refer „General Rules‟ section for more details. |
| ContentText | Text |
The Target Group business object supports only one note instance. If an additional note is transmitted by the consumer for creation the system updates the already existing note with the provided text. Using the ActionCode it is possible to delete the note instance. Empty notes cannot be created. If empty note content is provided the system removes the whole note instance (ActionCodes 02 and 04) or ignors the creation of it (ActionCode 01).
Example (1): Create a note for an already existing target group
Request:
<n0:TargetGroupBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>00300571D06B1DED9EE4723F124207BC</ID> </BasicMessageHeader> <TargetGroup actionCode="06"> <ID>431</ID> <Note actionCode="01"> <ContentText>This is a note.</ContentText> </Note> </TargetGroup> </n0:TargetGroupBundleMaintainRequest_sync>
Example (2): Delete a note
Request:
<n0:TargetGroupBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>00300571D06B1DED9EE4723F124207BC</ID> </BasicMessageHeader> <TargetGroup actionCode="06"> <ID>434</ID> <Note actionCode="03"> </Note> </TargetGroup> </n0:TargetGroupBundleMaintainRequest_sync>
Using this node element members can be added to or removed from a target group.
| Attributes | Description |
|---|---|
| actionCode | Refer „General Rules‟ section for more details. |
| Elements | Description |
|---|---|
| ObjectNodeSenderTechnicalID | Refer „General Rules‟ section for more details. |
| UUID | To identify a member for deletion |
| CustomerUUID | To identify the customer to be added |
| CustomerInternalID | To identify the customer to be added |
| ContactPersonUUID | To identify the contact person to be added |
| ContactPersonInternalID | To identify the contact person to be added |
| <Member Extension Fields> | If configured by the key user member extension fields can be maintained by the service |
Customer and contact person serve as logical key for a target group member. They cannot be updated. If a consumer wants to update a member, for example, replace the contact person, the member instance needs to be deleted and a new one needs to be created. The consumer will receive a corresponding error in the log section of the response if s/he transfers customer or contact person data with action code 02.
To add a member to a target group a customer needs to be specified. It’s possible to pass either the CustomerUUID or the CustomerID. In addition a contact person can be specified. Here also passing the UUID or the ID is possible.
When members are added an implicit check on duplicates is done. Warnings are put into the log section of the response if a customer – contact person – combination shall be added which is already available in the specified target group.
Member extension fields can only be passed in change mode (action code 02). When passed in create mode (action codes 01 and 04) appropriate error messages are raised.
To delete target group members they must be identified by the member UUID. The member UUIDs can be obtained using the Target Group Query Service
Example (1): Add members to a target group
Request:
<n0:TargetGroupBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>00300571D06B1DED9EE4723F124207BC</ID> </BasicMessageHeader> <TargetGroup actionCode="04"> <ID>431</ID> <Member actionCode="01"> <CustomerInternalID>MC9785</CustomerInternalID> <ContactPersonInternalID>MCP9785</ContactPersonInternalID> </Member> <Member actionCode="01"> <CustomerInternalID>MC9786</CustomerInternalID> <ContactPersonInternalID>MCP9786</ContactPersonInternalID> </Member> </TargetGroup> </n0:TargetGroupBundleMaintainRequest_sync>
Example (2): Delete all members from a target group and add new members (using LCTI)
Request:
<n0:TargetGroupBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>00300571D06B1DED9EE4723F124207BC</ID> </BasicMessageHeader> <TargetGroup actionCode="04" memberListCompleteTransmissionIndicator="true"> <ID>431</ID> <Member actionCode="01"> <CustomerInternalID>MC9785</CustomerInternalID> <ContactPersonInternalID>MCP9785</ContactPersonInternalID> </Member> <Member actionCode="01"> <CustomerInternalID>MC9786</CustomerInternalID> <ContactPersonInternalID>MCP9786</ContactPersonInternalID> </Member> </TargetGroup> </n0:TargetGroupBundleMaintainRequest_sync>
Example (3): Delete members from a target group
Request:
<n0:TargetGroupBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>00300571D06B1DED9EE4723F124207BC</ID> </BasicMessageHeader> <TargetGroup actionCode="06"> <ID>431</ID> <Member actionCode="03"> <UUID>00163E02-8B2E-1EE1-B084-C9B56C75CEFC</UUID> </Member> <Member actionCode="03"> <UUID>00163E02-8B2E-1EE1-B084-C9B56C75EEFC</UUID> </Member> </TargetGroup> </n0:TargetGroupBundleMaintainRequest_sync>
Example (4): Update extension field of a target group member
Request:
<n0:TargetGroupBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>00300571D06B1DED9EE4723F124207BC</ID> </BasicMessageHeader> <TargetGroup actionCode="06"> <ID>431</ID> <Member actionCode="02"> <UUID>00163E02-8B2E-1EE1-B084-C9B56C75CEFC</UUID> <n1:test_ext xmlns:n1="http://sap.com/xi/AP/CustomerExtension/BYD/ZZZZZ">weddccwe</n1:test_ext> </Member> </TargetGroup> </n0:TargetGroupBundleMaintainRequest_sync>
The structure consists of two parts:
Information about IDs and UUIDs of the created, changed or deleted target groups
Log items containing system messages including errors, warnings, and information messages raised by the system during processing of the service request. The severity code specifies whether the message is of type error (3), warning (2) or information (1).
Example (1): Creating a target group
Response:
<nm:TargetGroupBundleMaintainConfirmation_sync xmlns:nm="http://sap.com/xi/SAPGlobal20/Global" xmlns:prx="urn:sap.com:proxy:ALP:/1SAI/TAS220EB8A27B8B07382875:804"> <TargetGroup> <ReferenceObjectNodeSenderTechnicalID>Token 14</ReferenceObjectNodeSenderTechnicalID> <ChangeStateID>20120627084217.8722850</ChangeStateID> <UUID>00163e02-8b2e-1ee1-b086-7fd3dd4012df</UUID> <ID>442</ID> </TargetGroup> <Log /> </nm:TargetGroupBundleMaintainConfirmation_sync>
Example (2): Adding already existing members to a target group
Response:
<nm:TargetGroupBundleMaintainConfirmation_sync xmlns:nm="http://sap.com/xi/SAPGlobal20/Global" xmlns:prx="urn:sap.com:proxy:ALP:/1SAI/TAS220EB8A27B8B07382875:804"> <Log> <MaximumLogItemSeverityCode>2</MaximumLogItemSeverityCode> <Item> <TypeID>112(/CL_APCRM_TG_OB/)</TypeID> <CategoryCode>INC.BOI</CategoryCode> <SeverityCode>2</SeverityCode> <Note>Adding 2 members not possible; they already exist in target group</Note> </Item> </Log> </nm:TargetGroupBundleMaintainConfirmation_sync>
Example (3): Deleting a non obsolete target group
Response:
<nm:TargetGroupBundleMaintainConfirmation_sync xmlns:nm="http://sap.com/xi/SAPGlobal20/Global" xmlns:prx="urn:sap.com:proxy:ALP:/1SAI/TAS220EB8A27B8B07382875:804"> - <Log> <MaximumLogItemSeverityCode>3</MaximumLogItemSeverityCode> <Item> <TypeID>108(/AP_ESI_COMMON/)</TypeID> <CategoryCode>INC.BOI</CategoryCode> <SeverityCode>3</SeverityCode> <ReferenceObjectNodeSenderTechnicalID>Token 14</ReferenceObjectNodeSenderTechnicalID> <Note>Deleting data not possible; deletion disabled</Note> </Item> </Log> </nm:TargetGroupBundleMaintainConfirmation_sync>
| Description | Check target groups |
| Name | CheckMaintainBundle |
| Synchronous | yes |
| Release Status | Deprecated |
To check whether one or more Target Groups can be maintained using imported structured data.
The web service request- and response message types for the CheckMaintainBundle operation are the same as those of the Maintain Bundle operation. The explanations given can therefore also be applied to the CheckMaintainBundle operation.