Show full documentation

 Show full documentation

Definition

An interface to manage contract data from an external system.

Business Context and Use

This web service is used to maintain contracts with data from an external consumer.

It has the MaintainBundle and the CheckMaintainBundle operations. The MaintainBundle operation is used to create or update one or more instances of the contract. The CheckMaintainBundle operation is used to check if the one or more instances of the contract can be maintained.

The signatures of the two operations are identical.

Example

The following example creates a contract with an external ID and customer data:

<n0:ContractBundleMaintainRequest_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global">
 <BasicMessageHeader>
  <ID>00163E07C0211ED49CF7337A5935C13B</ID>
 </BasicMessageHeader>
 <Contract actionCode="01">
  <ObjectNodeSenderTechnicalID>one</ObjectNodeSenderTechnicalID>
  <ID>XYZ1</ID>
  <BuyerID>X123</BuyerID>
  <Name>Standard Service Contract</Name>
  <Date>2014-11-01</Date>
  <ValidityStartDate>2014-11-10</ValidityStartDate>
  <ValidityEndDate>2015-11-09</ValidityEndDate>
  <TimeZoneCode>CET</TimeZoneCode>
  <ServiceLevelObjectiveID>STD_1</ServiceLevelObjectiveID>
  <BuyerParty>
   <BusinessPartnerInternalID>XC6049</BusinessPartnerInternalID>
  </BuyerParty>
  <Text actionCode="01">
   <TypeCode>10024</TypeCode>
   <CreationDateTime>2014-11-21T12:00:00.1234567Z</CreationDateTime>
   <Content>information for customer</Content>
  </Text>
 </Contract>
</n0:ContractBundleMaintainRequest_sync>

Prerequisites

Technical Prerequisites:

This web service must be activated within a communication arrangement maintained for the scenario Manage Contracts.

Existence of master data:

All master data are only referenced, and will not be created by the service operations. They must already exist in the system at the time the web service is called:

• Customers

• Employees used as Administrators

• Organizational Management Data

• Materials, Registered Products, Installation Points or Installed Bases used as Covered Objects

• Service Levels

• Products and Product Categories used in Items or Item Entitled Products

More Information

General Information

You can find general information about Web services, their structure and consumption in the Web Services documentation.

Scenarios

Possible scenarios include the following:

• Create Contracts

Operation MaintainBundle is used to create contracts.

• Update Contracts

Operation MaintainBundle is used to update existing contracts.

For a complete roundtrip, service interface QueryContractIn can be used to read contract data.

Examples

 Show full documentation

 Show full documentation

Definition

To create and update one or more contracts using imported structured data.

Business Context and Use

This operation is used to create or update one or more instances of a contract.

The request message of the operation MaintainBundle contains a BasicMessageHeader node element, as well as a Contract node element containing the contract data to be created or updated. The detailed structure of the contract node will be explained in the following sub-chapters. The contract node can occur multiple times in the request message, meaning that multiple contracts can be created and updated by a single web service call.

The response message of the operation MaintainBundle contains log items, processing information, and a contract-specific node with ReferenceObjectNodeSenderTechnicalID, ChangeStateID; as well as contract ID and contract UUID.

Structure

Contract

The Contract node element contains basic information about the contract such as ID, name, dates, servicel level, and status. Together with customer and administrator which are mentioned below, these fields can be found in the list of contracts in the contracts work center, or they will appear when creating a new contract. The UUID element is not visible on the UI, but can be retrieved using web service Query Contract In.

Note: When creating contracts using this operation, the contract ID is internally determined by the system if not explicitly specified.

Note: The contract UUID is read-only, and cannot be set by an external application when creating contracts.

Note: Either UUID or ID can be used to specify a contract which shall be updated or deleted.

Example

Update a contract, identified using UUID, with a different subject:

<Contract actionCode="02">
  <UUID>00163E07-C021-1ED4-9CF7-C70E2541E268</UUID>
  <Name>changed name</Name>
