Description | Manage Service Agents |
Name | ManageServiceAgentIn |
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 service agent master data from a source system or file.
The web service interface Manage Service Agent In enables you to connect external applications to your SAP Business ByDesign system and to create and edit service agents in your system. The web service interface Manage Service Agent In is relevant if your company wants to access and manage business partner data from external applications.
The web service interface Manage Service Agent In offers the operations MaintainBundle and CheckMaintainBundle.
Here is an example of a simple web service request:
<n0:ServiceAgentBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <BasicMessageHeader/> <ServiceAgent actionCode="04"> <LifeCycleStatusCode>2</LifeCycleStatusCode> <GivenName>JIM</GivenName> <MiddleName>H</MiddleName> <FamilyName>SNABE</FamilyName> <BirthName>Birthname</BirthName> <NickName>Nickname</NickName> </ServiceAgent> </n0:ServiceAgentBundleMaintainRequest_sync>
Existence of referenced business documents:
While creating a service agent for a supplier, the following business documents are only referenced and will not be created by the service operations. These business documents should already exist in the system.
Supplier
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 service agents |
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 service agent |
Name | MaintainBundle |
Synchronous | yes |
Release Status | Released |
The request message of the operation MaintainBundle contains a BasicMessageHeader node element as well as a service Agent node element that contains the service agent data to be created or updated. The detailed structure of the service agent node will be explained in the following sub-chapters. The service agent node can occur multiple times in the request message – this means that multiple service agents 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 service agent-specific node with ReferenceObjectNodeSenderTechnicalID, ChangeStateID, as well as service agent InternalID and UUID.
The service agent node element can be used to create and change service agents. This contains all general service agent information, such as ID, UUID, names, and other identification data. The data for this node is related to General Data on the service agent UI. For service agent, the CategoryCode is 1.
The InternalID element corresponds to the Service Agent ID on the UI, - the UUID element is not visible on the UI, but can be retrieved using query and read web services.
Existing service agent can be assigned to supplier using the relationship and service performer node elements:
1. Relationship node element: Provide the RelationshipBusinessPartnerUUID or RelationshipBusinessPartnerInternalID elements to identify the related service agent and set RoleCode BUR025-2.
2. Service performer node element: Provide elements RelationshipBusinessPartnerUUID or the RelationshipBusinessPartnerInternalID to identify the related service agent. In addition, the actionCode must be set to 04 (save).
Service agent relations can be removed from a supplier using the relationship and service performer elements.
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 supplier UI.
By default, the service agent workplace address refers to the main/default supplier address of the supplier to which the service agent is assigned. If a supplier has multiple supplier addresses, the workplace address of the service agent can be related to a supplier address of your choice. To assign a service agent workplace address, enter the AddressInformation UUID of the supplier address in the WorkplaceBusinessAddressUUID element of the service agent.
The main private address and additional private addresses can be provided in the AddressInformation sub-node element of the service agent 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 service agent addresses.
Data for the AddressInformation node element is related to communication addresses data on the service agent 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 service agent 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 service agent UI.
To assign a service agent to a supplier, you need to provide a valid supplier ID in <RelationshipBusinessPartnerInternalID>. With that the service agent will be assigned to the supplier ID provided by you.
Language independent text can be provided as service agent 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 suppliers 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 service agent attachments.
Data for this node can be found on the service agent 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> |