Enterprise Documents Definition

The response model of the ObjectAPI

Enterprise Document description

The Response Model is basically the description of how an Enterprise Document looks like: the properties, property groups, and associations to different Enterprise Documents. For each endpoint, this response model controls what information can be used in the select, filter, and orderBy parameters.

OpenAPI definition

When preparing to call an ObjectAPI endpoint, it is important to investigate this response model. The image below shows a fragment of the response model for the Customers endpoint.

OpenAPI Schema Definition with custom annotations

In this response model, we can find a small description of each property and their data type. Additionally, custom annotations might be attached, indicating additional capabilities that can be used when requesting data from the ObjectAPI, or giving valuable information (for example, the combination of keys that makes an Enterprise Document unique).

Custom attributes

x-u4-key

Defines the combination of properties that makes an Enterprise Document unique.

"x-u4-key": {
    "keys": "companyId,customerId"
}

x-u4-filterable

Properties that are marked with this custom annotation can be used in a filter condition to restrict the list of returned Enterprise Documents. As a general rule of thumb, this is true for all properties, with exceptions being large text or image properties.

x-u4-describable

For properties that are marked with this custom annotation, we can request an optional description as well. We do this by using the suffix [T] (description only) or [C;T] (code and description). When a description is being requested, an additional property will be injected to the response object, for example customerGroupId(description) as shown in the example below. This annotation is always used in combination with x-u4-attribute or x-u4-valuelist.

 "x-u4-describable": {
    "propertyName": "customerGroupId(description)"
  }

curl -X GET \
  "https://unit4-api-address/v1/objects/customers\
        ?companyId=EN\
        &select=companyId,customerId,customerGroupId[C;T]\
        &filter=customerId eq 1" \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Accept-Encoding: gzip"

[
    {
        "companyId": "EN",
        "customerGroupId": "1",
        "customerGroupId(description)": "Domestic customers",
        "customerId": "1"
    }
]

x-u4-valueList

Properties that are marked with this custom annotation have values controlled by the value-list defined in the backend. This might be relevant information when setting up filters. To investigate the possible values, we can send an up-front request to the value-list endpoint. Once these values are known, they can be used as filters on the property that has this custom annotation.

"x-u4-valueList": {
  "valueList": "WF_STATE"
}

curl -X GET \
  "https://unit4-api-address/v1/objects/value-list\
        ?companyId=EN\
        &select=number,description,title\
        &filter=name eq 'STATUS' and language eq 'EN'" \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Accept-Encoding: gzip"

[
    {
        "description": "N",
        "name": "STATUS",
        "title": "Active"
    },
    {
        "description": "P",
        "name": "STATUS",
        "title": "Parked"
    },
    {
        "description": "C",
        "name": "STATUS",
        "title": "Closed"
    }
]

Note: The possible values that are required for filtering as returned by the value-lists call depend on the data type: use number for numeric fields and description for strings.

x-u4-attribute

Properties that are marked with this custom annotation are referring to attribute values (key concept in Unit4 ERPx). This might be relevant information when setting up filters. To investigate the possible values, we can send an up-front request to the attribute-values endpoint. Once these values are known, they can be used as filters on the property that has this custom annotation.

"x-u4-attribute": {
  "attributeId": "AJ"
}

curl -X GET \
  "https://unit4-api-address/v1/objects/attribute-values\
        ?companyId=EN\
        &select=attributeValue,periodFrom,description\
        &filter=attributeId eq 'AJ' and status eq 'N'" \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Accept-Encoding: gzip"

[
    {
        "attributeValue": "X1",
        "description": "British Customers",
        "periodFrom": 0
    },
    {
        "attributeValue": "X3",
        "description": "Cash Customers",
        "periodFrom": 0
    },
    {
        "attributeValue": "X4",
        "description": "Diverse Customers",
        "periodFrom": 0
    }
]

Then, we can use the returned attributeValue to filter the Customers object endpoint as shown below:

&filter=customerGroupId eq 'X3'

x-u4-relation

We can use the information provided by this custom annotation to investigate what relations are set up for this Enterprise Document.

"x-u4-relation": {
  "attributeId": "A4"
}

curl -X GET \
  "https://unit4-api-address/v1/objects/attribute-values\
        ?companyId=EN\
        &select=attributeValue,periodFrom,description\
        &filter=attributeId eq 'AJ' and status eq 'N'" \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Accept-Encoding: gzip"

x-u4-complextype

This custom annotation provides information about the properties inside this property group that are interconnected with each other and better be retrieved together. See below for the example of usage. In this example, even if only one property is requested, the endpoint still returns both attributeId and dimValue properties.

{
"U4ERP.Objects.GeneralLedgerTransaction.AccountingInformation.AccountingDimension1": {
    "type": "object",
    "properties": {
      "attributeId": {
        "title": "",
        "type": "string",
        "description": ". For more information please visit https://ontology-latest.u4pp.com/properties/attributeId",
        "x-u4-filterable": {
          "filterable": true
        }
      },
      "dimValue": {
        "title": "",
        "type": "string",
        "description": ". For more information please visit https://ontology-latest.u4pp.com/properties/dimValue",
        "x-u4-filterable": {
          "filterable": true
        }
      }
    },
    "description": "",
    "x-u4-complextype": {
      "isComplexType": true
    }
  }
}

U4 ERPx