</Contract>

Example

Update a contract, identified using ID, with a different name:

<Contract actionCode="02">
  <ID>1234</ID>
  <Name>changed name</Name>
</Contract>

The BuyerID element can be found as External Reference in the UI. It is a unique identifier for a contract assigned by the customer.

The Date element corresponds to the Signed On attribute in the UI. The ValidityStartDate and ValidityEndDate elements are named Begins On and Ends On in the UI.

The input format is expected in the following format:

CCYY-MM-DD

The TimeZoneCode element applies to all three dates.

It can be considered to represent the location where the contract has been signed. In addition, it is used to determine at which point in time the validity of a contract begins or ends.

Example

Create a contract with dates:

<Contract actionCode="01">
  <Date>2014-11-01</Date>
  <ValidityStartDate>2014-11-10</ValidityStartDate>
  <ValidityEndDate>2015-11-09</ValidityEndDate>
  <TimeZoneCode>CET</TimeZoneCode>
</Contract>

The lifecycle status code can occur with the following values:

Status Code	Description
1	In Preparation
2	Active
3	Blocked
4	Obsolete
5	Ready

In the UI, it is called Status.

Note: It is not necessary to specify the LifeCycleStatusCode element when a new contract shall be created. The lifecycle status will be automatically set to its default value 1.

Note: When the lifecycle status code is used, the system will check if the corresponding action is allowed for this contract. If not, the system will return an error message.

Note: When contract approval has been selected in business configuration, it is not possible to directly activate a contract.

If the CurrencyCode element is not provided it will be determined from the customer.

Buyer Party and Seller Party

The BuyerParty node element contains the customer for which the contract has been created. The BusinessPartnerInternalID element corresponds to the customer ID in the user interface.

The optional SellerParty node element represents the own company. In the UI, it can be entered in the Involved Parties as party with the role Seller. The BusinessPartnerInternalID element corresponds to the company ID in the value help.

Administrator Party

The AdministratorParty node element contains basic information about the administrator responsible for the contract.

In the employee UI, the EmployeeID can be displayed for the contract administrator.

Alternatively, the BusinessPartnerInternalID element can serve to identify the administrator of the contract.

Note: If both elements are provided, the employee ID is the default value. In this case, the BusinessPartnerInternalID will be automatically determined by the system.

Example

  <AdministratorParty>
   <EmployeeID>7000039</EmployeeID>
  </AdministratorParty>

Contracting Unit Party

The ContractingUnitParty node element represents the contracting unit the contract is assigned to. The OrganisationalCentreID element specifies the ID of the organizational unit.

Example

  <ContractingUnitParty>
   <OrganisationalCentreID>C007</OrganisationalCentreID><!-- ID of contract department -->
  </ContractingUnitParty>

Sales Unit Party

The SalesUnitParty can be used to identify the sales unit responsible for the contract. The OrganisationalCentreID element specifies the ID of the organizational unit.

Example

  <SalesUnitParty>
   <OrganisationalCentreID>D009</OrganisationalCentreID><!-- ID of sales unit -->
  </SalesUnitParty>

Other Party

In the OtherParty node element, parties with customer-defined party roles can be specified. The role has to be transmitted, using the PartyRoleCode element. Depending on the type of the party, the EmployeeID or BusinessPartnerInternalID identifies the party.

For the interdependency of both elements, see above (Administrator Party).

Covered Object

The CoveredObject node element specifies which objects are covered by a contract. When covered objects are specified, the coverage of the contract is restricted to the listed covered objects. When no covered objects are specified, the coverage is not limited.

A covered object can be a product, a registered product, an installation point or an installed base. The MaterialID element corresponds to the Product ID; the IndividualProductSerialID element corresponds to the Serial ID in the UI.

Note: Either a product or a registered product can be specified, however, not both at the same time. However, the Product ID element has to be supplied when a serial ID is not unique.

