Show full documentation

 Show full documentation

Definition

An interface to query contracts.

Business Context and Use

The web service interface Query Contract In enables you to connect external applications to your SAP system and to query and read contracts within your system. The web service interface Query Contract In is relevant if your company wants to access and manage contracts from external applications.

The web service interface Query Contract In offers the operation Find By Elements.

Prerequisites

Technical Prerequisites:

This web service must be activated within a communication arrangement maintained for the query contracts scenario.

Other Prerequisites:

Contracts should exist in the system in order to get a positive result.

More Information

General Information

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

Examples for Requested Elements

• All data (complete response):

Expected result:

<Contract>
    <full response... />
</Contract>

Request:

<RequestedElements contractTransmissionRequestCode="1">

or (default is '1')

<RequestedElements />

or just omit it (default is all)

 ... empty ... 

• Return everything except texts and attachments:

Expected result:

<Contract>
  <all... except text and attachment nodes />
</Contract>

Request:

<RequestedElements contractTransmissionRequestCode="2">
    <Contract textTransmissionRequestCode="4" attachmentFolderTransmissionRequestCode="4" />
</RequestedElements>

Return contract general data, buyer party data and covered objects:

Expected result:

 <Contract>
  <ID>TEST_1</ID>
  <UUID>00163e07-c274-1ed4-9fde-125f5a518965</UUID>
  <Name>test</Name>
  <Date>2014-12-21</Date>
  <etc./>
  <BuyerParty>
   <BusinessPartnerInternalID>...</BusinessPartnerInternalID>
   <MainContactParty>
    <BusinessPartnerInternalID>...</BusinessPartnerInternalID>
   </MainContactParty>
  </BuyerParty>
  <CoveredObject>
   <ProductID>...</ProductID>
   <IndividualProductSerialID>1234567</IndividualProductSerialID>
  </CoveredObject>
 </Contract>

Request:

 <RequestedElements contractRequestTransmissionRequestCode="2">
  <Contract businessTransactionDocumentReferenceTransmissionRequestCode="4" buyerPartyTransmissionRequestCode="1" sellerPartyTransmissionRequestCode="4" ... coveredObjectTransmissionRequestCode="1" 
itemTransmissionRequestCode="4" textTransmissionRequestCode="4" attachmentFolderTransmissionRequestCode="4"></Contract>
 </RequestedElements>

 Show full documentation

 Show full documentation

Definition

To find contracts by elements.

Business Context and Use

FindByElements is an operation to query contract data by the selection elements passed in the request.

Structure

Request

Contract Selection By Elements

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

Selection Parameter	Remark
SelectionByID	Contract ID
SelectionByContractLifeCycleStatusCode	Status code: 1 In Preparation, 2 Active, 3 Blocked, 4 Obsolete, 5 Ready
SelectionByApprovalStatusCode	Approval status code: 1 Not Started, 2 Approval Not Necessary, 3 In Approval, 4 Approved, 6 In Revision, 7 Withdrawn
SelectionByInformationLifeCycleStatusCode	Information lifecycle status: AC Active, AN Anonymized
SelectionByBuyerPartyID	Customer ID
SelectionByContactPartyID	Customer contact ID
SelectionByPartyID	Party ID
SelectionByPartyRoleCategoryCode	Party role category code: 1 Buyer Party = Customer, 2 Seller Party = Own company, 100 Other Party, 122 Administrator Party, 204 Contracting Unit Party
SelectionByCoveredObjectSerialID	Covered Object Serial ID
SelectionByCoveredObjectProductID	Covered Object Product ID
SelectionByCoveredObjectInstallationPointID	Covered Object Installation Point ID
SelectionByCoveredObjectInstalledBaseID	Covered Object Installed Base ID
SelectionBySearchText	Selection by search text (Basic Search)

Response

The response contains the found contracts and the processing conditions, such as ReturnedQueryHitsNumberValue, MoreHitsAvailableIndicator, and LastReturnedObjectID.

The service consumer can specify which node elements are delivered. For more information, see also interface documentation, section "Requested Elements".

Contract

In this node contains all found contracts, including their basic data according to the RequestedElements provided in the query request. This includes the ChangeStateID that may be needed for subsequent change requests using web services as well.

The Date, ValidityStartDate and ValidityEndDate elements are returned in the format CCYY-MM-DD. The TimeZoneCode element applies to all three dates.

The date time elements in the system administrative data are provided as UTC timestamps in the format CCYY-MM-DDThh:mm:ss.ffffffZ.

The part ffffff stands for fractions of seconds.

The BuyerID element can be found as External Reference in the user interface.

Business Transaction Document Reference

The BusinessTransactionDocumentReferenceID element contains the ID of a referenced document. The possible values for the BusinessTransactionDocumentReferenceTypeCode are

Type Code	Description
118	Ticket / Service Request
2004	Contract

