Priority Developer Portal

Requesting Data

OData services support requests for data via HTTP GET requests.

Requesting the Service Root

The request below returns a basic list of the resources available through the service. The response includes two types of links:

The $metadata document that describes the schema of the service.
Links to various collections of objects such as CUSTOMERS and ORDERS.

GET serviceRoot/

Response Payload

{
  "@odata.context": "serviceRoot/$metadata",
  "value": [
    {
      "name": "ABILITIES",
      "kind": "EntitySet",
      "url": "ABILITIES"
    },
  ...
    {
      "name": "CUSTOMERS",
      "kind": "EntitySet",
      "url": "CUSTOMERS"
    },
  ...
  {
      "name": "ORDERS",
      "kind": "EntitySet",
      "url": "ORDERS"
    },
  ...
  ]
}

Language

18.2

When working with a multi-lingual installation of Priority, you can specify which language to access the system by appending the appropriate language code to the service root URL, following the tabula.ini file name. This primarily affects the language used for error or warning messages returned from the system.

Example: https://www.example.com/odata/Priority/tabula.ini,3/test/CUSTOMERS('1234').

In this example, the system is being accessed in American English (language code 3). The Priority system manager can provide you with a list of language codes for the languages available in their particular system.

Decimals

‘22.0’ While the Priority system supports display of decimals using a variety of separators based on locale, to ensure consistency across languages, decimals in the REST API should always use a decimal point as the decimal separator. This is true for both the query URL and JSON body.

Requesting the Priority Version

‘22.0’

As some API features are restricted by the version of Priority on the sever, you may want to obtain this information and tailor your code accordingly.

You can obtain the Priority version with the following functions:

GET serviceRoot/GetPriorityVersion()

Response Payload

{
    "@odata.context": "serviceroot/$metadata#Edm.String",
    "value": "22.0-20.0.0.119"
}

The first number (22.0) is the Priority version. The second (20.0.0.119) is the server IP.

You can also request the OData version:

GET serviceRoot/GetODataVersion()

Response Payload

{
    "@odata.context": "serviceroot/$metadata#Edm.String",
    "value": "1.0.0.0"
}

Requesting the Service Metadata

The request below returns the $metadata document for the service. This document contains a machine-readable description of the service model, including entities, type schemas, and properties.

Note: Just as a database schema implies nothing of the business significance of the entities that it represents, the business significance of the entities and properties is not documented here.

GET serviceRoot/$metadata

Response Payload

<?xml version="1.0" encoding="utf-8"?>
<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
    <edmx:DataServices>
        <Schema Namespace="Priority.OData" xmlns="http://docs.oasis-open.org/odata/ns/edm">
            <EntityType Name="ABILITIES">
                <Key>
                    <PropertyRef Name="ABILITYCODE" />
                </Key>
                <Property Name="ABILITYCODE" Type="Edm.String" MaxLength="3" />
                <Property Name="ABILITYDES" Type="Edm.String" MaxLength="32" />
                <Property Name="ABILITY" Type="Edm.Int64" />
                <NavigationProperty Name="ABILITYVALUES_SUBFORM" Type="Collection(Priority.OData.ABILITYVALUES)" ContainsTarget="true" />
            </EntityType>
      ...
      <EntityContainer Name="DefaultContainer">
                <EntitySet Name="ABILITIES" EntityType="Priority.OData.ABILITIES" />
                <EntitySet Name="ABILITYVALUECODES" EntityType="Priority.OData.ABILITYVALUECODES" />
                <EntitySet Name="ABSENTCHART" EntityType="Priority.OData.ABSENTCHART" />
                <EntitySet Name="ABSENTCODES" EntityType="Priority.OData.ABSENTCODES" />
        ...
        <EntitySet Name="pDOCSTATS" EntityType="Priority.OData.pDOCSTATS" />
            </EntityContainer>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

Every EntityType represented in the data model comprises a set of Properties and NavigationProperties. They map to the Priority entities as follows:

