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 |
Release Status | Released |
An interface to migrate contact master data from a source system or file.
The web service interface "Manage Contact In" enables you to connect external applications to your SAP Business ByDesign system 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" xmlns:ns1="http://sap.com/xi/A1S/Global"> <CategoryCode>1</CategoryCode> <GivenName>JIM</GivenName> <FamilyName>SNABE</FamilyName> <Relationship actionCode="04" workplaceTelephoneListCompleteTransmissionIndicator="false"> <VIPReasonCode>A</VIPReasonCode> </Relationship> <DuplicateCheckApplyIndicator>true</DuplicateCheckApplyIndicator> </Contact> </ns1:ContactBundleMaintainRequest_sync_V1>
Existence of referenced business documents:
While creating a contact for an account, the following business documents are only referenced and will not be created by the service operations. The following should be existing in the system.
Corporate Account
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.
Description | Check contacts |
Name | CheckMaintainBundle |
Synchronous | yes |
Release Status | Released |
The web service request- and response message types for the “CheckMaintainBundle” operation are the same as those of the “Maintain Bundle” operation.
Description | Maintain contacts |
Name | MaintainBundle |
Synchronous | yes |
Release Status | Released |
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 a contact-specific node with ReferenceObjectNodeSenderTechnicalID, ChangeStateID, as well as contact InternalID and contact UUID.
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 identification data. The data for this node is related to General Data on the account UI. For contacts, the CategoryCode is "1".
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.
Existing contact persons can be assigned to accounts using the Relationship and Contact node elements:
1. Relationship node element: Provide the RelationshipBusinessPartnerUUID or RelationshipBusinessPartnerInternalID elements to identify the related contact and set RoleCode "BUR001-1".
2. Contact node element: Provide elements BusinessPartnerContactUUID or the BusinessPartnerContactInternalID to identify the related contact. In addition, the actionCode must be set to "04" (save).
Contact person relations can be removed from an account using the Relationship and Contact node elements.
Existing employees can be assigned to or made responsible for contacts using the current employee responsible node elements. Also, there is an option to provide a value for the groupware subscription indicator for the synchronization of accounts and contacts from your system to an external web client or vice versa.
The WorkplaceTelephone 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 account UI.
By default, the contact workplace address refers to the main/default account address of the account to which the contact is assigned. If an account has multiple account addresses, the workplace address of the contact person can be related to an account address of your choice. To assign a contact person workplace address, enter the AddressInformation UUID of the account address in the WorkplaceBusinessAddressUUID element of the contact.
The Main Private Address and additional Private Addresses can be provided in the AddressInformation sub-node element of the Contact node element. The Main Private Address is the address with the AddressUsageCode = "XXDEFAULT". All other Private Addresses do not have an AddressUsage at all.
If changes to the WorkplaceTelephone are to be performed, the workplaceTelephoneListCompleteTransmissionIndicator must be set to “true”, and the complete list has to be transmitted.
The AddressInformation node element can be used to create and change contact addresses.
Data for the AddressInformation node element is related to Communication Addresses data on the contact UI. The elements of the Address sub-node element in the request message are located in the Address- and Communication 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 address | "XXDEFAULT" |
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. The DefaultIndicator element is not relevant for the usage code "XXDEFAULT". In case of multiple addresses, instances have the same usage code (e.g. two ship-to addresses); one address has to be indicated as the default address for that particular address usage - which means the DefaultIndicator has to be "true" for exactly one of these addresses. On the user interface, the default address for a given usage has the value "Yes (Standard)".
If changes to node element Telephone are requested, the telephoneListCompleteTransmissionIndicator has to be set to “true” (and the complete list has to be transmitted).
Note: An address that has been saved cannot be deleted, and hence instances of the AddressInformation node element cannot be deleted in this case, either.
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 on the account UI.
To assign a Contact to an Account, You need to provide a valid Account ID in <RelationshipBusinessPartnerInternalID>. And with that the contact will be assigned to the Account ID provided by you.
Language independent text can be provided as 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 accounts 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.
The AttachmentFolder node element can be used to add and remove account attachments.
Data for this node can be found on the account 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 |
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> |