The Business Transaction Document Relationship Role Code element can have the following values:

Role Code	Description
1	Predecessor
2	Successor

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 SellerParty node element represents the own company.

The AdministratorParty node element identifies administrator responsible for the contract.

The ContractingUnitParty node element represents the contracting unit the contract is assigned to.

The SalesUnitParty can be used to identify the sales unit responsible for the contract.

In the OtherParty node element, parties with customer-defined party roles can be specified.

Sales and Service Business Area

The SalesAndServiceBusinessArea node element can be used to specify the sales or service specific business area to which the contract belongs. It can be defined through the SalesOrganisationID, DistributionChannelCode and DivisionCode elements.

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 IndividualProductSerialID element corresponds to the Serial ID in the user interface.

Item

The Item node element contains the items (entitlements) of the contract. The ID element is displayed as Line on the user interface, RequestedQuantity and QuantityMeasureUnitCode elements appear as Quantity. ValidityStartDate and ValidityEndDate elements are returned in the format CCYY-MM-DD. They are are named Begins On and Ends On on the user interface.

The WarrantyGoodwillCode element is displayed as Coverage on the user interface.

Item Entitled Product

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

Single products are specified in the ProductID element. Alternatively, product categories can be specified as a whole, using the ProductCategoryInternalID element alone.

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.

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.

For the text TypeCode, the following values can exist:

Type Code	Description
10011	Internal Comment
10024	Customer Information
10029	Approval Note

In the CreationDateTime element, the text creation timestamp is returned in UTC in the following format:

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

The part (.sss) stands for fractions of seconds.

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

Attachment Folder

The Attachment Folder node element returns information on links and documents attached to the contract.

Note: The binary document content is not returned using this web service. Either the file content URI can be used to access the document, or another web service has to be used.

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) are used.

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

Example: Document information of a standard attachment

  <AttachmentFolder>
   <UUID>00163e02-8b12-1ed2-8bff-9ac970add60b</UUID>
   <Document>
    <UUID>00163e02-8b12-1ed2-8bff-9ac970aeb60b</UUID>
    <VersionID>0</VersionID>
    <SystemAdministrativeData>
     <CreationDateTime>2014-11-16T14:49:35.232901Z</CreationDateTime>
     <CreationIdentityUUID>00163e02-33f4-1ee1-81aa-311337aab123</CreationIdentityUUID>
     <LastChangeDateTime>2014-11-16T14:49:35.232901Z</LastChangeDateTime>
     <LastChangeIdentityUUID>00163e02-33f4-1ee1-81aa-311337aab123</LastChangeIdentityUUID>
    </SystemAdministrativeData>
    <VisibleIndicator>true</VisibleIndicator>
    <CategoryCode>2</CategoryCode>
    <TypeCode>10001</TypeCode>
    <MIMECode>text/plain</MIMECode>
    <PathName>/BOAttachments/00163E028B121ED28BFF9AC970ADD60B/attachment_test.txt</PathName>
    <Name>attachment_test.txt</Name>
    <AlternativeName>attachment_test.txt</AlternativeName>
    <Description>my attachment</Description>
    <FileContentURI>http://servername.domain:12345/sap/ap/ds/wd/doc/00163E028B121ED28BFF9AC970AEB60B/attachment_test.txt?sap-client=004</FileContentURI>
    <FilesizeMeasure unitCode="AD">23.0</FilesizeMeasure>
   </Document>
  </AttachmentFolder>

Example: Link information of a standard attachment

  <AttachmentFolder>
   <UUID>00163e02-8b32-1ed2-90dd-8662926d6477</UUID>
   <Document>
    <UUID>00163e02-8b32-1ed2-90dd-8662926e4477</UUID>
    <VersionID>0</VersionID>
    <SystemAdministrativeData>
     <CreationDateTime>2014-12-10T17:08:21.575777Z</CreationDateTime>
     <CreationIdentityUUID>00163e02-33f4-1ee1-81aa-311337aac123</CreationIdentityUUID>
     <LastChangeDateTime>2014-12-10T17:08:21.575777Z</LastChangeDateTime>
     <LastChangeIdentityUUID>00163e02-33f4-1ee1-81aa-311337aac123</LastChangeIdentityUUID>
    </SystemAdministrativeData>
    <VisibleIndicator>true</VisibleIndicator>
    <CategoryCode>3</CategoryCode>
    <TypeCode>10001</TypeCode>
    <PathName>/BOAttachments/00163E028B321ED290DD8662926D6477/link_test.txt</PathName>
    <Name>link_test.txt</Name>
    <AlternativeName>link_test.txt</AlternativeName>
    <Description>Home page</Description>
    <ExternalLinkWebURI>http://sap.com/anyURI</ExternalLinkWebURI>
    <FileContentURI>http://sap.com/anyURI</FileContentURI>
   </Document>
  </AttachmentFolder>