Skip to main content

General Usage Information

The request and response JSON schemas can be found on our API Reference page. The API Reference page also contains documentation on the optional query parameters that allow for additional configuration of the data ingress to Orgvue.

Request Schema​

All of the item actions (create, update, delete etc.) share a number of validation rules which take place during the initial processing stages.

The rules are as follows:

  • The payload for each action must contain a unique identifier for the item and action.
  • If one or more additional properties are specified in the payload, each of the properties must exist in the dataset definition. You cannot create new properties and initialize them via the Items endpoint.
info

Please note that the synchronous PUT Items endpoint has a strict 6 MB size limit for request bodies. If your request exceeds this 6 MB limit, please use the asynchronous endpoint instead.

Access rules​

Access rules are a second stage validation process that checks if a user has access to the item/property and determines whether the user can perform the specified action. What happens when access to an item or property is denied can be broadly controlled by the onPropertyAccessDenied, onItemAccessDenied and onActionValidationFailure query parameters. By configuring these parameters you can decide whether the item/property that you specified should be skipped or if the entire transaction should fail when access to a specified item/property/action is denied. You can read more about these query parameters on the API Reference page.

Choosing the unique identifier for each item​

When forming the request payload, you can select one of three mutually exclusive ways to identify the dataset record to which the item action refers.

  1. Identify each item by providing one or more non-default unique identifiers in the payload. This can either be a pre-configured unique identifier property of your choice (using the autoId query parameter) or one or more properties (using the idKey query parameter).
  2. Identify each item by providing the Orgvue default unique identifier _id in the payload.
  3. Identify one or more items by providing a property value-like filter (using the mergeKey query parameter). Please note that in order to use a property as a merge key, the property must be tagged as "index". This condition does not apply for the _id property and the property which is configured as the auto id. Please see the Settings user guide for instructions on how to tag a property.

In the case of _id, autoId and idKey you must match each item in the payload to one dataset record each. mergeKey on the other hand should be used to perform batch updates. Both idKey and mergeKey can be provided multiple times in a payload, as per our examples page.

info

Please note that you cannot perform per-item and batch updates as part of the same request

Choosing the date format for each item​

You can present items in your payload in one of three supported date formats: YYYY-MM-DD,DD/MM/YYYY or MM/DD/YYYY. The date format is configurable via the dateFormat query parameter. All items must follow the date format specified.

Response Schema​

The response body contains an array of JSON objects (referred to hereafter as entries), where each entry corresponds to an item action in the initial request. Each of these entries will contain a unique identifier that distinguishes the record, an _action parameter which tells which item action was attempted, and a _status parameter which indicates if the action was successful or not. If the action was unsuccessful, the response object will also have a _failures parameter which contains an array of error objects.

A successful entry will look like this:

{
  "_status": "success",
  "_id": "7918D0B4-24AC-8A3E-E21C-1302FAE4937E",
  "_action": "update"
}

The status of the item update​

There are four possible statuses that can be returned as the result of an item operation.

  • success: The item action was successfully completed
  • partialSuccess: The item action was successful for some item properties, but failed for others. This can happen when a user has access to an item, but not all of its properties.
  • skipped: The item action was not attempted. This can happen when the action would not result in any changes, or if item/property access is denied and one or more of the query parameters controlling access rules is set to skipAction/skipProperty (the value depends on the parameter).
  • failed: The item operation was not successful.

Errors​

If an item action either fails or only partially succeeds, the entry for that action in the response object will also include a _failures parameter which contains one or more errors objects.

For example, if you attempt to delete an item using a non-existent _id the response will look like this:

[
  {
    "_status": "failed",
    "_failures": [
      {
        "message": "Item not found.",
        "code": 400804,
        "name": "ItemNotFound"
      }
    ],
    "_id": "AF4E6038-00CF-48F7-A682-AB073D02DADF",
    "_action": "delete"
  }
]

For information about specific errors, please see our Full list of API Errors page.