API	Priority
EntityType	Form
Property	Field in a form
NavigationProperty	Sub-form

Properties

Each Property can have one of the following types:

Edm.DateTimeOffset
Edm.Decimal
Edm.Int64
Edm.String

Knowing the type of each property is important when filtering or adding entities because the way the values are represented depends on the type. Here are examples of how values should be represented, depending on their type:

Type	Example
Edm.Decimal	42.00
Edm.Int64	42
Edm.String	“A string”
Edm.DateTimeOffset	2017-04-16

Navigations properties have two types:

Collections

 <NavigationProperty Name="GENCUSTNOTES_SUBFORM" Type="Collection(Priority.OData.GENCUSTNOTES)" ContainsTarget="true" />

and non-collections

<NavigationProperty Name="SHIPTO2_SUBFORM" Type="Priority.OData.SHIPTO2" ContainsTarget="true" />

This distinction is important, as collections are represented as arrays, while non-collections are not.

Requesting Entity Collections

The request below returns the entity sets in the Part Families form, FAMILY_LOG.

Important: Currently, user requests via REST API are not subject to data privilege restrictions in Priority that they may be subject to when working in the Priority interface.

GET serviceRoot/FAMILY_LOG

Response Payload

{
    "@odata.context": "serviceRoot/$metadata#FAMILY_LOG",
    "value": [
        {
            "FAMILYNAME": "0",
            "FAMILYDESC": "Default part family",
             ...
            "FAMILY": -1
        },
...
        {
            "FAMILYNAME": "001",
            "FAMILYDESC": "Sound Systems",
    ...
        }
        }
    ]
}

Requesting an Individual Entity by ID

To get a particular entity from a collection, append a key segment. Key segments in OData services are bound by parentheses because they may be composite keys, e.g., OrderLine(OrderID=1,LineNumber=1).

The request below returns an individual entity from the LOGPART form by the given PARTNAME “111-012”.

GET serviceRoot/LOGPART('111-012')

Response Payload

{
  "@odata.context": "serviceRoot/$metadata#LOGPART/$entity",
  "PARTNAME": "111-012",
  "BARCODE": "111-012",
  "PARTDES": "Panasonic Black Blu-ray Disc Theater SCBT100",
  ...
  "EXTPART": 29
}

To access related entities, keep appending segments that represent valid property names as defined in $metadata or in a full metadata response. For example, the request below starts at the service root and navigates to the entity set FAMILY_LOG, then to the resource keyed ‘001’, and finally to the FAMILY_LOGPART_SUBFORM property. Note that the @odata.context URL self-describes the payload.

GET serviceRoot/FAMILY_LOG('001')/FAMILY_LOGPART_SUBFORM

Response Payload

{
  "@odata.context": "serviceRoot/$metadata#FAMILY_LOG('001')/FAMILY_LOGPART_SUBFORM",
  "value": [
    {
      "PARTNAME": "111-001",
      "TYPE": "P",
      "PARTDES": "Sony HT7100DH Home Theater",
      "STATDES": "In Use",
      "PART": 18
    },
    {
      "PARTNAME": "111-002",
      "TYPE": "P",
      "PARTDES": "Sony HT-DDW790 Home-theater",
      "STATDES": "In Use",
      "PART": 19
    },
    {
      "PARTNAME": "111-003",
      "TYPE": "P",
      "PARTDES": "Samsung HT-AS720 Home Theater",
      "STATDES": "In Use",
      "PART": 20
    }
  ]
}

Requesting Attachments

‘21.0’

Potentially Breaking Change

When requesting data that includes an attached file, the file is returned as a data URI. The request below shows the URIs of docx files attached to a customer order. Note that the URIs in EXTFILENAME have been trimmed to keep the example short.

This applies to any attached file, including images.

In previous versions of the API, attachments were returned as file paths.

GET serviceroot/ORDERS('SO21000113')?$select=CUSTNAME,ORDNAME&$expand=EXTFILES_SUBFORM

