Modifying Data

The OData service supports Create, Update and Delete operations for some or all exposed entities. Please note that data modification via the API is only available in Priority version 17.2 and above.

Creating an Entity

To create an entity in a collection, the client sends a POST request to that collection’s URL. The POST body MUST contain a single valid entity’s information. The request below creates a new part family in the Part Families form.

POST serviceRoot/FAMILY_LOG 
OData-Version: 4.0
Content-Type: application/json;odata.metadata=minimal
Accept: application/json

{
    "FAMILYNAME": "765",
    "FAMILYDESC": "My OData Family"
}

Response Payload

{
  "@odata.context": "serviceRoot/$metadata#FAMILY_LOG/$entity",
  "FAMILYNAME": "765",
  "FAMILYDESC": "My OData Family",
  "EFAMILYDES": null,
  "TECHFLAG": null,
  "DEBITFLAG": null,
  "PROJPROCESS": null,
  ...
  "FAMILY": 26
}

To create an entity related to an entity (for example, an ORDERITEM that is part of an ORDER), navigate to the entity using its identifying key property, then specify the related resource in which to insert a new line.

POST serviceroot/ORDERS('SO18000002')/ORDERITEMS_SUBFORM 
Content-Type: application/json

{
  "PARTNAME": "TR0001",
  "TQUANT": 5,
  "DUEDATE": "2018-03-15T00:00:00+02:00"
}

Response Payload

{
    "@odata.context": "serviceroot/$metadata#ORDERS('SO18000002')/ORDERITEMS_SUBFORM/$entity",
    "PARTNAME": "TR0001",
    "PDES": "Almonds, mascarpone & strawberries tart",
    "TQUANT": 5,
    "TUNITNAME": "ea",
    "PRICE": 33,
    "ICODE": "$",
    "DUEDATE": "2018-03-15T00:00:00+02:00",
    ...
    "KLINE": 1
}

Composite Keys

Certain entities might have a composite key comprised of multiple properties.To specify a composite key, separate the different properties with a comma(,). Key property information is available in the $metadata of the entity.

POST serviceroot/AINVOICES(IVNUM='T9696',IVTYPE='A',DEBIT='D')/AINVOICEITEMS_SUBFORM  

Content-Type: application/json

{
  "PARTNAME": "TR0001",
  "TQUANT": 3,
}

You can create an entity with multiple related child entities (for example, an ORDER with the relevant ORDERITEMS). To do so, specify the values for the related resources as part of the request.

POST serviceRoot/ORDERS 
OData-Version: 4.0
Content-Type: application/json;odata.metadata=minimal
Accept: application/json
{
    "CUSTNAME": "007",
    "ORDERITEMS_SUBFORM": [
        {
            "PARTNAME": "111-001",
            "DUEDATE": "2016-08-01T00:00:00+03:00"
        },
        {
            "PARTNAME": "111-002",
            "DUEDATE": "2016-08-01T00:00:00+03:00"
        }
     ]
}

Response Payload

{
  "@odata.context": "serviceRoot/$metadata#ORDERS/$entity",
  "CUSTNAME": "007",
  "CDES": "ACME Inc.",
  "NAME": null,
  "POSITIONDES": null,
  "CURDATE": "2016-08-07T00:00:00+03:00",
  "ORDNAME": "SO16000007",
  "BOOKNUM": null,
  "DOCNO": null,
  "PROJDES": null,
  "ORDSTATUSDES": "Draft",
  "BOOLCLOSED": null,
  ...
  "PIKORDER": 0,
  "FOLLOWUPIV": 88
}

Updating an Entity

To update an existing entity, send a PATCH request with the values you wish to modify. You can also use PUT, but the semantics for PUT require all properties to be either sent on the wire or reverted to their default values.

PATCH serviceRoot/FAMILY_LOG('765')
OData-Version: 4.0
Content-Type: application/json;odata.metadata=minimal
Accept: application/json

{
    "FAMILYDESC": "My Updated Family"
}

Response Payload

{
  "@odata.context": "serviceRoot/$metadata#FAMILY_LOG/$entity",
  "FAMILYNAME": "765",
  "FAMILYDESC": "My Updated Family",
  "EFAMILYDES": null,
  "TECHFLAG": null,
  "DEBITFLAG": null,
  "PROJPROCESS": null,
  ...
  "FAMILY": 26
}

