Inbound Service ManageContactIn

Overview

Description Manage Contacts

Name ManageContactIn

Namespace http://sap.com/xi/A1S/Global

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  Check contacts

 Maintain contacts

Public Solution Model

Release Status Released

Documentation

Definition

An interface to migrate contact master data from a source system or file.

Business Context and Use

The web service interface Manage Contact In enables you to connect external applications to
your solution and to create and edit contacts in your system. The web service interface
Manage Contact In is relevant if your company wants to access and manage business partner
data from external applications.

The web service interface Manage Contact In offers the operations MaintainBundle and
CheckMaintainBundle.

Here is an example of a simple web service request:

<ns1:ContactBundleMaintainRequest_sync_V1 xmlns:ns
="http://sap.com/xi/SAPGlobal20/Global">

<BasicMessageHeader />

<Contact actionCode="01">

<LifeCycleStatusCode>2</LifeCycleStatusCode>

<GivenName>Hugo</GivenName>

<FamilyName>Meier</FamilyName>
</Contact>

</ns1:ContactBundleMaintainRequest_sync_V1>

The following example response returns the InternalID and the UUID of the created contact
person:

<nm:ContactBundleMaintainConfirmation_sync
xmlns:nm="http://sap.com/xi/SAPGlobal20/Global">

<Contact>

<ReferenceObjectNodeSenderTechnicalID> </ReferenceObjectNodeSenderTechnicalID>

<ChangeStateID>20121121162952.5876960</ChangeStateID>

<InternalID>1008034</InternalID>

<UUID>00163e02-8b2e-1ee2-8cff-1590d2192418</UUID>

</Contact>

<Log/>

</nm:ContactBundleMaintainConfirmation_sync>

Prerequisites

Existence of referenced business objects:

The following business objects are only referenced and will not be created by the service
operations. They must already exist in the system.

 Corporate Account

Constraints and Integrity Conditions

General Rules for Using This Web Service

Change State ID

Note: For this web service the change state ID does not apply to the ContactPerson,
Relationship, CommunicationArrangement, DirectResponsibility, SalesArrangement, or
PaymentData node elements.

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

Possible scenarios include the following:

 Create Contacts

The MaintainBundle_V1 operation is used to create contacts.

  Update Contacts

The MaintainBundle_V1 operation is used to update existing contacts.

Here is an example web service request for a contact:

<n0:ContactBundleMaintainRequest_sync_V1
xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">

<BasicMessageHeader/>

<Contact actionCode="01">

<ObjectNodeSenderTechnicalID>Contact</ObjectNodeSenderTechnicalID>

<!-- ChangeStateID is only relevant for changing

<ChangeStateID>20101201082957.5189460</ChangeStateID> -->

<!-- The UUID cannot be changed

<UUID>12345678-90AB-CDEF-0123-456789ABCDEF</UUID> -->

<InternalID>CONTACT1</InternalID>

<LifeCycleStatusCode>2</LifeCycleStatusCode>

<FormOfAddressCode>0002</FormOfAddressCode>

<AcademicTitleCode>0001</AcademicTitleCode>

<GivenName>GivenName</GivenName>

<MiddleName>MiddleName</MiddleName>

<BirthName>BirthName</BirthName>

<NickName>NickName</NickName>

<FamilyName>FamilyName</FamilyName>

<NameFormatCountryCode>DE</NameFormatCountryCode>

<GenderCode>1</GenderCode>

<BirthDate>1980-01-24</BirthDate>

<NonVerbalCommunicationLanguageCode>EN</NonVerbalCommunicationLanguageCode>

<OccupationCode>0001</OccupationCode>
 <ContactPermissionCode>1</ContactPermissionCode>

<!-- Maintain relationships to Business Partners -->

<Relationship>

<RelationshipBusinessPartnerInternalID>BP001</RelationshipBusinessPartnerInternalID>

<RoleCode>BUR004-0</RoleCode>

</Relationship>

<!-- Maintain relation to an account -->

<IsContactPersonForRelationship actionCode="01"
WorkplaceTelListCompleteTransmissionIndicator="true">