Note: When a registered product belongs to an installed base, the installation point and installed base will be found automatically.

When an installation point is entered which carries a registered product, serial ID and product will be found automatically.

Example

  <CoveredObject actionCode="01">
   <ProductID>MCF-0003</ProductID>
   <IndividualProductSerialID>MC6129-MCF-0003-SID2</IndividualProductSerialID>
   <InstallationPointID/>
   <InstalledBaseID/>
  </CoveredObject>

Item

The Item node element contains the items (entitlements) of the contract.

If the ID element is not specified when creating an item, the system will propose a value. On the UI, the ID element is displayed as Line.

If the Description element is not specified when creating an item, it will be defaulted from the product description.

ValidityStartDate and ValidityEndDate elements are named Begins On and Ends On in the UI. Their input format is expected in the format CCYY-MM-DD. The validity periods of the items must be within the validity period of the contract header.

The ProductID element identifies a product, which is part of the contract and represents an entitlement.

RequestedQuantity and QuantityMeasureUnitCode elements appear as Quantity on the user interface.

The WarrantyGoodwillCode element is displayed as Coverage on the user interface. For example, it can be used to specify that all services and parts which belong to an item are fully covered by the contract.

For the LifeCycleStatusCode element, please refer to the Contract section above.

Note: For service contracts, at least one entitled product must be specified under the item in the ItemEntitledProduct node element.

Item Entitled Product

The ItemEntitledProduct node element represents the parts and services a customer is entitled to release with reference to a contract item.

Either the ProductID element can be specified or the ProductCategoryInternalID element, however not both at the same time.

Note: In case the entitled products of an item shall be updated, it is necessary to set the itemEntitledProductListCompleteTransmissionIndicator attribute to true.

Example

  <Item actionCode="02" itemEntitledProductListCompleteTransmissionIndicator="true">
   <ObjectNodeSenderTechnicalID>Item 14</ObjectNodeSenderTechnicalID>
   <ID>14</ID>
   <ItemEntitledProduct actionCode="04">
    <ObjectNodeSenderTechnicalID>ItEntP 1</ObjectNodeSenderTechnicalID>
    <ProductID>MCF-0001</ProductID>
    <ProductCategoryInternalID/>
   </ItemEntitledProduct>
  </Item>

Item Usage Restriction

With the ItemUsageRestriction node element you can restrict the context in which this contract item can be used in ticket items.

The possible values for contract usage restrictions are defined by the customer in business configuration.

Note: When usage restrictions are specified, the coverage of the contract item is restricted to the listed usages. When no usage restrictions are specified, the usage of the item not limited to a specific context.

Note: If the usage restrictions of an item are updated, set the itemUsageRestrictionListCompleteTransmissionIndicator attribute to true.

Example

Replace all usage restrictions for an item:

  <Item actionCode="02" itemUsageRestrictionListCompleteTransmissionIndicator="true">
   <ObjectNodeSenderTechnicalID>Item 14</ObjectNodeSenderTechnicalID>
   <ID>14</ID>
   <ItemUsageRestriction>
    <ObjectNodeSenderTechnicalID>Usage Restr ZZZ1</ObjectNodeSenderTechnicalID>
    <UsageRestrictionCode>ZZZ1</UsageRestrictionCode>
   </ItemUsageRestriction>
  </Item>

Example

Delete a specific usage restriction from an item:

  <Item actionCode="02" itemUsageRestrictionListCompleteTransmissionIndicator="false">
   <ObjectNodeSenderTechnicalID>Item 14</ObjectNodeSenderTechnicalID>
   <ID>14</ID>
   <ItemUsageRestriction actionCode="03">
    <ObjectNodeSenderTechnicalID>Usage Restr ZZZ1</ObjectNodeSenderTechnicalID>
    <UsageRestrictionCode>ZZZ1</UsageRestrictionCode>
   </ItemUsageRestriction>
  </Item>