{
    "@odata.context": "serviceroot/$metadata#ORDERS(CUSTNAME,ORDNAME,EXTFILES_SUBFORM())/$entity",
    "CUSTNAME": "1004",
    "ORDNAME": "SO21000113",
    "EXTFILES_SUBFORM": [
        {
            "EXTFILEDES": "docx1",
            "EXTFILENUM": 3,
            "EXTFILENAME": "data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,UEsDBBQAAAAIAMhJhUzM9xURzwsAACxjAAATAAAAY3VzdG9tWG1sL2l0ZW0x...",
            "SUFFIX": "docx",
            "CURDATE": "2021-01-31T00:00:00+02:00",
            "NOSEND": null,
            "STATUS": null,
            "FILESIZE": 53803,
            "EI_COND": null,
            "USERLOGIN": "James",
            "UDATE": "2021-01-31T15:10:00+02:00",
            "LUSERLOGIN": null
        },
        {
            "EXTFILEDES": "docx1",
            "EXTFILENUM": 2,
            "EXTFILENAME": "data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,UEsDBBQAAAAIAMhJhUzM9xURzwsAACxjAAATAAAAY3VzdG9tWG1sL2l0ZW0xL...",
            "SUFFIX": "docx",
            "CURDATE": "2021-01-27T00:00:00+02:00",
            "NOSEND": null,
            "STATUS": null,
            "FILESIZE": 53803,
            "EI_COND": null,
            "USERLOGIN": "James",
            "UDATE": "2021-01-27T08:52:00+02:00",
            "LUSERLOGIN": null
        },
        {
            "EXTFILEDES": "docx1",
            "EXTFILENUM": 1,
            "EXTFILENAME": "data:application/vnd.openxmlformats-officedocument.wordprocessingml.document;base64,UEsDBBQAAAAIAMhJhUzM9xURzwsAACxjAAATAAAAY3VzdG9tWG1sL2l0ZW0xLnhtbO1...",
            "SUFFIX": "docx",
            "CURDATE": "2021-01-26T00:00:00+02:00",
            "NOSEND": null,
            "STATUS": null,
            "FILESIZE": 53803,
            "EI_COND": null,
            "USERLOGIN": "James",
            "UDATE": "2021-01-26T12:48:00+02:00",
            "LUSERLOGIN": null
        }
    ]
}

Requesting Text

‘20.0’

Requesting text is similar to requesting a related entity. The request below returns the text for order SO20000422.

GET serviceroot/ORDERS('SO20000422')/ORDERSTEXT_SUBFORM

The response contains a JSON object with the ODATA context, and the entirety of the HTML text as a string in the TEXT property. The other two properties are used when adding text

Response Payload

{
    "@odata.context": "https://dev.eshbel.com/odata/Priority/tabdev.ini/test/$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><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> ",
    "APPEND": null,
    "SIGNATURE": null
}

18.1

The OData service supports retrieving a record alongside its subform records in a single request, using the $expand system query option. The request below returns all ORDERITEMS_SUBFORM record for a specified ORDERS record:

GET serviceRoot/ORDERS('99100042')?$expand=ORDERITEMS_SUBFORM

Response Payload

{
  "@odata.context": "serviceRoot/$metadata#ORDERS/$entity",
  "CUSTNAME": "T000001",
  "CDES": "Joshua P. Atkins",
  ...
  "ORDERITEMS_SUBFORM@odata.context": "serviceRoot/$metadata#ORDERS('SO17000003')/ORDERITEMS_SUBFORM",
  "ORDERITEMS_SUBFORM": [
    {
      "PARTNAME": "TR0001",
      "PDES": "Almonds, mascarpone & strawberries tart",
      "TQUANT": 1,
      ...
    },
    {
      "PARTNAME": "FD0001",
      "PDES": "Phistacio Macrons with chocolate",
      "TQUANT": 1,
      ...
    }
  ]
}

You can specify mutliple subforms to be returned in the $expand option:

GET serviceRoot/ORDERS('99100042')?$expand=ORDERITEMS_SUBFORM,ORDERSTEXT_SUBFORM

