| Description | Manage Sales Leads |
| Name | ManageLeadIn |
| Namespace | http://sap.com/xi/A1S/Global |
| Process Component Description | Lead Processing |
| Process Component Name | LeadProcessing |
| 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 migrate sales lead data from a source system or file.
The web service interface Manage Sales Lead In enables you to connect external applications to your SAP system and to create and edit sales leads in your system. The web service interface Manage Sales Lead In is relevant if your company wants to access and manage sales lead data from external applications.
The web service interface Manage Lead In offers the operations MaintainBundle and CheckMaintainBundle.
Here is an example of a simple web service request:
Show full documentation
Show full documentation
<n0:LeadBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
<BasicMessageHeader>
<ID>00000000000102dcade9bcb0ab000c99</ID>
</BasicMessageHeader>
<Lead actionCode="01">
<Name>A2X Create Lead with Parties, Text etc.</Name>
<QualificationLevelCode>01</QualificationLevelCode>
<StartDate>2012-05-01</StartDate>
<EndDate>2012-12-01</EndDate>
<GroupCode>0023</GroupCode>
<OriginTypeCode>004</OriginTypeCode>
<Note actionCode="01">
<ContentText>A2X Example for text</ContentText>
</Note>
<Item actionCode="01">
<ID>10</ID>
<Description languageCode="EN">A2X Example for item</Description>
<QuantityValue unitCode="ea">1</QuantityValue>
</Item>
<MarketingResponsibleEmployeeParty>
<BusinessPartnerInternalID>MC3719</BusinessPartnerInternalID>
</MarketingResponsibleEmployeeParty>
<SalesResponsibleEmployeeParty>
<BusinessPartnerInternalID>MC2471</BusinessPartnerInternalID>
</SalesResponsibleEmployeeParty>
<ProspectParty>
<BusinessPartnerInternalID>MC9785</BusinessPartnerInternalID>
</ProspectParty>
</Lead>
</n0:LeadBundleMaintainRequest_sync>
Existence of referenced business data:
The following business data are only referenced and will not be created by the service operations. They must exist in the system already at the time the web service is called:
Business partners and related projections like prospects, employees, etc.
Products, Materials, Services
Campaigns
Maintain Bundle operations enable external applications to create and change business document data. Check Maintain Bundle operations enable external applications to simulate maintain bundle requests without changing business document data. In particular, Check Maintain Bundle operations have the following functions:
Return system messages similar to corresponding maintain bundle operations
Provide the same message type as the corresponding operation Maintain Bundle
Do not assign internal numbers from a productive number range interval (number range statuses are not increased)
Do not change business documents
Action codes represent an instruction to the recipient of the web service request to process transmitted message node elements.
| 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 to avoid accidental creation of duplicate business documents.
The processing of node elements with cardinality > 1 (for example a list of parties with a certain party role) 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).
| LCTI | Description |
|---|---|
| false | 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 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. |
Default list complete transmission indicator: false.
Note: The LCTI refers to the completeness of the list of node elements and does not state completeness of sub-elements.
Optional leaf elements in request messages that are not transmitted within a web service request are not changed in corresponding business documents.
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 of data 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 has to provide unique values for the elements ID or UUID of the BasicMessageHeader node element.
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 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 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.
Note: The ObjectNodeSenderTechnicalID is also used to identify failed business document modifications in a mass operation.
Example
Request:
<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.
Possible scenarios include the following:
Create Sales Lead
The MaintainBundle operation is used to create sales leads.
Update Sales Lead
The MaintainBundle operation is used to update sales leads.
Example web service request to create a sales lead:
<n0:LeadBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
<BasicMessageHeader>
<ID>00000000000102dcade9bcb0aa001a64</ID>
</BasicMessageHeader>
<Lead actionCode="01" itemListCompleteTransmissionIndicator="true">
<ObjectNodeSenderTechnicalID></ObjectNodeSenderTechnicalID>
<ChangeStateID></ChangeStateID>
<UUID></UUID>
<ID></ID>
<Name>A2X Create Lead</Name>
<QualificationLevelCode></QualificationLevelCode>
<StartDate>2012-06-25</StartDate>
<EndDate>2012-07-25</EndDate>
<LifeCycleStatusCode></LifeCycleStatusCode>
<StatusValidSinceDate></StatusValidSinceDate>
<GroupCode></GroupCode>
<OriginTypeCode>004</OriginTypeCode>
<ResultReasonCode></ResultReasonCode>
<CampaignPredecessorReferenceID></CampaignPredecessorReferenceID>
<Note actionCode="01">
<ObjectNodeSenderTechnicalID></ObjectNodeSenderTechnicalID>
<ContentText>A2X Example for Lead note</ContentText>
</Note>
<Item actionCode="01">
<ObjectNodeSenderTechnicalID></ObjectNodeSenderTechnicalID>
<UUID></UUID>
<ID>10</ID>
<Description languageCode="EN">A2X Example for Lead item</Description>
<QuantityValue unitCode="ea">2</QuantityValue>
<ProductUUID></ProductUUID>
<MaterialInternalID>10000335</MaterialInternalID>
<ServiceProductInternalID></ServiceProductInternalID>
<ProductStandardID></ProductStandardID>
<ProductCategoryInternalID></ProductCategoryInternalID>
</Item>
<MarketingResponsibleEmployeeParty>
<BusinessPartnerInternalID>MC3719</BusinessPartnerInternalID>
</MarketingResponsibleEmployeeParty>
<SalesResponsibleEmployeeParty>
<BusinessPartnerInternalID>MC2471</BusinessPartnerInternalID>
</SalesResponsibleEmployeeParty>
<ProspectParty partyContactPartyListCompleteTransmissionIndicator="true" actionCode="04">
<BusinessPartnerInternalID>MC9785</BusinessPartnerInternalID>
<ContactParty actionCode="04">
<ObjectNodeSenderTechnicalID></ObjectNodeSenderTechnicalID>
<BusinessPartnerInternalID>MCP9785</BusinessPartnerInternalID>
<MainIndicator>true</MainIndicator>
</ContactParty>
</ProspectParty>
</Lead>
</n0:LeadBundleMaintainRequest_sync>
Example to update a sales lead:
<n0:LeadBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader> <ID>00000000000102dcade9bcb0aa001b86</ID> </BasicMessageHeader> <Lead actionCode="02"> <ObjectNodeSenderTechnicalID></ObjectNodeSenderTechnicalID> <ChangeStateID></ChangeStateID> <UUID></UUID> <ID>1139</ID> <Name>A2X Update Lead</Name> </Lead> </n0:LeadBundleMaintainRequest_sync>
| Description | Check leads |
| Name | CheckMaintainBundle |
| Synchronous | yes |
| Release Status | Deprecated |
To check if leads can be created, updated, or deleted without errors.
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.
| Description | Maintain leads |
| Name | MaintainBundle |
| Synchronous | yes |
| Release Status | Deprecated |
To create, update, or delete leads.
The request message of the operation MaintainBundle contains a BasicMessageHeader node element as well as a lead node element that contains the data to be created or updated. 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 leads can be created and updated through a single web service request.
The response message type of the operation MaintainBundle contains log items, processing information and a lead-specific node with ReferenceObjectNodeSenderTechnicalID, ChangeStateID, as well as ID and UUID.
The Lead node element contains all general lead information such as ID, UUID, name, qualification level code and other data.
The data for this node is related to general data on the Lead UI.
The UUID is a unique identifier of the lead. It will be generated by the web service.
The ID is a unique identifier of the lead. It is generated automatically by the system.
The name descibes a lead as it will be shown in the UI.
The QualificationLevelCode specifies a classification of the potential interest of a customer:
| Qualification level code | Description |
|---|---|
| 01 | Cold |
| 02 | Warm |
| 03 | Hot |
If a QualificationLevelCode is set, the LifeCycleStatusCode will automatically set to Qualified in backend.
If a QualificationLevelCode is not specified by the customer on creation or will be removed by the customer on update, the LifeCycleStatusCode will be set back to Open as long as the lead has not reached the status Accepted or Declined. Otherwise removing the QualificationLevelCode will lead to an error.
The attribute shows the start date of a lead. The date is the specification of an exact day in the Gregorian calendar.
If not specified by the consumer, a default value is set to the current date.
Example:
<StartDate>2012-05-25</StartDate>
The attribute shows the end date of a lead. The date is the specification of an exact day in the Gregorian calendar.
If not specified by the consumer, a default value is set according to the entry in the business configuration (default 30 days after start date).
Example <EndDate>2002-04-19</EndDate>
The attribute LifeCycleStatusCode indicates the status of a lead.
| LifeCycleStatusCode | Description |
|---|---|
| 1 | Open |
| 2 | Qualified |
| 4 | Accepted |
| 5 | Declined |
| 6 | Converted |
If not specified by the consumer, a default is set by the web service according to the specified lead attributes:
If the attribute QualificationLevelCode is specified, the web service sets the LifeCycleCode to Qualified.
The status Accepted can be set only if lead has a valid QualificationLevelCode, a valid SalesResponsibleEmployeeParty and a valid ProspectParty. If a new lead shall be created with status Accepect these attributes must be given. If an existing lead shall be updated with status Accepted the lead must have already these attributes filled or the must be given into the message of the web service.
It is not possible to set the status Accepted or Declined and to be set the ResultReasonCode in one call of the web service. It would fail with an error that the ResultReasonCode is not changeable.
The web service must be called two times:
1. set the status Accepted or Declined
2. set the ResultReasonCode
The attribute GroupCode specifies the assignment of a lead to a specific group.
The GroupCode can contain the following values, depending on business configuration settings:
| GroupCode | Description |
|---|---|
| 0023 | Prospect for Product Sales |
| 0024 | Prospect for Service |
| 0025 | Prospect for Training |
| 0026 | Prospect for Consulting |
If not specified by the consumer, a default is set by the web service.
The attribute OriginTypeCode indicates the origin of a lead.
The OriginTypeCode can contain the following values, depending on business configuration settings:
| OriginTypeCode | Description |
|---|---|
| 001 | Trade Fair |
| 002 | External Partner |
| 003 | Campaign |
| 004 | Telephone Inquiry |
| 005 | Roadshow |
If not specified by the consumer, a default is set by the web service.
The attribute ResultReasonCode specifies the reason of a current lead result.
The ResultReasonCode can contain the following values, depending on business configuration settings:
| ResultReasonCode | Description |
|---|---|
| 002 | Lost Due to Product |
| 003 | Lost Due to Price |
| 004 | Lost Due to Service |
| 005 | Won Due to Product |
| 006 | Won Due to Price |
| 007 | Won Due to Service |
| 008 | Accepted Because of High Revenue Potential |
| 009 | Accepted Because of High Chance of Success |
| 010 | Accepted for Strategic Reasons |
| 011 | Rejected Because of Low Revenue Potential |
| 012 | Rejected Because of Low Chance of Success |
| 013 | Rejected Because of Wrong Target Segment |
If not specified by the consumer, a default is set by the web service.
See also the explanations for the LifeCycleStatusCode
By the CampaignPredecessorReferenceID the lead can be referenced to a campaign that is the direct predecessor of the lead.
This node element allows to add text to a lead.
For every update (using action code 02 or 04) the existing entry will be replaced by the new text.
Example for creating a new note entry:
<Note actionCode="01"> <ContentText>A2X Example for Lead note</ContentText> </Note>
The AttachmentFolder node element can be used to add and remove lead attachments.
Data for this node can be found on the lead UI as attachments. On the user interface, files and links can be created. In the web service request, links and files are differentiated through the CategoryCode:
| Category code | Description |
|---|---|
| 2 | Document |
| 3 | Link |
The different types of attachments are differentiated by the TypeCode:
| Type code | Description |
|---|---|
| 10001 | Standard Attachment |
To create link attachments, document elements must be as follows:
<AttachmentFolder ActionCode="04">
<Document ActionCode="04">
<VisibleIndicator>true</VisibleIndicator>
<CategoryCode>3</CategoryCode>
<TypeCode>10001</TypeCode>
<Name>SAP AG Link</Name>
<ExternalLinkWebURI>http://www.sap.com</ExternalLinkWebURI>
<AlternativeName>SAP AG URL</AlternativeName>
<Description languageCode="EN">A hyperlink to SAP AG</Description>
</Document>
</AttachmentFolder>
To create file attachments, document elements must be as follows:
| Element | Value |
|---|---|
| VisibleIndicator | true |
| CategoryCode | 2 |
| TypeCode | <none> |
| Name | <Document Title> |
| AlternativeName | <Document Title> |
| Description | <Comment> |
The item node contains all information regarding products, product categories or just descriptions, the prospect of the lead is interested in.
Each item is defined by a combination of ID, Description, QuantityValue, a MaterialID, a ServiceProductID, a ProductStandardID and a ProductCategoryInternalID.
Example for creating a new item:
<Item actionCode="01"> <ID>10</ID> <Description languageCode="EN">A2X Example for Lead item</Description> <QuantityValue unitCode="ea">2</QuantityValue> <MaterialInternalID>10000335</MaterialInternalID> </Item>
When updating an item that already contains a MaterialID, a ServiceProductID or a ProductStandardID, it is important, not to provide the ProductCategoryInternalID, as it is not changeable anymore if the item already has a product ID.
If the ProductCategoryInternalID is provided while update and it differs from the original maintained ProductCategoryInternalID, an error message in the response will be provided that the product category ID cannot be changed as the field is read only.
The node element contains the identification for the party that is responsible on marketing side of the lead.
Either the business partner internal ID or the business partner UUID can be provided. The business partner UUID is used in case both identifiers are provided.
Example providing the business partner internal ID:
<MarketingResponsibleEmployeeParty> <BusinessPartnerInternalID>MC3719</BusinessPartnerInternalID> </MarketingResponsibleEmployeeParty>
The node element contains the identification for the party that is responsible on sales side for the lead.
Either the business partner internal ID or the business partner UUID can be provided. The business partner UUID is used in case both identifiers are provided.
Example providing the business partner internal UUID:
<MarketingResponsibleEmployeeParty> <BusinessPartnerInternalUUID>00300571-CE9B-1DED-89DE-7BBF95CDD98F</BusinessPartnerInternalUUID> </MarketingResponsibleEmployeeParty>
The node element contains the identification for the prospect party, the contacts of the prospect party and the main indicator flag.
Either the business partner internal ID or the business partner UUID can be provided. The business partner UUID is used in case both identifiers are provided.
Example:
<ProspectParty partyContactPartyListCompleteTransmissionIndicator="true" actionCode="01">
<BusinessPartnerInternalID>MC9785</BusinessPartnerInternalID>
<ContactParty actionCode="01">
<BusinessPartnerInternalID>MCP9785</BusinessPartnerInternalID>
<MainIndicator>true</MainIndicator>
</ContactParty>
<ContactParty actionCode="01">
<BusinessPartnerInternalID>MCPC9785</BusinessPartnerInternalID>
</ContactParty>