Text

Using the Text node element, communication with the customer, as well as internal information can be stored.

The ID element identifies a line in the list of texts. It cannot be externally set when creating a text. It must be used to address the line for which data shall be changed or deleted.

The different types of text are distinguished via the TypeCode element. The following values can exist:

Type Code	Description
10011	Internal Comment
10024	Customer Information

With the CreationDateTime element, the original text creation timestamp can be specified. The input format is expected in UTC in the following format:

CCYY-MM-DDThh:mm:ss(.sss)Z

The part (.sss) stands for fractions of seconds, and is optional.

The text content itself is stored as plain text in the Content element.

Note: The internal comment as well as the customer information can occur only once in one instance of a contract.

Note: All texts are language-independent.

Example

Add an internal comment and change another text specified by ID:

  <Text action code="01">
   <TypeCode>10011</TypeCode>
   <CreationDateTime>2015-03-28T12:00:00Z</CreationDateTime>
   <Content>... covered objects not yet completely maintained ...</Content>
  </Text>
  <Text actionCode="02">
   <ID>00163E028B121ED1B2D287F8D2B9E1AA00163E028B121ED1B2D29D7C425FA1D4T00002</ID>
   <Content>... some corrected text...</Content>
  </Text>

Attachment Folder

Links or file attachments can be added or removed using the AttachmentFolder node element.

AttachmentFolder can occur only once. It can contain several attachments together with their attributes.

The UUID element of the attachment folder must be specified when changes in the list of documents shall be made.

The UUID is not visible on the UI. However, it can be retrieved using the Query Contract In web service interface.

Note: The UUID element cannot be specified when creating an attachment folder.

Important Note

Within the AttachmentFolder node element and its subnodes, the ActionCode attributes have to be specified with a capital "A".

Example

Delete all existing attachments and replace by a new one:

  <AttachmentFolder DocumentListCompleteTransmissionIndicator="true" ActionCode="02">
   <UUID>00163E02-E0F6-1ED1-B4AE-C44BAD505361</UUID>
   <Document ActionCode="01">
     <CategoryCode>2</CategoryCode>
     <MIMECode>text/plain</MIMECode>
     <Name>attachment_test.txt</Name>
     <AlternativeName>attachment_test.txt</AlternativeName>
     <FileContent>
       <BinaryObject fileName="attachment_test.txt" mimeCode="text/plain">SW5ib3VuZCBhdHRhY2htZW50IHRlc3Q=</BinaryObject>
     </FileContent>
    </Document>
  </AttachmentFolder>

Document

The Document node element contains the attachment information.

The UUID element serves to address a specific line in the list of documents. For example, it has to be specified when a document shall be changed or deleted.

Example

Delete an attachment:

  <AttachmentFolder DocumentListCompleteTransmissionIndicator="false" ActionCode="02">
   <UUID>00163e02-e0f6-1ed1-b4ae-c44bad505361</UUID>
   <Document ActionCode="03">
     <UUID>00163e02-8b30-1ee1-b4b0-3de4b08a65d1</UUID>
   </Document>
  </AttachmentFolder>

Do not specify the following elements:

• LinkInternalIndicator

• VisibleIndicator

The values will be internally set, independent of the web service input.

The CategoryCode element indicates whether a document is a folder, link, or file:

Category Code	Description
1	File
2	Document
3	Link

In this context, values 2 (Document) and 3 (Link) can be used. Entries with category code 1 will not be displayed on the UI.

Example

  
<CategoryCode>3</CategoryCode>  

The TypeCode element can contain the following values:

Type Code	Description
10001	Standard Attachment
10009	Summary
10087	Graphical Signature of Buyer

If no document type code is specified upon creation, the system will assume a standard attachment.

