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
}

Adding or Modifying Text

[20.0]

To work with text, provide a JSON object that contains the text you would like to add. The JSON object should provide the following properties:

Property Explanation Example
TEXT HTML text, including tags. Some text
more text.
SIGNATURE Determines whether to appends the user’s signature to the the inserted text. Possible values are true or false false
APPEND Determines whether the text will replace the existing text or be appened to it. Possible values are true or false true

Notes:

Example:

PATCH serviceroot/ORDERS('SO20000422')/ORDERSTEXT_SUBFORM
Content-Type: application/json
Authorization: Basic YXBpZGVtbzoxMjM=

  {
      "TEXT": "This is my order. <br> There are many like it, but this one is mine.",
      "APPEND": true,
      "SIGNATURE": false
  }

Response Payload

{
    "@odata.context": "serviceroot/$metadata#ORDERS('SO20000422')/ORDERSTEXT_SUBFORM/$entity",
    "TEXT": "<style> p,div,li {margin:0cm;font-size:10.0pt;font-family:'Arial';}li > font > p {display: inline-block;}</style><p dir=rtl><p dir=rtl>This is my order.<br> There are many like it, but this one is mine.</p> <p dir=rtl><font color=\"#0000ff\"><p dir=\"ltr\"><!--pdt-->06/04/20 14:00<!--edt--></p><p dir=\"ltr\">This is how the text looks like when retrieved by the REST API.&nbsp;</p><p dir=\"ltr\"><!--psi-->Sincerely,</p><p dir=\"ltr\">A Humble Documentarian</p><p dir=\"ltr\"></p><p dir=\"ltr\"><!--esi--></p></font><hr ss=\"\">&nbsp;<p dir=\"rtl\"><font color=\"#0000ff\"></font></p><p dir=\"rtl\" style=\"direction: ltr;\"><br></p> </p> ",
    "APPEND": null,
    "SIGNATURE": null
}

Text Only Forms

Certain specialized text forms in Priority operate in Text-only mode (the :$.NOHTML.T variable is set to 1 for this form). In this case, the text retrieved will not contain any HTML tags, and line breaks are represented by \n.

When working with these forms, inputted text should be in plain text only. Additionally, these forms do not support signatures, and as such SIGNATURE is always treated as false.

Performing Batch Operations

19.1

$batch enables you to combine multiple requests into a single request and receiving multiple responses in a single response. For example, to path a part family and retrieve that part family with a single request such as in the request and response payload below.

For more information on $batch, see the official documentation on the OASIS website.

Batch commands are limited to 100 operations in one batch call.

The Priority REST API supports the following features of batch operations:

Note: Once a change is saved by Priority to the database, it cannot be undone (although it may be overwritten). As such, batch operations do not support rollback, be it of the entire batch or inidivdual atomicity groups.

POST serviceRoot/$batch

Request

{
  "requests": [{
    "method": "PATCH",
    "atomicityGroup": "g1",
    "url": "serviceRoot/FAMILY_LOG('765')",
    "headers": {
      "content-type": "application/json; odata.metadata=minimal; odata.streaming=true",
      "odata-version": "4.0"
    },
    "id": "g1-r1",
    "body": {
      "FAMILYNAME": "765",
      "FAMILYDESC": "My OData Family"
    }
    },
    {
      "id": "r8",
      "method": "GET",
      "url": "serviceRoot/FAMILY_LOG('765')",
      "headers": {
        "content-type": "application/json; odata.metadata=minimal; odata.streaming=true",
        "odata-version": "4.0"
      },
      "dependsOn": ["g1"]
    }]
  }

Response Payload

  --batchresponse_8e86ef59-cb2c-4e46-b442-c8919a2826e9
Content-Type: multipart/mixed; boundary=changesetresponse_8917b75c-eae7-42a0-bbd8-443db93f1ca6

--changesetresponse_8917b75c-eae7-42a0-bbd8-443db93f1ca6
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: g1-r1

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal; odata.streaming=true
OData-Version: 4.0

{"@odata.context":"https://www.eshbelsaas.com/ui/odata/Priority/tabmob.ini/usdemo/$metadata#FAMILY_LOG/$entity","FAMILYNAME":"765","FAMILYDESC":"My OData Family","EFAMILYDES":null,"TECHFLAG":null,"DEBITFLAG":null,"PROJPROCESS":null,"TECHNICIANLOGIN":null,"FTCODE":null,"FTNAME":null,"DISTRFLAG":null,"DUTYPERCENT":0.00,"DUTYPERCENT1":0.00,"DUTYPERCENT2":0.00,"DUTYPERCENTTYPE":null,"SELLFLAG":null,"NEGBALFLAG":null,"FORECAST":null,"PARTNAME":null,"PARTDES":null,"STORAGETYPECODE":null,"STORAGETYPEDES":null,"SERIALMONTHEXPIRY":null,"ISMFAMILY":null,"MFAMILYNAME":null,"MFAMILYDES":null,"INACTIVE":null,"METERFLAG":null,"FAMILY":198}
--changesetresponse_8917b75c-eae7-42a0-bbd8-443db93f1ca6--
--batchresponse_8e86ef59-cb2c-4e46-b442-c8919a2826e9
Content-Type: application/http
Content-Transfer-Encoding: binary

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>