<ObjectNodeSenderTechnicalID>Relationship</ObjectNodeSenderTechnicalID>

<RelationshipBusinessPartnerInternalID>AC001</RelationshipBusinessPartnerInternalID>

<RoleCode>BUR001</RoleCode>

<MainBusinessPartnerIndicator>true</MainBusinessPartnerIndicator>

<BusinessPartnerFunctionTypeCode>0003</BusinessPartnerFunctionTypeCode>

<BusinessPartnerFunctionalAreaCode>0002</BusinessPartnerFunctionalAreaCode>

<VIPReasonCode>B</VIPReasonCode>

<WorkplacePreferredCommunicationMediumTypeCode>INT</WorkplacePreferredCommunica
tionMediumTypeCode>

<WorkplaceEmailURI>work@sap.com</WorkplaceEmailURI>

<WorkplaceFacsimileFormattedNumberDescription>+34 345
444</WorkplaceFacsimileFormattedNumberDescription>

<WorkplaceTelephone>

<FormattedNumberDescription>+ 49 177 111 111 11</FormattedNumberDescription>

<MobilePhoneNumberIndicator>true</MobilePhoneNumberIndicator>

</WorkplaceTelephone>

<WorkplaceTelephone>

<FormattedNumberDescription>+ 49 2222 22 22 22</FormattedNumberDescription>

<MobilePhoneNumberIndicator>false</MobilePhoneNumberIndicator>

</WorkplaceTelephone>
 <WorkplaceWebURI>http://www.work.sap.com</WorkplaceWebURI>

<WorkplaceFunctionalTitleName>CEO</WorkplaceFunctionalTitleName>

<WorkplaceDepartmentName>IT</WorkplaceDepartmentName>

<WorkplaceBuildingID>Foundry</WorkplaceBuildingID>

<WorkplaceFloorID>Floor 7</WorkplaceFloorID>

<WorkplaceRoomID>Room 77</WorkplaceRoomID>

</IsContactPersonForRelationship>

<!-- Maintain address -->

<AddressInformation actionCode="01">

<ObjectNodeSenderTechnicalID>Address</ObjectNodeSenderTechnicalID>

<Address actionCode="01" telephoneListCompleteTransmissionIndicator="true">

<EmailURI>email@gmx.de</EmailURI>

<FacsimileFormattedNumberDescription>+49 233
233</FacsimileFormattedNumberDescription>

<PostalAddress>

<CountryCode>DE</CountryCode>

<RegionCode>08</RegionCode>

<CountyName>Baden</CountyName>

<CityName>Heidelberg</CityName>

<AdditionalCityName>Le City</AdditionalCityName>

<DistrictName>Untere Gasse</DistrictName>

<StreetPostalCode>23443</StreetPostalCode>

<POBoxPostalCode>88372</POBoxPostalCode>

<StreetPrefixName>SteetPrefix</StreetPrefixName>

<AdditionalStreetPrefixName>AdditionalStreetPrefix</AdditionalStreetPrefixName>

<StreetName>Heidelbergstraße</StreetName>

<StreetSuffixName>StreetSuffix</StreetSuffixName>

<AdditionalStreetSuffixName>AdditionalStreetSuffix</AdditionalStreetSuffixName>

<HouseID>1</HouseID>

<CareOfName>Nice Care of Name</CareOfName>

 <POBoxDeviatingCountryCode>GB</POBoxDeviatingCountryCode>

<POBoxDeviatingRegionCode>CO</POBoxDeviatingRegionCode>

<POBoxDeviatingCityName>Commonwealth</POBoxDeviatingCityName>

<POBoxID>66631</POBoxID>

<POBoxIndicator>true</POBoxIndicator>

<TimeZoneCode>CET</TimeZoneCode>

</PostalAddress>

<Telephone>

<FormattedNumberDescription>+49 111 11 1</FormattedNumberDescription>

<MobilePhoneNumberIndicator>true</MobilePhoneNumberIndicator>

</Telephone>

<Telephone>

<FormattedNumberDescription>+49 222 22</FormattedNumberDescription>