To update an entity related to an entity (for example, an ORDERITEM that is part of an ORDER), navigate to the entity using its identifying key property, then specify the related resource you are updating.

PATCH serviceroot/ORDERS('SO18000002')/ORDERITEMS_SUBFORM(1)
Content-Type: application/json
Authorization: Basic YXBpZGVtbzoxMjM=

{
  "TQUANT": 10,
}

Response Payload

{
    "@odata.context": "serviceroot/$metadata#ORDERS('SO18000002')/ORDERITEMS_SUBFORM/$entity",
    "PARTNAME": "TR0001",
    "PDES": "Almonds, mascarpone & strawberries tart",
    "TQUANT": 10,
    "TUNITNAME": "ea",
    "PRICE": 33,
    "ICODE": "$",
    "DUEDATE": "2018-03-15T00:00:00+02:00",
    ...
    "KLINE": 1
}

To update multiple related entities (for example, several ORDERITEMS for an ORDER), specify the values for the related resources as part of the request. Make sure to specify the key property identifying the entities you are updating.

PATCH serviceRoot/ORDERS(ORDNAME='SO17000004')
OData-Version: 4.0
Content-Type: application/json;odata.metadata=minimal
Accept: application/json

{      
    "ORDERITEMS_SUBFORM" : [
        {KLINE: "1", PARTNAME: "111-001", QUANT: 1},
        {KLINE: "2", PARTNAME: "111-002", QUANT: 2}
    ]
}

Writing to a Text Form

Making updates to a text subform is similar to updating multiple related entities. The maximum amount of characters for the “TEXT” field is specified in the $metadata file.

Note: Creating a new line using /n is unsupported and will generate an error.

The request below demonstrates adding text to the “Remarks” in the DOCUMENTS_D form:

PATCH /ui/odata/Priority/tabmob.ini/usdemo/DOCUMENTS_D(DOCNO='SH17000002',TYPE='D') HTTP/1.1
Host: www.eshbelsaas.com
Content-Type: application/json
Authorization: Basic YXBpZGVtbzoxMjM=
Cache-Control: no-cache
Postman-Token: 09860195-d461-a1ba-38cf-337080f9c341

{
    "DOCUMENTSTEXT_SUBFORM" : [
    {
        "TEXT": "<p>Test Line 1</p>",
        "TEXTLINE": 1
    },
    {
        "TEXT": "<p>Test Line 2</p>",
        "TEXTLINE": 2
    },
    {
        "TEXT":"<p>Test Line 3</p>",
        "TEXTLINE": 3
    }]
}

Deleting an Entity

To remove a resource, send an HTTP Delete to the resource URL.

DELETE serviceRoot/FAMILY_LOG('765')

To remove a related resource (e.g. an order item for a specific order), treat it as updating a related entity, specifying both the key for the resource and related resource.

DELETE serviceroot/ORDERS('SO18000002')/ORDERITEMS_SUBFORM(1)

Remember to take composite keys into consideration.

Error Handling

Since the API is essentially a wrapper around the Priority screens, any errors generated by the screens are included in the response. The example below demonstrates an attempt to create a new FAMILY_LOG entity with an invalid value for the DEBITFLAG field.

POST serviceRoot/FAMILY_LOG 
OData-Version: 4.0
Content-Type: application/json;odata.metadata=minimal
Accept: application/json

{
    "FAMILYNAME": "765",
    "FAMILYDESC": "My OData Family"
    "DEBITFLAG": "Q"
}

Response Payload

<FORM
  TYPE="FAMILY_LOG">
    <FAMILY_LOG>
        <FAMILYNAME>790</FAMILYNAME>
        <FAMILYDESC>My invalid OData Family</FAMILYDESC>
        <DEBITFLAG>Q</DEBITFLAG>
        <FAMILY>0</FAMILY>
    </FAMILY_LOG>
    <InterfaceErrors>
        <text>Specify 'N' or 'Y' as the default value that will be filled in the Billable column of the "Reports of Project Hrs/Expenses" form. /n Leave the column blank if you do not want to have a default.</text>
    </InterfaceErrors>
</FORM>