| Description | Query Goods And Service Acknowledgement |
| Name | QueryGoodsAndServiceAcknowledgementInbound |
| Namespace | http://sap.com/xi/A1S/Global |
| Process Component Description | Goods And Service Acknowledgement Processing |
| Process Component Name | GoodsAndServiceAcknowledgement |
| Process Component Namespace | http://sap.com/xi/AP/Purchasing/Global |
| Deployment Unit Description | Purchasing |
| Endpoint Activation | By Scoping of Process Component | Operations |
| Release Status | Released |
An interface to query Goods and Service Acknowledgment from a source system.
The web service Interface Query GoodsAndServiceAcknowledgement In enables you to connect external applications to your SAP Business By Design system and to query GSA in your system. The web service interface Query GoodsAndServiceAcknowledgement In is relevant if your company wants to access GSA data from external applications.
In the Purchase Requests and Orders work center, if you accept changes to the PO acknowledgment, the system updates the original purchase order.
Query selection parameters are mainly exposed as select options or ranges, with an inclusion/exclusion code, interval boundary type code, lower boundary value, and upper boundary value.
The inclusion/exclusion code (element name InclusionExclusionCode) specifies the inclusion or exclusion of a set in a result set.
| Inclusion Exclusion Code | Description |
|---|---|
| E | Excluding |
| I | Including |
The interval boundary type code (element name IntervalBoundaryTypeCode) is used to describe intervals by their boundaries. Depending on the operator, the lower boundary value or both boundary values are relevant.
| Interval Boundary Type Code | Name | Description | Logical Operator |
|---|---|---|---|
| 1 | Equal to | Single Value | =X |
| 2 | Between(Excluding upper boundary) | Interval with closed lower and open upper boundary | [X, Y) |
| 3 | Between | Interval with open lower and open upper boundary | (X, Y) |
| 4 | Between (excluding both boundaries) | Interval with open lower and open upper boundary | (X, Y) |
| 5 | Between (excluding lower boundary) | Interval with open lower and closed upper boundary | (X, Y] |
| 6 | Less than | Interval with unlimited lower and open upper boundary | < X |
| 7 | Less than or Equal to | Interval with unlimited lower and closed upper boundary | <= X |
| 8 | Greater than | Interval with open lower and unlimited upper boundary | > X |
| 9 | Greater than or Equal to | Interval with closed lower and unlimited upper boundary | = X |
TransmissionRequestCode specifies which elements shall be returned. The valid code values for the TransmissionRequestCode are:
| Code | Description | "Short form" |
|---|---|---|
| 1 | The node element, all its elements and its child node elements and all their elements shall be returned. | All |
| 2 | The node element and all its elements shall be returned. | Current node |
| 3 | The node element and its key elements shall be returned. | Current node keys only |
| 4 | The node element and its child node elements shall not be returned. | Ignore |
Each TransmissionRequestCode is assigned to a specific message node.
The transmission request code is optional. If no transmission request code is modeled or provided by the service consumer, then the following rules apply:
1.If no transmission request code is provided at all, then the response message contains all data.
2.If the transmission request code of the parent node element is '1', then its sub-node elements for which no transmission request code is specified are defaulted by '1'.
3.If the transmission request code of the parent node element is '2' or '3', then its sub-node elements for which no transmission request code is specified are defaulted by '4'.
4.If the transmission request code of the parent node element is '4', then its sub-node elements are not returned anyway.
Before a query is executed on GSA , instance of GSA has to be created and maintained first.
Action codes represent an instruction to the recipient of the web service request to process transmitted message node elements.
The action code to be used is ‘QUERY_BY_ELEMENTS’.
Optional leaf elements in request messages that are not transmitted within a web service request are not considered while querying. So any value of missing parameters would meet the comparison.
Query operation is stateless synchronous web service operation. Transferring or requesting amounts of data that are too large causes communication timeouts. The web service consumer is responsible for ensuring reasonable sizes of data for mass operations.
The structure of the request message type consists of two parts:
• Selection parameters for the query
• Processing conditions. This specifies the limit on the output i.e number of records returned. You can also specify if you want unlimited number of records.
Many external applications consuming web services have special requirements and restrictions regarding the format of WSDLs. Some external applications require service definition WSDLs describing the web service signature. This is normally sufficient for the creation of static client-side proxies. Other external applications, normally those that do not create static client-side proxies, require binding WSDLs including the endpoint definition and authentication policy information.
In both cases, it may be the case that the external application imposes special restrictions on the structure or the size of WSDLs.
Microsoft InfoPath requires binding WSDLs and considers elements with the attribute "minOccurs=0" as "mandatory". However "minOccurs=0" means "optional" in SAP web services. In order to circumvent this problem, the WSDL must be saved locally and an additional attribute "nillable=true" must be added to make a query parameter optional for Microsoft InfoPath.
For very small clients such as mobile devices, the size of the WSDL itself may become a problem. In most cases the client only requires a very small part of the signature, but due to the complexity of the WSDL they may end up with long runtime during serialization of the request or deserialization of the response. In order to circumvent this problem, the WSDL must be saved locally and the optional parts of the signature have to be removed before the WSDL is imported or static client-side proxies are generated.
External applications have to take into account that web service request and response message types can be enhanced with additional elements and attributes. Enhancements can be created by SAP, SAP partners, and key users. Enhancements of request message types are always optional elements or attributes. The SAP system does not require the external application to provide values in the request. Enhancements of response message types can contain mandatory elements or attributes. The external application must be able to process the extended response successfully.
XML element and attribute names are always stable. Technical definitions of data types can be enhanced in a compatible way. This may result in changed data type names. External applications can rely on XML element names and attribute names, but should not rely on data type names.
Note: You can download the WSDL file for any web service here:
• Application and User Management work center -> Input Output Management -> Communication Arrangement.
• User Management work center -> Service Explorer view.
You can find the documentation of the global data types in the SAP Community Network: Go to http://scn.sap.com/docs/DOC-17516 and click View Document.
You can find general information about Web services, their structure and consumption in the Web Services documentation.
Possible scenarios include the following:
• Find GSA based on certain set of information like parties, location etc.
This finds the GSA that has life cycle status equal to 1
<n0:GSASimpleByElementsQuery_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <GSASimpleSelectionByElements> <SelectionByStatusGoodsAndServiceAcknowledgementLifeCycleStatusCode> <InclusionExclusionCode>I</InclusionExclusionCode> <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode> <LowerBoundaryGoodsAndServiceAcknowledgementLifeCycleStatusCode>1</LowerBoundaryGoodsAndServiceAcknowledgementLifeCycleStatusCode> </SelectionByStatusGoodsAndServiceAcknowledgementLifeCycleStatusCode> <ProcessingConditions> <QueryHitsMaximumNumberValue>10</QueryHitsMaximumNumberValue> <QueryHitsUnlimitedIndicator>false</QueryHitsUnlimitedIndicator> </ProcessingConditions> </GSASimpleSelectionByElements> </n0:GSASimpleByElementsQuery_sync>
| Description | Find goods and service acknowledgement |
| Name | FindSimpleByElements |
| Synchronous | yes |
| Release Status | Released |
QueryGSAIn interface allows to query on existing GSA in the system.
The request message of the QueryByElements contain two parts: Body and Processing Conditions. Body comprises of the various parameters on which GSA can be queried. Details on these parameters is discussed in the following sub-sections. Processing conditions controls the execution of query. For example you can specify if you want a certain number of records as output or unlimited records should be shown.
The response message contain the header level relevant attributes of GSA along with the processing conditions. The processing condition here indicates that how many records are returned and are there any more records existing which meet the criteria but not fetched.
The search can contain complex criteria instead of having simple equation. You can get results based on ‘equal to’ or a Range or Less than or greater than logical operations. These type codes should be specified in the request message.
The web service Query GoodsAndServiceAcknowledgement In offers the operation QUERY_BY_ELEMENTS.
Structure of the request message has the following parameters based on which GSA can be searched:
| Element | Remark |
|---|---|
| SelectionBySearchText | You can specify anything in this text and if this text exists for any GSA it will show up in result |
| ID | Id of the GSA |
| SystemAdministrativeDataCreationDateTime | Creation date of GSA |
| SystemAdministrativeDataLastChangedDateTime | Last changed date of GSA |
| ItemDeliveryPeriodStartDateTime | GSA delivery start date time |
| ItemDeliveryPeriodEndDateTime | GSA delivery end date time |
| TypeCode | TypeCode of the GSA |
| CurrencyCode | Currency of GSA |
| TransactionDateTime | Date when the GSA was created |
| SupplierCommonBusinesspartnerFormattedName | Supplier name in GSA |
| Name | GSA text |
| TotalNetAmount | Total value of GSA |
| BuyerPartyKeyPartyID | Company ID of GSA |
| EmployeeResponsiblePartyKeyPartyID | Purchaser in GSA |
| PartyResponsiblePurchasingUnitPartyKeyPartyID | Purchasing Unit in GSA |
| PartySellerPartyKeyPartyID | Supplier Id in GSA |
| Approval Status | Approval related status of GSA |
| DeliveryProcessingStatus | The status of processing the delivery of GSA. It could be NotStarted, Partially Delivered, Not relevant or Completed. |
| DelievryStatusCode | The status of delivery. Not started, Delivered or Partially delivered |
| GSALifeCycleStatusCode | The life cycle status of GSA. It could be In preparation, In approval, Sent, Canceled, Finished etc.... |
| ItemAccountingCodingBlockTYpe | The type of accounting object of GSA item |
| ItemAccountingCodingBlockDistributionItemCostCentreId | Cost center of item |
| ItemAccountingCodingBlockDistributionItemProjectReferenceProjectId | Project to which GSA Item is accounted |
| ItemAccountingCodingBlockDistributionItemSAlesOrderReferenceID | Sales Order to which Item is accounted to |
| ItemDeliveryPeriod | The delivery start and end dates of GSA Item. |
| ItemDescription | The Product description |
| ItemLocationShipToLocationID | Ship to location of GSA item |
| ItemPartyProductRecipientPartyKeyPartyID | Recipient of the product |
| ItemPartyServicePerformerPartyKeyPartyID | ServiceAgent in the GSA item |
| ItemProductCategoryID | Product category of the GSA Item |
| ItemProductProductRequirmentSpecificationKey | Product Requirements Specification ID of Product |
| ItemTypeCode | Type of GSA Item |
| GSADocumentrefernce* | Reference to PO document. |
The response consists of root level element of GSA. Following are the major attributes in result:
The GSA node elements contain all general information such as ID, names, TypeCode and business partners. The data of this node is related to the General Data on the GSA UI.
| Element | Remark |
|---|---|
| GSA ID | The the internal ID with which the GSA can be addressed and found |
| Posting Date | The posting date of GSA |
| Supplier Party | The supplier ID |
| BuyerParty | This is the buying company |
| Delivery note ID | Outbound delivery note ID for GSA |
| PO reference ID | Original PO number which GSA comes from |
| Seller Party | The supplier to whom the purchase document is raised |
| TextCollection | Maintain notes on GSA Header |
| AttachmentFolder | Maintain Attachment on GSA header |
| ChangeStateID | Change State ID on GSA header |
| Code | Description |
|---|---|
| 1 | In Preparation |
| 2 | In Approval |
| 3 | In Revision |
| 4 | Rejected |
| 5 | Released |
| 6 | Canceled |
| 7 | Partially Canceled |
| 8 | Preparation Finished |
| 9 | Approved |
| 10 | Partial Cancellation Requested |
| 11 | Cancellation Requested |
| 12 | Goods Returned |
| 13 | Approval Withdrawn |
| 14 | Discarded |
| Party Type Code | Description |
|---|---|
| 154 | Company (Buyer Party |
| 410 | Purchasing Unit |
| 266 | Supplier |
| 167 | Employee |
The AttachmentFolder node element can be used to add and remove GSA attachments. Data for this node can be found on the GSA 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
| TypeCode | Description |
|---|---|
| 10001 | Standard Attachment |
| 10068 | Internal Attachment |
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> |
This node is used to maintain notes on GSA Header or Item Level. There are different types of notes supported in GSA:
| TypeCode | Description |
|---|---|
| 10011 | Internal comment from the Purchase |
| 10014 | Remark for Supplier |
| 10015 | Remark from Supplier |
| 10029 | Approval Note |
This node has information relevant for the GSA items like the product, quantity, price, various item statuses, quantity delivered, quantity invoiced etc. The attributes here can be seen on the Items view of the GSA UI.
Following are some of the important attributes on Item node:
| Element | Remark |
|---|---|
| ItemID | This is the serial no of the item in GSA and is unique |
| TypeCode | Item Type Code |
| Description | The product description |
| Quantity | Quantity of product of the item in GSA |
| QuantityTypeCode | Quantity Type Code |
| NetAmount | The Net value of GSA item |
| NetUnitPrice | The Net Unit Price of GSA item |
| GrossAmount | The Gross Amount of GSA item |
| GrossUnitPrice | The Gross Unit Price of GSA item |
| ListUnitPrice | The List Amount of GSA item |
| LimitAmount | The Limit Amount of GSA item |
| ItemProduct | The product ID |
| ShipToLocation | Ship to Location of GSA item |
| CustomerParty | Customer which an item should be delivered to |
| RequestorParty | Requester ID |
| ProductRecipientParty | Recipient ID |
| DeliveryPeriod | The time frame in which the goods must be delivered |
| ItemIndividualMaterial | Individual Material of GSA item |
| ItemAttachmentFolder | Maintain Attachment on GSA Header |
| ItemTextCollection | Maintain notes on GSA Header |
| PurchaseOrderReference | Original PO number and item number GSA's item corresponds to |
There are multiple parties that are relevant at item level. Each item can be delivered to a different address and hence the address is derived from the parties or location at item level. Following parties and type codes are important at item level:
| PartyTypeCode | Description| |
|---|---|
| 167 | Requester or Recipient or Service Agent |
| 159 | End Buyer (Customer) |
Location Codes applicable for GSA are
| TypeCode | Description |
|---|---|
| 1 | Ship To Location |
| 2 | Ship From Location |
| 3 | Receiving Location |
The node contains the cost assignment of the GSA item. The cost can be assigned to following types of cost objects:
| TypeCode | Description |
|---|---|
| CC | Cost Center |
| ACC | General Ledger |
| IMAT | Individual Material |
| PRO | Project Task |
| SLS | Sales Order |
| SRV | Service Order |
Here is an example of a simple web service request:
Web service request
<n0:GSASimpleByElementsQuery_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global"> <GSASimpleSelectionByElements> <SelectionByID> <InclusionExclusionCode>I</InclusionExclusionCode> <IntervalBoundaryTypeCode>1</IntervalBoundaryTypeCode> <LowerBoundaryID>21</LowerBoundaryID> </SelectionByID> <ProcessingConditions> <QueryHitsMaximumNumberValue>1</QueryHitsMaximumNumberValue> <QueryHitsUnlimitedIndicator>false</QueryHitsUnlimitedIndicator> </ProcessingConditions> </GSASimpleSelectionByElements> </n0:GSASimpleByElementsQuery_sync>
Web service response
<n0:GSASimpleByElementsResponse_sync xmlns:n0="http://sap.com/xi/SAPGlobal20/Global" xmlns:prx="urn:sap.com:proxy:ACL:/1SAI/TAS1E95C8E04F2CDE79E3FF:804"> <GSA> <GSAID>21</GSAID> <GSAUUID>00163e06-66fc-1ee5-bdb3-f9d459d49641</GSAUUID> <PostingDate>2016-03-29</PostingDate> <GSAStatus> <LifeCycleStatusCode>2</LifeCycleStatusCode> <ApprovalStatusCode>3</ApprovalStatusCode> <CancellationStatusCode>1</CancellationStatusCode> <ConsistencyStatusCode>3</ConsistencyStatusCode> <GoodsReturnStatusCode>1</GoodsReturnStatusCode> <ReleaseStatusCode>1</ReleaseStatusCode> </GSAStatus> <SupplierParty> <PartyUUID>00163e06-66fc-1ee5-bdb3-f9d459d4f641</PartyUUID> <PartyTypeCode>266</PartyTypeCode> <AddressReference> <AddressHostUUID>00145ef5-88e6-02db-b8e1-91e842bd4788</AddressHostUUID> </AddressReference> <PartyKey> <PartyTypeCode>147</PartyTypeCode> <PartyID>QMC7000</PartyID> </PartyKey> </SupplierParty> <POID>60</POID> <Item> <ItemID>1</ItemID> <ItemUUID>00163e06-66fc-1ee5-bdb3-f9d459dc1641</ItemUUID> <TypeCode>18</TypeCode> <Description>Monitor 17''</Description> <Quantity unitCode="EA">4.0</Quantity> <QuantityTypeCode>EA</QuantityTypeCode> <NetAmount currencyCode="USD">800.0</NetAmount> <NetUnitPrice> <Amount currencyCode="USD">200.0</Amount> <BaseQuantity unitCode="EA">1.0</BaseQuantity> <BaseQuantityTypeCode>EA</BaseQuantityTypeCode> </NetUnitPrice> <ItemProduct> <ProductRequirementSpecificationKey> <RequirementSpecificationID>AXUS-M923</RequirementSpecificationID> </ProductRequirementSpecificationKey> </ItemProduct> <ProductRecipientParty> <PartyKey> <PartyID>MC2471</PartyID> </PartyKey> </ProductRecipientParty> <DeliveryPeriod> <StartDateTime timeZoneCode=" ">2016-03-29T15:17:22Z</StartDateTime> <EndDateTime timeZoneCode=" ">2016-03-30T15:17:22Z</EndDateTime> </DeliveryPeriod> <ItemAccountingCodingBlockDistribution> <UUID>00163e06-66fc-1ee5-bdb3-f9d459dc1641</UUID> <CompanyID>MC10000</CompanyID> <GeneralLedgerAccountAliasContextCodeElements> <UsageCode>5</UsageCode> </GeneralLedgerAccountAliasContextCodeElements> <HostObjectTypeCode>56</HostObjectTypeCode> <TotalAmount currencyCode="USD">800.0</TotalAmount> <TotalQuantity unitCode="EA">4.0</TotalQuantity> <AccountingCodingBlockAssignment> <Percent>100.0</Percent> <Amount currencyCode="USD">800.0</Amount> <Quantity unitCode="EA">4.0</Quantity> <AccountingCodingBlockTypeCode>CC</AccountingCodingBlockTypeCode> <CostCentreID>MC21100</CostCentreID> <CompanyID>MC10000</CompanyID> </AccountingCodingBlockAssignment> </ItemAccountingCodingBlockDistribution> <PurchaseOrderReference> <BusinessTransactionDocumentReference> <ID>60</ID> <UUID>00163e06-66fc-1ee5-bdb3-e997ba95d639</UUID> <TypeCode>001</TypeCode> <ItemID>1</ItemID> <ItemUUID>00163e06-66fc-1ee5-bdb3-eb78170dd639</ItemUUID> <ItemTypeCode>18</ItemTypeCode> </BusinessTransactionDocumentReference> </PurchaseOrderReference> </Item> <Item> <ItemID>2</ItemID> <ItemUUID>00163e06-66fc-1ee5-bdb3-f9d459dbf641</ItemUUID> <TypeCode>18</TypeCode> <Description>APPROXIMAL Designer 2.0</Description> <Quantity unitCode="EA">4.0</Quantity> <QuantityTypeCode>EA</QuantityTypeCode> <NetAmount currencyCode="USD">12000.0</NetAmount> <NetUnitPrice> <Amount currencyCode="USD">3000.0</Amount> <BaseQuantity unitCode="EA">1.0</BaseQuantity> <BaseQuantityTypeCode>EA</BaseQuantityTypeCode> </NetUnitPrice> <ItemProduct> <ProductRequirementSpecificationKey> <RequirementSpecificationID>AXUS-M933</RequirementSpecificationID> </ProductRequirementSpecificationKey> </ItemProduct> <ProductRecipientParty> <PartyKey> <PartyID>MC2471</PartyID> </PartyKey> </ProductRecipientParty> <DeliveryPeriod> <StartDateTime timeZoneCode=" ">2016-03-29T15:17:22Z</StartDateTime> <EndDateTime timeZoneCode=" ">2016-03-30T15:17:22Z</EndDateTime> </DeliveryPeriod> <ItemAccountingCodingBlockDistribution> <UUID>00163e06-66fc-1ee5-bdb3-f9d459dbf641</UUID> <CompanyID>MC10000</CompanyID> <GeneralLedgerAccountAliasContextCodeElements> <UsageCode>5</UsageCode> </GeneralLedgerAccountAliasContextCodeElements> <HostObjectTypeCode>56</HostObjectTypeCode> <TotalAmount currencyCode="USD">12000.0</TotalAmount> <TotalQuantity unitCode="EA">4.0</TotalQuantity> <AccountingCodingBlockAssignment> <Percent>100.0</Percent> <Amount currencyCode="USD">12000.0</Amount> <Quantity unitCode="EA">4.0</Quantity> <AccountingCodingBlockTypeCode>CC</AccountingCodingBlockTypeCode> <CostCentreID>MC21100</CostCentreID> <CompanyID>MC10000</CompanyID> </AccountingCodingBlockAssignment> </ItemAccountingCodingBlockDistribution> <PurchaseOrderReference> <BusinessTransactionDocumentReference> <ID>60</ID> <UUID>00163e06-66fc-1ee5-bdb3-e997ba95d639</UUID> <TypeCode>001</TypeCode> <ItemID>2</ItemID> <ItemUUID>00163e06-66fc-1ee5-bdb3-ec6c514b9639</ItemUUID> <ItemTypeCode>18</ItemTypeCode> </BusinessTransactionDocumentReference> </PurchaseOrderReference> </Item> <ChangeStateID> </ChangeStateID> </GSA> <ResponseProcessingConditions> <ReturnedQueryHitsNumberValue>1</ReturnedQueryHitsNumberValue> <MoreHitsAvailableIndicator>false</MoreHitsAvailableIndicator> <LastReturnedObjectID>00163E0666FC1EE5BDB3F9D459D49641</LastReturnedObjectID> </ResponseProcessingConditions> <Log/> </n0:GSASimpleByElementsResponse_sync>
| Release | Change Description | Details |
| 1805 | Documentation change | Service Interfaces and Operation , Structure of request message and response message, Example of payload updates |
Show full documentation
Show full documentation