<MobilePhoneNumberIndicator>false</MobilePhoneNumberIndicator>

</Telephone>

</Address>

<AddressUsage actionCode="01">

<ObjectNodeSenderTechnicalID>AddressUsage</ObjectNodeSenderTechnicalID>

<AddressUsageCode>XXDEFAULT</AddressUsageCode>

<DefaultIndicator>false</DefaultIndicator>

</AddressUsage>

</AddressInformation>

<!-- Maintain language-independant notes -->

<Note>

<ObjectNodeSenderTechnicalID>Note</ObjectNodeSenderTechnicalID>

<ContentText>Test</ContentText>

</Note>

<!-- Maintain contact attachments like documents, images, links... -->

<AttachmentFolder DocumentListCompleteTransmissionIndicator="true" ActionCode="01">

 <!-- Link attachment -->

<Document ActionCode="01">

<VisibleIndicator>true</VisibleIndicator>

<CategoryCode>3</CategoryCode>

<TypeCode>10001</TypeCode>

<Name>SAP AG</Name>

<AlternativeName>SAP AG Homepage</AlternativeName>

<Description languageCode="EN">Hyperlink to SAP AG</Description>

<ExternalLinkWebURI>http://www.sap.com/</ExternalLinkWebURI>

</Document>

<!-- File attachment -->

<Document ActionCode="01">

<VisibleIndicator>true</VisibleIndicator>

<CategoryCode>2</CategoryCode>

<TypeCode>10001</TypeCode>

<MIMECode>image/jpg</MIMECode>

<Name>Logo</Name>

<AlternativeName>Company Logo</AlternativeName>

