|Process Component Description||Business Partner Data Management|
|Process Component Name||BusinessPartnerDataManagement|
|Process Component Namespace||http://sap.com/xi/AP/FO/BusinessPartner/Global|
|Deployment Unit Description||Foundation|
|Endpoint Activation||By Scoping of Process Component||Operations|
An interface to query contact master data.
The web service interface Query Contact In enables you to connect external applications to your solution and to query and read contacts in your system. The web service interface Query Contact In is relevant if your company wants to access and manage business partner data from external applications.
The web service interface Query Contact In offers the operation Find By Elements.
Here is an example of a simple web service request, which seeks for all contacts related to customer MS2400 (Akron Heating):
<n0:ContactByElementsQuery_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <ContactSelectionByElements> <SelectionByRelationshipBusinessPartnerInternalID> <InclusionExclusionCode>I</InclusionExclusionCode> <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode> <LowerBoundaryIdentifier>MS2400</LowerBoundaryIdentifier> </SelectionByRelationshipBusinessPartnerInternalID> </ContactSelectionByElements> <ProcessingConditions> <QueryHitsMaximumNumberValue>10</QueryHitsMaximumNumberValue> <QueryHitsUnlimitedIndicator>false</QueryHitsUnlimitedIndicator> </ProcessingConditions> </n0:ContactByElementsQuery_sync>
Here is an excerpt of the response of the request above. It contains the relationship to the business partner MS2400:
<nm:ContactByElementsResponse_sync xmlns:nm="http://sap.com/xi/SAPGlobal20/Global"> <Contact> <ChangeStateID>20080523084202.0000000</ChangeStateID> <UUID>00300571-ce9b-1ded-89de-403b12aa5ec4</UUID> <InternalID>MSP2400</InternalID> ... <GivenName>Peter M.</GivenName> <FamilyName>Greene</FamilyName> ... <Relationship> <RelationshipBusinessPartnerUUID>00300571-cc0f-02db-b8c6-6cc9735cc23a</RelationshipBusinessPartnerUUID> <RelationshipBusinessPartnerInternalID>MS2400</RelationshipBusinessPartnerInternalID> <RoleCode>BUR001-2</RoleCode> </Relationship> <IsContactPersonForRelationship> <RelationshipBusinessPartnerUUID>00300571-cc0f-02db-b8c6-6cc9735cc23a</RelationshipBusinessPartnerUUID> <RelationshipBusinessPartnerInternalID>MS2400</RelationshipBusinessPartnerInternalID> <MainBusinessPartnerIndicator>true</MainBusinessPartnerIndicator> <WorkplaceEmailURI>firstname.lastname@example.org</WorkplaceEmailURI> ... </IsContactPersonForRelationship> </Contact> <ProcessingConditions> <ReturnedQueryHitsNumberValue>1</ReturnedQueryHitsNumberValue> <MoreHitsAvailableIndicator>false</MoreHitsAvailableIndicator> <LastReturnedObjectID>00300571CE9B1DED89DE403B12AA5EC4</LastReturnedObjectID> </ProcessingConditions> </nm:ContactByElementsResponse_sync>
You can find general information about Web services, their structure and consumption in the Web Services documentation.
The following example scenario can be carried out using requested elements.
All contacts are searched for that have "Meier" as family name. But only the nodes "Notes" and "Relationships" are returned.
<n0:ContactByElementsQuery_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <ContactSelectionByElements> <SelectionByFamilyName> <InclusionExclusionCode>I</InclusionExclusionCode> <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode> <LowerBoundaryName>Meier</LowerBoundaryName> </SelectionByFamilyName> </ContactSelectionByElements> <ProcessingConditions> <QueryHitsUnlimitedIndicator>true</QueryHitsUnlimitedIndicator> </ProcessingConditions> <RequestedElements contactTransmissionRequestCode="2"> <Contact relationshipTransmissionRequestCode="1" noteTransmissionRequestCode="1" /> </RequestedElements> </n0:ContactByElementsQuery_sync>
Here is the sample request to get all contacts for which given employee is responsible.
<n0:ContactByElementsQuery_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <ContactSelectionByElements> <SelectionByResponsibleEmployeeUUID> <InclusionExclusionCode>I</InclusionExclusionCode> <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode> <LowerBoundaryUUID>00163e03-390f-1ed2-a391-b1a36530b88f</LowerBoundaryUUID> </SelectionByResponsibleEmployeeUUID> </ContactSelectionByElements> <ProcessingConditions> <QueryHitsUnlimitedIndicator>true</QueryHitsUnlimitedIndicator> </ProcessingConditions> </n0:ContactByElementsQuery_sync>
To find contact data by elements.
The request message of the operation "FindByElements" contains the ContactSelectionByElements node that groups all possible selection parameters. This node is described in the following sub-chapter.
This node groups all selection parameters. The selection parameters are:
|SelectionByInternalID||Selection by internal ID (business partner ID)|
|SelectionByUUID||Selection by UUID|
|SelectionByFamilyName||Selection by family name|
|SelectionByGivenName||Selection by given name|
|SelectionBySortingFormattedName||Selection by formatted name|
|SelectionByAddressDefaultIndicator||Selection by address default indicator. No range is used for this selection. Using "false" for this selection parameter has the semantics that only contacts are selected which have an address without the default indicator being set.|
|SelectionByPostalAddressCityName||Selection by postal address city name|
|SelectionByPostalAddressStreetPostalCode||Selection by postal address street postal code|
|SelectionByPostalAddressCountryCode||Selection by postal address country code|
|SelectionByLifeCycleStatusCode||Selection by life cycle status code: 1 for "In Preparation"; 2 for "Active"; 3 for "Blocked"; 4 for "Obsolete"|
|SelectionByRelationshipBusinessPartnerInternalID||Selection by relationship business partner internal ID|
|SelectionByRelationshipBusinessPartnerUUID||Selection by relationship business partner UUID|
|SelectionByRelationshipBusinessPartnerCommonOrganisationNameFirstLineName||Selection by relationship business partner common organization name first line name|
|SelectionByRelationshipBusinessPartnerCommonSortingFormattedName||Selection by relationship business partner common sorting formatted name|
|SelectionByRelationshipContactPersonBusinessPartnerFunctionTypeCode||Selection by relationship contact person business partner function type code|
|SelectionByRelationshipContactPersonBusinessPartnerFunctionalAreaCode||Selection by relationship contact person business partner functional area code|
|SelectionByCreatedSinceDate||Selection by created since date. No range is used for this selection.|
|SelectionByCreatedSinceDateTime||Selection by created since date time. No range is used for this selection.|
|SelectionByChangedSinceDateTime||Selection by changed since date time. No range is used for this selection.|
|SelectionByCreationIdentityID||Selection by creation identity ID.|
|SelectionByLastChangeIdentityID||Selection by last change identity ID.|
|SelectionByRelationshipBusinessPartnerLifeCycleStatusCode||Selection by relationship business partner life cycle status code.|
|SelectionByValidityDate||Selection by validity date.|
|SelectionByResponsibleAgentUUID||Selection by service agent responsible UUID.|
|SelectionBySearchText||Selection by search text. No range is used for this selection.|
|SelectionByResponsibleEmployeeUUID||Selection by employee responsible UUID.|
The response contains the list of found contacts, log items, and processing conditions.
In this node, all found contacts are contained, including their data according to the RequestedElements provided in the query request. This includes the ChangeStateID that may be needed for subsequent change requests via web services as well.
For each contact address the address UUID and the most current address snapshot UUID are returned by this service. Note that the address snapshot UUID is not available for contacts with status In Preparation.
If you want to change or display address data of business partners, use the AddressInformationUUID element.
In all other cases use the current address snapshot UUID representing an address snapshot of this business partner address with the currently valid data. This applies particularly to all usages of the address within business processes or business transaction documents, such as sales orders, purchasing orders, outbound deliveries, or invoices.
The address snapshot contains exactly the same data as the business partner address, but it cannot be changed: If the business partner’s address changes, the address snapshot does not change, but a new address snapshot is created for each change of the business partner address instead.
Note that for all SAP-delivered business transaction documents, you must use the address snapshot UUID; you cannot use the address UUID.