You can use $expand to nest multiple levels of queries, retrieving information from a subform of a subform, or even deeper:

GET serviceRoot/ORDERS('SO20000422')?$expand=ORDERITEMS_SUBFORM($expand=ORDERITEMSTEXT_SUBFORM)

Response Payload

{
    "@odata.context": "https://www.eshbelsaas.com/ui/odata/Priority/tabmob.ini/usdemo/$metadata#ORDERS(ORDERITEMS_SUBFORM(ORDERITEMSTEXT_SUBFORM()))/$entity",
    "CUSTNAME": "0017F00002W6akoQ",
    "CDES": "marko enterprise",
    "CURDATE": "2020-06-22T00:00:00+03:00",
    "ORDNAME": "SO20000422",
    ...
    "ORDERITEMS_SUBFORM": [
        {
            "PARTNAME": "pt77",
            "PDES": "ptt77",
            ...
            "ORDERITEMSTEXT_SUBFORM": {
                "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\" style=\"direction: ltr;\">&nbsp;You reached this with multiple $expands, didn't you?</p> ",
                "APPEND": null,
                "SIGNATURE": null
            }
        }
    ]
}

Requesting Full Metadata

By default, the OData service returns an extremely compact JSON format, by stripping out all the metadata that should be calculable by “smart” OData clients. For generic hypermedia clients, you can request additional metadata by using the Accept header, or $format system query option to request application/json;odata.metadata=full. The request below yields additional annotations in the payload, indicating type information and relationships to other resources.

GET serviceRoot/FAMILY_LOG?$format=application/json;odata.metadata=full

Response Payload

  {
  "@odata.context": "serviceRoot/$metadata#FAMILY_LOG",
  "value": [
    {
      "@odata.type": "#Priority.OData.FAMILY_LOG",
      "@odata.id": "serviceRoot/FAMILY_LOG('0')",
      "@odata.editLink": "FAMILY_LOG('0')",
      "FAMILYNAME": "0",
      "FAMILYDESC": "Default part family",
      ...
      "FAMILY@odata.type": "#Int64",
      "FAMILY": -1,
      "FAMILY_LOGPART_SUBFORM@odata.associationLink": "serviceRoot/FAMILY_LOG('0')/FAMILY_LOGPART_SUBFORM/$ref",
      "FAMILY_LOGPART_SUBFORM@odata.navigationLink": "serviceRoot/FAMILY_LOG('0')/FAMILY_LOGPART_SUBFORM",
      "FAMILYMALF_SUBFORM@odata.associationLink": "serviceRoot/FAMILY_LOG('0')/FAMILYMALF_SUBFORM/$ref",
      "FAMILYMALF_SUBFORM@odata.navigationLink": "serviceRoot/FAMILY_LOG('0')/FAMILYMALF_SUBFORM",
      "FAMILYSERVTYPES_SUBFORM@odata.associationLink": "serviceRoot/FAMILY_LOG('0')/FAMILYSERVTYPES_SUBFORM/$ref",
      "FAMILYSERVTYPES_SUBFORM@odata.navigationLink": "serviceRoot/FAMILY_LOG('0')/FAMILYSERVTYPES_SUBFORM",
      "FAMILYREQLABANALYSES_SUBFORM@odata.associationLink": "serviceRoot/FAMILY_LOG('0')/FAMILYREQLABANALYSES_SUBFORM/$ref",
      "FAMILYREQLABANALYSES_SUBFORM@odata.navigationLink": "serviceRoot/FAMILY_LOG('0')/FAMILYREQLABANALYSES_SUBFORM"
    },
    ......

Requesting Data

Requesting the Service Root

Language

Requesting the Priority Version

Requesting the Service Metadata

Properties

Navigation Properties

Requesting Entity Collections

Requesting an Individual Entity by ID

Navigating to Related Entities

Requesting Attachments

Requesting Text

Retrieve Related Entities Inline

Requesting Full Metadata