Show full documentation

 Show full documentation

Definition

An interface to query contact master data.

Business Context and Use

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>peter.greene@akron.com</WorkplaceEmailURI>
            ...
        </IsContactPersonForRelationship>
    </Contact>
    <ProcessingConditions>
        <ReturnedQueryHitsNumberValue>1</ReturnedQueryHitsNumberValue>
        <MoreHitsAvailableIndicator>false</MoreHitsAvailableIndicator>
        <LastReturnedObjectID>00300571CE9B1DED89DE403B12AA5EC4</LastReturnedObjectID>
    </ProcessingConditions>
</nm:ContactByElementsResponse_sync>

Constraints and Integrity Conditions

More Information

General Information

You can find general information about Web services, their structure and consumption in the Web Services documentation. Please open the Web Services document in a new window.

Scenarios

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>

 Show full documentation

 Show full documentation

Definition

To find contact data by elements.

Business Context and Use

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.

Structure

Request

Contact Selection By Elements

This node groups all selection parameters. The selection parameters are:

Selection Parameter	Remark
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.

Response

The response contains the list of found contacts, log items, and processing conditions.

Contact

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.