<Description languageCode="EN">The Company`s logo</Description>

<FileContent ActionCode="01">

<BinaryObject mimeCode="image/png" characterSetCode="" format="" fileName=""

uri="">AQIDBAUGBwgJAA==</BinaryObject>

</FileContent>

</Document>

</AttachmentFolder>

<DuplicateCheckApplyIndicator>false</DuplicateCheckApplyIndicator>

</Contact>

</n0:ContactBundleMaintainRequest_sync_V1>
Operation Check Maintain Bundle

Overview

Description Check contacts

Name CheckMaintainBundle

Synchronous yes

Public Solution Model

Release Status Released

Documentation

Business Context and Use

The web service request- and response message types for the “CheckMaintainBundle”
operation are the same as those of the “Maintain Bundle” operation.

Operation Maintain Bundle

Overview

Description Maintain contacts

Name MaintainBundle

Synchronous yes

Public Solution Model

Release Status Released

Documentation

Business Context and Use

The request message of the operation MaintainBundle contains a BasicMessageHeader node

element as well as a Contact node element that contains the contact data to be created or
updated. The detailed structure of the Contact node will be explained in the following sub-
chapters. The Contact node can occur multiple times in the request message – this means that
multiple contacts 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 contact-specific node with ReferenceObjectNodeSenderTechnicalID,
ChangeStateID, as well as contact InternalID and contact UUID.

Structure

Contact

The Contact node element can be used to create and change Contacts. This contains all general
contact information such as ID, UUID, names, and other identifications. The data for this node
is related to General data on the contact UI.
The InternalID element corresponds to the Contact ID on the UI - the UUID element is not
visible on the UI, but can be retrieved using query and read web services.

Note: Please be aware of the fact that the element DuplicateCheckApplyIndicator means that a
duplicate check is performed if the current solution supports the check and if the check is
activated in the Business Configuration.

Address Information

The AddressInformation node element can be used to create and change contact addresses.

Data for the AddressInformation node element is related to Addresses data on the contact UI.
The elements of the Address sub-node element in the request message are located in the
Address details section on the UI.

The AddressUsage sub-node element corresponds to the usages in the table of addresses on
the contact UI. The usages are modeled as a list of AddressUsageCodes in the request
message:

User Interface AddressUsageCode

Main personal address XXDEFAULT

The DefaultIndicator element is not relevant for the usage code XXDEFAULT. If multiple
personal addresses exist, one of them has to be the default address - which means the
AddressUsageCode is XXDEFAULT. On the user interface the default address has the value
"Main Personal Address". All other Personal Addresses do not have an AddressUsage at all. For
the "Business Address", contact-specific data like Business Communication, Details or
Workplace Building, Floor and Room are maintained via the node element
"IsContactPersonForRelationship".

The Telephone sub-node element allows two entries at maximum - one with
MobilePhoneNumberIndicator = "true" and one with MobilePhoneNumberIndicator = "false".
This corresponds to the Phone and Mobile fields on the user interface.

If changes to node element Telephone are requested, the

telephoneListCompleteTransmissionIndicator has to be set to “true” (and the complete list has
to be transmitted).

Relationship

The Relationship node element can be used to create, change, and delete relations to an
existing business partner.

The data of the Relationship node corresponds to the Relationships data on the UI.

This node contains all relationships that a contact has with other business partners, which
have to be maintained by specifying the relationship direction. If the contact, which is
represented by the root segment of the service, shall be the first business partner in the
relationship, the relationship type code ends with -1 (e.g. BUR013-1).

Note: Not all relationship types allow to maintain the contact as the first business partner. For
example, to assign the contact to an existing account for an IsContactFor relationship the code
"BUR001-2" must be used.
The node can also include "is contact person for" relationships. In this case an empty
relationship node in combination with relationshipListCompleteTransmissionIndicator="true"
will also remove contact person relationships.

IsContactPersonFor Relationship

Data of this node can be found in the Relationships section of the user interface for the
relationship type "Is contact person for".

The data for the Business Address, Business Communication and Business Details are located
as elements / sub nodes in this node of the request message.

The IsContactPersonForRelationship node creates or updates a contact person relationship and

directly assigns it to an existing account. To assign existing accounts to a contact person there
are two possible options:

 The Relationship node can be used. The RoleCode for contact person relationships is
"BUR001-2".

 The IsContactPersonForRelationship node can be used. In this case only the

RelationshipBusinessPartnerUUID or the RelationshipBusinessPartnerInternalID need
to be filled.

The contact persons assigned can be removed from an account using one of the following
nodes:

 Relationship node.

 ContactPerson node. In this case the BusinessPartnerContactUUID or the

BusinessPartnerContactInternalID have to be filled and the actionCode must be "03" or
"05".

For the WorkplaceTelephone sub node two entries at maximum are allowed - one with
MobilePhoneNumberIndicator = "true" and one with MobilePhoneNumberIndicator = "false".
This corresponds to the Phone and Mobile fields on the user interface.

By default the Business Address data relates to the Main Address of the account the contact
person is assigned to. If an account has multiple addresses it can be chosen to which of these
addresses the Business Address should be related to. This is can be achieved by referencing
the value of the UUID of the account's address in the WorkplaceBusinessAddressUUID element
of the AddressInformation sub node.

If changes to the WorkplaceTelephone should be performed the attribute

WorkplaceTelListCompleteTransmissionIndicator="true" should be set at
"<IsContactPersonForRelationship>" (and the complete list has to be transmitted).

For example, <IsContactPersonForRelationship

WorkplaceTelListCompleteTransmissionIndicator="true">

Note

Language independent text can be provided as a contact note.

If an update operation on the Text node is to be performed, the
textListCompleteTransmissionIndicator must be set to “true”, and the complete list has to be
transmitted. Notes in contacts can be changed by the creator only.

Note: If a web service call is performed using a communication user, then created texts cannot
be changed afterwards through the UI, because it is not possible to log on with the
communication user.

Attachment Folder

The AttachmentFolder node element can be used to add and remove contact attachments.

Data for this node can be found on the contact 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

10016 Business partner image

10017 Business card

10078 Avatar Image

To create link attachments, Document elements must be as follows:

Element Value

VisibleIndicator "true"

CategoryCode 3

TypeCode <none>

AlternativeName <Document Title>

ExternalLinkWebURI <link URI>

Description <Comment>

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>

In the FileContent-BinaryObject element the content element has to contain the file's binary
content.

The Property node and it's sub nodes are not functional by intention.