Note: After the action Preview is performed on the UI, a summary of the contract can be viewed and stored as PDF in the local file system. Then you can upload it as attachment of type 10009 (Summary). Currently, this is a manual process.

Example

Add a standard attachment to an existing attachment folder:

  
  <AttachmentFolder DocumentListCompleteTransmissionIndicator="false" ActionCode="02">
   <UUID>00163E02-E0F6-1ED1-B4AE-C44BAD505361</UUID>
   <Document ActionCode="01">
     <CategoryCode>2</CategoryCode>
     <TypeCode>10001</TypeCode>
     <MIMECode>text/plain</MIMECode>
     <Name>attachment_test.txt</Name>
     <AlternativeName>attachment_test.txt</AlternativeName>
     <FileContent>
       <BinaryObject>SW5ib3VuZCBhdHRhY2htZW50IHRlc3Q=</BinaryObject>
     </FileContent>
    </Document>
  </AttachmentFolder>

Note: The document type code cannot be changed.

The Name, AlternativeName and Description elements serve to further describe the attachment. The AlternativeName element can be found as Title on the UI. The Name element is not visible on the UI. However, it is used for internal purposes, and is therefore mandatory.

Example

  
<Name>Document Name</Name>
<AlternativeName>My Document Title</AlternativeName> 

Do not specify the Property node element. It is not used.

Some elements become mandatory, dependent on the document category. They are described in the following sections.

Document with File Content

You can embed file content into the payload using the following tags:

The MIMECode element describes the medium type of the binary content according the corresponding MIME type recommendations.

Example

 <MIMECode>text/plain</MIMECode>  

Remark: The available MIME codes for attachment upload can be restricted by business configuration in the activity Allowed MIME Types for Document Upload. Usage of a MIME type that is not allowed does not become immediately visible. A contract is created. However, the attachment does not contain the data. Therefore, we recommend that you check the allowed MIME types first.

The FileContent node element contains the binary content itself in the BinaryObject element. It must be encoded in Base64 format.

The additions like mimeCode and fileName are optional.

Example

 
<FileContent>
<BinaryObject mimeCode="text/plain" fileName="test.txt">Q29uZ3JhdHVsYXRpb25zISBXaGVuIHlvdSByZWFkIHRoaXMsIHRoZSB1cGxvYWQgd2FzIHN1Y2Nlc3NmdWwu</BinaryObject>
</FileContent> 

Document as Link

Instead of file content, a link can be added. In this case, the ExternalLinkWebURI element must be provided.

Example

  
<ExternalLinkWebURI>http://qwertjkl/anyURI</ExternalLinkWebURI>  

Example XML for attachments

The first document references a URL, the second contains a plain text file content.

  <AttachmentFolder ActionCode="01">
   <Document ActionCode="01">
    <CategoryCode>3</CategoryCode>
    <Name>link name</Name>
    <AlternativeName>link title</AlternativeName>
    <Description languageCode="EN">link comment</Description>
    <ExternalLinkWebURI>http://qwertjkl/anyURI</ExternalLinkWebURI>
   </Document>
   <Document ActionCode="01">
    <CategoryCode>2</CategoryCode>
    <MIMECode>text/plain</MIMECode>
    <Name>test.txt</Name>
    <AlternativeName>test file</AlternativeName>
    <Description languageCode="EN">My comment for the test file</Description>
    <FileContent>
    <BinaryObject>Q29uZ3JhdHVsYXRpb25zISBXaGVuIHlvdSByZWFkIHRoaXMsIHRoZSB1cGxvYWQgd2FzIHN1Y2Nlc3NmdWwu</BinaryObject>
  </FileContent>
 </Document>
</AttachmentFolder> 

 Show full documentation

 Show full documentation

Definition

To check if contract data can be created or updated without errors.

Business Context and Use

The web service request and response message types of the CheckMaintainBundle operation are the same as those of the MaintainBundle operation.

The explanations given can therefore also be applied to the CheckMaintainBundle operation.