Following by the document B1 Service Layer: Entity CRUD - Update by my colleague @Andy Bai, 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?

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

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:

B1 Service Layer: Grouping

B1 Service Layer: Aggregation