B1 Service Layer: Sample Payload of CRUD and How to find help
Tags:
Following by the document B1 Service Layer: Entity CRUD - Update by my colleague , in this document I would like to share the CRUD payload samples of most frequent objects such as BusinessPartners, Orders, UDO. And more importantly, how you can help yourself to find out the right object and payload in Service Layer.
- How to find help for Service Layer?
- Samples of CRUD payload for BusinessPartners Object
- Samples of CRUD payload for Orders Object
- Samples of CRUD payload for User Defined Object
- Samples of Querying Options in Service Layer
- Sample#13: Get the whole customer data for a given sales order
- Sample#14: Get the customer’s phone number for a given sales order
- Sample#15: Get a specific Sales Order only with its DocNum, DocTotal,DocDate and DocumentLines, also the foreign name of its customer.
- Sample#16: Get top 10 customers list by balance descending
- Sample#17: Grouping and Aggregation
How to find help for Service Layer?
Service Layer User Manual and API Reference is available in https://<YOUR_HANA_SERVER>:50000
To find out the right object and payload, you should refer to API Reference, they search by the the key word of the object.
For example, you could like to find out the object for AP Invoices, you may not be sure about the object as "APInvoices" or "PurchaseInvoices".
However, by searching by the key word "Invoices" you will be able find it out as "PurchaseInvoices".
Then you may wonder what is the object schema or payload sample for PurchaseInvoices.
You could find its object schema in the metadata https://<YOUR_HANA_SERVER>:50000/b1s/v1/$metadata
by searching the object keyword "PurchaseInvoices", you can find its object type as "Document".
However, I would recommend to find out a sample of the target object by calling GET as reference, which is more straightforward.
For example, to find the a sample payload of PurchaseInvoice, you can use the HTTP command below.
GET https://<YOUR_HANA_SERVER>:50000/b1s/v1/PurchaseInvoices(1)
Notes:
No all the objects in DI API now available in Service Layer. More objects exposed in Service Layer is still in process by SAP.
If you urgently need some objects to be accessible by Service Layer, you can post your request here.
Samples of CRUD payload for BusinessPartners Object
Note: If you copy the payload from the sample below, please pay attention to the comma, double quote etc, which may be changed in SCN document and need to replaced by your own if you encounter the error "invalid character or bad request" etc.
Sample#1: Get a Customer by the given CardCode ‘C20000’
GET https://<YOUR_HANA_SERVER>:50000/b1s/v1/BusinessPartners('C20000')
No body required
Sample#2: Add a new Customer
POST https://<YOUR_HANA_SERVER>:50000/b1s/v1/BusinessPartners
Raw Body as application/json format
{
"CardCode": "Z00006",
"CardName": "SL workshop India",
"CardType": "C"
}
Sample#3: Update the Customer its name and adding a bill-to and ship-to address
If you would like to update or delete a line, please refer to Sample#7
PATCH https://<YOUR_HANA_SERVER>:50000/b1s/v1/BusinessPartners('Z00006')
Raw Body as application/json format
{
"CardName": "SL workshop India-Updated",
"BPAddresses": [
{
"AddressName": "Bill To",
"Street": "4417 Stonebridge Rd",
"Block": "Suite 500",
"ZipCode": "18067",
"City": "SL",
"County": "SL",
"Country": "US",
"State": "PA"
},
{
"AddressName": "Ship To",
"Street": "4417 Stonebridge Rd",
"Block": "Suite 500",
"ZipCode": "18067",
"City": "SL",
"County": "SL",
"Country": "US",
"State": "PA"
}
]
}
Sample#4: Delete a Customer by the given CardCode ‘Z00006’
DELETE https://<YOUR_HANA_SERVER>:50000/b1s/v1/BusinessPartners('Z00006')
No body required
Samples of CRUD payload for Orders Object
Sample#5: Get a Sales Order by DocEntry
GET https://<YOUR_HANA_SERVER>:50000/b1s/v1/Orders(1)
No body required
Please specify the target DocEntry to be retrieved.
Sample#6: Add a Sales Order
POST https://<YOUR_HANA_SERVER>:50000/b1s/v1/Orders
Raw Body as Application/json format
{
"CardCode": "C20000",
"DocDueDate": "2016-08-18",
"DocumentLines": [
{
"ItemCode": "A00001",
"Quantity":"1"
},
{
"ItemCode": "A00002",
"Quantity":"1"
}
]
}
Sample#7: Update a Sales Order by Changing, Deleting and Adding line.
-Changing quantity in the first line of Sales Order
-Deleting the second line of Sales Order
-Adding a new line at the end
PATCH https://<YOUR_HANA_SERVER>:50000/b1s/v1/Orders(***)
HEADER parameter:
B1S-ReplaceCollectionsOnPatch=true
This will enable service layer to replace the collection object on patch.
Raw Body as application/json format
{
"Comments": "Change quantity for first line,Remove the second, insert a new line",
"DocumentLines": [
{
"LineNum": 0,
"Quantity":"2"
},
{
"ItemCode": "A00003",
"Quantity": 1
}
]
}
To update a line, you need to specify the target LineNum and fields to be updated
To delete a line, just remove the line object from the DocumentLines Array object.
To add a new line, just provide a new line with ItemCode and Quantity etc into DocumentLines Array object.
Sample#8: Copy a Sales Order to Delivery Note
POST https://<YOUR_HANA_SERVER>:50000/b1s/v1/DeliveryNotes
Body: //Please replace the BaseEntry with your own.
{
"CardCode": "C20000",
"DocDueDate": "2016-08-18",
"DocumentLines": [
{
"BaseType": 17,
"BaseEntry": 375,
"BaseLine": 0
},
{
"BaseType": 17,
"BaseEntry": 375,
"BaseLine": 1
}
]
}
Sample#9: Cancel or Close an open Sales Order
To Cancel:
POST https://<YOUR_HANA_SERVER>:50000/b1s/v1/Orders(375)/Cancel
To Close:
POST https://<YOUR_HANA_SERVER>:50000/b1s/v1/Orders(375)/Close
Note: Any other operation other than CRUD in Service Layer, please use POST verb.
Samples of CRUD payload for User Defined Object
As with regular entities, you can perform CRUD and query operations on UDOs
The name of the UDO entity is based on the UDO code, the EntityType is the main table name of UDO.
<EntitySet EntityType="SAPB1.MainTableName" Name="UDO_Code”/>
The following UDO sample use Purchase Quality Control as example to assure the quality of the receiving items after purchasing. To use the following samples, you need to follow the steps in the prerequisites. Or you can use your own example, just need to understand what the payload is.
Prerequisites:
Step 1: Create a Document UDO for Purchase Quality Control as below
| UDO definitions | |
|---|---|
| UDO Code | OPQC |
| UDO Name | PurchaseQC |
| Menu | Please put the menu of PurchaseQC between Purchase Orders and Good Receipt. |
Main UDT XXX_OPQC for UDO OPQC | ||
|---|---|---|
| UDT Name | Object Type | Description |
| XXX_OPQC | Document | PurchaseQC |
UDFs configuration | ||
| UDF Name | Description | Data Type |
| CardCode | Vendor | Varchar(15) |
| CardName | Name | Varchar(100) |
| DocDate | Posting Date | Date |
| RefNo | PO Ref NO | Varchar(10) |
Sub UDT XXX_PQC1 for UDO OPQC | ||
|---|---|---|
| UDT Name | Object Type | Description |
| XXX_PQC1 | Document_Rows | PurchaseQCLines |
UDFs configuration of XXX_PQC1 | ||
| UDF Name | Description | Data Type |
| ItemCode | Item Code | Varchar(20) |
| ItemDesc | Description | Varchar(100) |
| AcceptedQty | Accepted Qty | Quantity |
| RejectedQty | Rejected Qty | Quantity |
| Remarks | Remarks | Varchar(100) |
Step 2: Restart Service Layer to have the UDO meta data refreshed in Service Layer instances.
As a result, the UDO entity is created in the meta data of Service Layer.
<EntitySet EntityType="SAPB1.XXX_OPQC" Name="OPQC"/>
...
<EntityType Name="XXX_OPQC">
<Key>
<PropertyRef Name="DocEntry"/>
</Key>
...
<Property Name="XXX_PQC1Collection" Type="Collection(SAPB1.XXX_PQC1)"/>
<ComplexType Name="XXX_PQC1">
<Property Name="DocEntry" Nullable="false" Type="Edm.Int32"/>
<Property Name="LineId" Nullable="false" Type="Edm.Int32"/>
...
<Property Name="U_ItemCode" Type="Edm.String"/>
</ComplexType>
</EntityType>
Rules:
1.The entity name of UDO is its UDO code and its entity type as Main Table name, in this case, it is OPQC as entity and XXX_OPQC as its EntityType.
2.Entity OPQC has a collection object named XXX_PQC1Collection with EntityType as Collection(SAPB1.XXX_PQC1)
Name of collection object: <Sub_Table_Name>Collection, and table name as its EntityType.
Step 3: Create a Purchase Order within B1
Vendor: V10000
Item Quantity
A00001 10
A00002 5
The following samples will create/update Purchase QC record referring this purchase order.
Sample#10: Adding a new record into UDO
Before the formal Good Receipt, we start the Purchase QC process, and find 2 A00001 printers having defeat. So we would like to QC got tracked by adding a new record to the PurchaseQC UDO referring to the purchase order
The UDO code is used as the entity name in Service Layer for UDO, it is OPQC in our sample.
And OPQC UDO has collection object named XXX_PQC1Collection. XXX_PQC1 as the sub table of UDO for this collection object.
POST https://<YOUR_HANA_SERVER>:50000/b1s/v1/OPQC
{
"U_CardCode": "V10000",
"U_DocDate": "2016-05-15",
"U_RefNo": "105",
"XXX_PQC1Collection": [
{
"U_ItemCode": "A00001",
"U_AcceptedQty": 8,
"U_RejectedQty": 2,
"U_Remarks": “2 Printers have defeat in printing with color”
},
{
"U_ItemCode": "A0002",
"U_AcceptedQty": 5,
"U_RejectedQty": 0,
"U_Remarks": “Perfect”
}
]
}
Sample#11: Update a record in UDO
This sample only change the first line. And second line is kept as-is.
PATCH https://<YOUR_HANA_SERVER>:50000/b1s/v1/OPQC(1)
Body:
{
"U_DocDate": “2016-06-15”,
"XXX_PQC1Collection": [
{
"LineId": 1,
"U_ItemCode": "A10000",
"U_AcceptedQty": 10,
"U_RejectedQty": 0,
"U_Remarks": "All good now after reset those two printers"
}
]
}
If you would like to delete a line, please refer to Sample#7
Sample#12: Delete a record in UDO
DELETE https://<YOUR_HANA_SERVER>:50000/b1s/v1/OPQC(1)
No body required.
Samples of Querying Options in Service Layer
The following samples shows how to query in Service Layer, which is complaint with OData v3.0. You can find the all the query options in User Manual of Service Layer and standard oData query options document
The query options are all use HTTP GET verb only.
Sample#13: Get the whole customer data for a given sales order
This sample demonstrate the navigation object in OData
GET https://<YOUR_HANA_SERVER>:50000/b1s/v1/Orders(1)/BusinessPartner
Sample#14: Get the customer’s phone number for a given sales order
https://<YOUR_HANA_SERVER>:50000/b1s/v1/Orders(1)/BusinessPartner/Phone1
Sample#15: Get a specific Sales Order only with its DocNum, DocTotal,DocDate and DocumentLines, also the foreign name of its customer.
This sample demonstrate the navigation object in expand manner in OData
GET https://<YOUR_HANA_SERVER>:50000/b1s/v1/Orders(1)?$select=DocNum,DocTotal,DocDate,DocumentLines,BusinessPartner/CardForeignName&$expand=BusinessPartner
The following URL will return an error saying DocumentLines is an invalid navigation object in Orders. For DocumentLines in current Service Layer is only a sub object of Documents, not as a navigation.
https://<YOUR_HANA_SERVER>:50000/b1s/v1/Orders?$select=DocNum,DocTotal,DocDate,DocumentLines/ItemCode&$expand=DocumentLines,BusinessPartner/CardName&$expand=BusinessPartner
Sample#16: Get top 10 customers list by balance descending
This sample demonstrate the $select, $filter, $orderby and $top query options
GET
https://<YOUR_HANA_SERVER>:50000/b1s/v1/BusinessPartners?$select=CardCode,CardName,CurrentAccountBalance&$filter=CardType eq 'C'&$top=10&$orderby=CurrentAccountBalance desc
Sample#17: Grouping and Aggregation
Please refer to the documents by Andy below:
