| Description | Manage Opportunities |
| Name | ManageOpportunityIn |
| Namespace | http://sap.com/xi/A1S/Global |
| Process Component Description | Opportunity Processing |
| Process Component Name | OpportunityProcessing |
| 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 create, update or delete an opportunity which can be used for opportunity migration or replication.
The web service interface Manage Opportunity In enables you to connect external applications to your SAP system and to create and edit opportunities within your system. The web service interface Manage Opportunity In is relevant if your company wants to access and manage opportunity data from external applications.
The web service interface Manage Opportunity In offers the operations MaintainBundle and CheckMaintainBundle.
Existence of required master data and related business documents in the system, like:
Master data of MOM and BusinessPartner: SalesUnit, SalesOrganization, Employee, Customer, etc.
Product Master data: Material, Service Product
Campaigns or other business documents to be related to the Opportunity in the BusinessTransactionDocumentReference
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 can 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. This will avoid accidentially creating duplicate business documents.
The processing of node elements with cardinality > 1 (for example a list of descriptions in different languages or a list of telephone numbers) 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 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 to the action code. If transmitted node elements in 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 deleted. If no node element is transmitted, all the node elements in the system will be 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.
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 ensure 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.
Note: For this web service the change state ID does not apply to the ContactPerson, Relationship, CommunicationArrangement, DirectResponsibility, SalesArrangement, or PaymentData node elements.
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. 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:
Show full documentation
Show full documentation
<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 an Opportunity
The MaintainBundle operation is used to create a opportunity
Update an Opportunity
The MaintainBundle operation is used to change or delete an existing opportunity
Example to create an opportunity:
<n0:OpportunityBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
<BasicMessageHeader/>
<Opportunity actionCode="01">
<Name>MyOpportunity20121001</Name>
<ProspectParty>
<BusinessPartnerInternalID>MC9785</BusinessPartnerInternalID>
</ProspectParty>
<EmployeeResponsibleParty>
<BusinessPartnerInternalID>MC9785</BusinessPartnerInternalID>
</EmployeeResponsibleParty>
<SalesForecast>
<ProbabilityPercent>88</ProbabilityPercent>
<ExpectedRevenueAmount currencyCode="EUR">8888.00</ExpectedRevenueAmount>
</SalesForecast>
<Item actionCode="01">
<ID>10</ID>
<Quantity unitCode="EA">100</Quantity>
<ExpectedNetAmount currencyCode="EUR">100000</ExpectedNetAmount>
<ItemProduct>
<MaterialInternalID>MCF-0001</MaterialInternalID>
</ItemProduct>
</Item>
<Text actionCode="01">
<TextTypeCode>10001</TextTypeCode>
<ContentText>This is my first opportunity</ContentText>
</Text>
</Opportunity>
</n0:OpportunityBundleMaintainRequest_sync>
Example to update an opportunity:
<n0:OpportunityBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
<BasicMessageHeader/>
<Opportunity actionCode="02" itemListCompleteTransmissionIndicator="false" textListCompleteTransimissionIndicator="true">
<ID>4989</ID>
<SalesForecast>
<ProbabilityPercent>99</ProbabilityPercent>
<ExpectedRevenueAmount currencyCode="EUR">9999.00</ExpectedRevenueAmount>
</SalesForecast>
<Item actionCode="04">
<ID>10</ID>
<Description languageCode="EN">Change this existing Item</Description>
<Quantity unitCode="EA">100</Quantity>
<ExpectedNetAmount currencyCode="EUR">100000</ExpectedNetAmount>
<ItemProduct>
<MaterialInternalID>MCF-0036</MaterialInternalID>
</ItemProduct>
</Item>
<Item actionCode="04">
<ID>30</ID>
<Description languageCode="EN">Create this NEW Item</Description>
<Quantity unitCode="EA">200</Quantity>
<ExpectedNetAmount currencyCode="EUR">200000</ExpectedNetAmount>
<ItemProduct>
<MaterialInternalID>MCF-0001</MaterialInternalID>
</ItemProduct>
</Item>
<Text actionCode="04">
<TextTypeCode>10001</TextTypeCode>
<ContentText>This is an update of my first opportunity</ContentText>
</Text>
</Opportunity>
</n0:OpportunityBundleMaintainRequest_sync>
Example to delete an opportunity:
<n0:OpportunityBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader/> <Opportunity actionCode="03"> <ID>4989</ID> </Opportunity> </n0:OpportunityBundleMaintainRequest_sync>
| Description | Maintain opportunities |
| Name | MaintainBundle |
| Synchronous | yes |
| Release Status | Deprecated |
To create, update, or delete an Opportunity.
The request message of the operation MaintainBundle contains a BasicMessageHeader node element as well as an Opportunity node element that contains the opportunity data to be created or updated. The detailed structure of the Opportunity node will be explained in the following sub-chapters. The Opportunity node can occur multiple times in the request message. This means that multiple opportunities 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 an opportunity-specific node with ReferenceObjectNodeSenderTecnicalID, ChangeStateID, as well as Opportunity ID and UUID.
The Opportunity node element contains all general opportunity information such as ID, UUID, name, and other forms of identification.
The data for this node is related to General data on the Opportunity UI.
The ID is a unique identifier of the opportunity. In creation case, it is automatically generated by the system. In update or deletion case, the ID (or UUID) must be provided
The UUID is a unique identifier of the opportunity. In creation case, it is automatically generated by the system. In update or deletion case, the UUID must be provided if the ID is not provided.
The name is the subject of an opportunity. It is mandatory and will be shown in the UI.
The Priority Code specifies the priority of an opportunity by the following codes:
| PriorityCode | Description |
|---|---|
| 1 | Immediate |
| 2 | Urgent |
| 3 | Normal |
| 7 | Low |
The Group Code is used to group opportunities under a certain aspect.
| PriorityCode | Description |
|---|---|
| 0023 | Prospect for product sales |
| 0024 | Prospect for service |
| 0025 | Prospect for training |
| 0026 | Prospect for consulting |
The Data Origin Type Code specifies the origin of the opportunity
| DataOriginTypeCode | Description |
|---|---|
| 1 | Trade fair |
| 2 | External partner |
| 3 | Campaign |
| 4 | Telephone inquiry |
| 5 | Roadshow |
If not specified by the consumer, a default is set by the web service.
A result reason code can only be set if the value is maintained and assigned to the corresponding lifecycle status of the opportunity in the BC Finetuning.
Possible values corresponding to the lifecycle status are
| Reason Code | Description |
|---|---|
| 001 | Lost to competitor |
| 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 |
The Process Status Valid Since Date can be currently only set in an update run due to dependencies of status actions, or also from the start date of the sales phase. In a create case, the action for the status value sets the current date and overwrites the previous setting.
The LifeCycleStatusCode indicates roughly the status of the opportunity
| LifeCycleStatusCode | Description |
|---|---|
| 1 | Open |
| 2 | In Process |
| 3 | Stopped |
| 4 | Won |
| 5 | Lost |
If not specified by the consumer, a default is set by the web service.
The Sales Forecast allows to set the probability, estimated in percent (ProbabilityPercent), the expected revenue (ExpectedRevenueAmount), the Forcast Relevance Indicator (SalesRevenueForecastRelevanceIndicator), the estimated budget of the interested party (ProspectBudgetAmount), and the period in which the Opportunity will probably be processed (ExpectedProcessingDatePeriod).
The SalesCycle includes the salescycle code and phase code, and the date when the phase became active.
The SalesCycle Code must be set during creation and cannot be changed. The code values must fit to the configuration of the sales cycles and their phases.
The StartDateTime and EndDateTime specifies the period in which the activity task is scheduled for processing.
A timestamp for each DateTime has to be provided. Both Dates have to be set together.
The prospect party can be specified by the BusinessPartnerInternalID.
Addtional contact persons on the prospect side could be assigned via ContactPerson. The main contact can be set by the Main Indicator.
The employee responsible party is the employee who's mainly responsible for the opportunity. It can be specified either by the Business partner ID or the Employee ID.
SalesEmployeeParty allows to specifies employees working on an Opportunity.
Note: if the the corresponding complete list transmission indicator is set to true in update case, all sales employees must be provided. The one which is not provided will be deleted.
SalesTeamParty allows to specify a party working on an Opportunity as part of a sales team.
Impotant Note: The Sales Team Party only supports complete list transmission indicator with the value TRUE if there is no overlap to the correponding tags 'ResponsibleParty', 'SalesUnitParty' and 'SalesEmployeeParty'. Sales Team Party is a set of these Parties with role codes '39','44' and '46'. Due to implicit delete logic in case of true complete list transmission for Sales Team Party an overlap i.e between Sales Unit Party (role code 44) and Sales Team Party leads to an update request for the sales unit but also a delete request for the same unit via Sales Team Party which ends in a dump!
The sales unit party is an org unit to which the opportunity is reported. It can be specified by the org center ID.
SalesPartnerParty allows you to maintain a party that is involved in processing the Opportunity as a sales partner.
Note: if the the corresponding complete list transmission indicator is set to true in update case, all sales partners must be provided. The one which is not provided will be deleted.
The competitor party can be specified by the BusinessPartnerInternalID. There can be multiple competitors. The main competitor can be flagged via the MainIndicator.
Note: if the the corresponding complete list transmission indicator is set to true in update case, all competitors must be provided. The one which is not provided will be deleted.
The competitor product can be specified by the MaterialInternalID or ServiceProductInternalID. There can be multiple competitor products per competitor.
Specifies a party maintained with a custom-defined role.
Note: if the the corresponding complete list transmission indicator is set to true in update case, all other parties must be provided. The one which is not provided will be deleted.
The sales and service business area is the sales and service specific business area that is valid for an opportunity. It can be specified by a sales organization and a distribution channel.
An item of the Opportunity contains product information, quantity, values, revenue plan, texts and attachments. The data of an item can be provided fully or partially.
Example:
<Item actionCode="01">
<ID>10</ID>
<Quantity unitCode="EA">10</Quantity>
<ExpectedNetAmount currencyCode="EUR">100000</ExpectedNetAmount>
<ItemProduct>
<MaterialInternalID>MCF-0001</MaterialInternalID>
</ItemProduct>
<Text actionCode="01">
<TextTypeCode>10001</TextTypeCode>
<ContentText>This is an additional external comment</ContentText>
</Text>
</Item>
<Item actionCode="01">
<ID>20</ID>
<Description languageCode="EN">Product category item</Description>
<ExpectedNetAmount currencyCode="EUR">100000</ExpectedNetAmount>
<ItemProduct>
<ProductCategoryInternalID>50-10</ProductCategoryInternalID>
</ItemProduct>
</Item>
Note:
If the the corresponding complete list transmission indicator is set to true in update case, all items must be provided. The one which is not provided will be deleted.
When an additional item is to be added, or an existing item is to be changed or deleted, other items need not to be provided if the item complete list transmission indicator is set to false.
For product items, the product category is determined from the product master. In update case, the product category of such items cannot be changed.
In general, with the Business Transaction Document Reference, the opportunity can be linked to other business documents like an activitiy or a campaign. To create or update a business transaction document reference, the ID (or UUID), TypeCode of the related business document as well as the RoleCode of the business document within the relationship shall be provided.
The allowed RoleCode are 1 - for Predecessor and 2 - for the Successor.
A opportunity can have the following business transaction document references:
CampaignPredecessorBusinessTransactionDocumentReference
A campaign as related business document to an opportunity can only be a predecessor and is always at header level. The type code of Campaign is 764.
LeadPredecessorBusinessTransactionDocumentReference
A lead as related business document is a predecessor to the opportunity. The type code of Lead is 64.
ActivitySuccessorBusinessTransactionDocumentReference
An activity as related business document is a predecessor to the opportunity. An activity can for example be an activity task with type code 542, an email activity with type code 39, or an appointment activity with type code 12.
Addionally the actual values of an activity as successor of an opportunity can be set. The actual values defines sales cycle phase in which the activity was created.
ActivityPredecessorBusinessTransactionDocumentReference
The Activity as the related business document can be a predecessor to the opportunity.
SalesOrderSuccessorBusinessTransactionDocumentReference
A sales order as related business document is a successor to the opportunity. The type code of Sales Order is 114.
Additionally, a reference to a sales order item can also be created. In this case, the item type code is to be provided. Main item type codes of the Sales Order are:
| ItemTypeCode | Description |
|---|---|
| 28 | Sales Item |
| 16777 | Sales Service Item |
CustomerQuoteSuccessorBusinessTransactionDocumentReference
A customer quote as related business document is a successor to the opportunity. The type code of Customer Quote is 30.
Additionally, a reference to a customer quote item can also be created. In this case, the item type code is to be provided. Main item type codes of the Customer Quote are:
| ItemTypeCode | Description |
|---|---|
| 29 | Sales Quote Item |
| 16778 | Sales Service Quote Item |
The revenue split party can be specified by the RevenueEmployeeID.
Note: if the the corresponding complete list transmission indicator is set to true in update case, all revenue split parties must be provided. The one which is not provided will be deleted.
The revenue distribution at the header level per revenue split party can be specified. For this the HeaderRevenueSchedule in the Root node should be set to true.
The Text Node Element allows you to set texts for the opportunity. The following text types are allowed:
| TextTypeCode | Description |
|---|---|
| 10001 | Additional External Comment |
| 10037 | Competitor Note |
There can be multiple Additional External Comments and Competitor Notes. For each of them a timestamp as CreationDateTime can be provided to capture a sequence of comments.
Example:
<Text actionCode="01"> <TextTypeCode>10001</TextTypeCode> <ContentText>This is an additional external comment</ContentText> </Text> <Text actionCode="01"> <TextTypeCode>10037</TextTypeCode> <ContentText>This is an competitor note</ContentText> <CreationDateTime>2012-10-01T12:45:00.0000000Z</CreationDateTime> </Text> <Text actionCode="01"> <TextTypeCode>10037</TextTypeCode> <ContentText>This is another competitor note</ContentText> <CreationDateTime>2012-10-05T12:55:00.0000000Z</CreationDateTime> </Text>
The AttachmentFolder node element can be used to add or remove attachments in the opportunity.
An attachment can be either a file or a link with the following CategoryCode:
| Category code | Description |
|---|---|
| 2 | Document |
| 3 | Link |
The following attachment type is supported in the opportunity:
| Type code | Description |
|---|---|
| 10001 | Standard attachment |
To create link attachments, document elements must be like the following:
| Element | Value |
|---|---|
| VisibleIndicator | true |
| CategoryCode | 3 |
| TypeCode | <none> |
| AlternativeName | <Document Title> |
| ExternalLinkWebURI | <link URI> |
| Description | <Comment> |
To create file attachments, document elements must be like the following:
| Element | Value |
|---|---|
| VisibleIndicator | true |
| CategoryCode | 2 |
| TypeCode | <none> |
| Name | <Document Title> |
| AlternativeName | <Document Title> |
| Description | <Comment> |
| Description | Check opportunities |
| Name | CheckMaintainBundle |
| Synchronous | yes |
| Release Status | Deprecated |
To check if opportunity data 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.