Retrieving Items (Raw Data)

Records stored on Orgvue's servers contain only raw data. Any calculated properties that depend on the dataset hierarchy or other properties are not stored, as they are always ultimately determined by the raw data. For example, a property age that is calculated from date of birth is not stored on the server, but date of birth itself would be. This is logical as you would never want to change someone's date of birth and not have it reflected as a change in their age.

We refer to records in their raw form as items, each item containing only stored values for the record. When using the export API endpoint, calculated properties are evaluated on the fly. But when updating the values stored within Orgvue you only interact with records at the item level. Calculated properties will always take care of themselves. It can be useful to retrieve items in this raw form; no calculations are made, and you can observe the pure stored values that might need updating.

Items can be retrieved using a synchronous call to the "Sync export excluding calculations" endpoint. To return all items with all properties a GET request should be used, while filtering is available via a POST.

Requesting all items (GET)

1. Authorize the request via a Bearer Token as with all other requests (see the Integration Guide).
2. Obtain the request URL by inserting your desired tenantId and datasetId into the endpoint path as described in the API Reference section. For example, if your tenantId is MY_TENANT and your datasetId is 123E4567-E89B-12D3-A456-426614174000 the URL would be .
3. Make a GET request to the URL.
4. Assuming the request succeeds you will receive a response with a 200 status code and the requested data will be be found in the response body. Items are returned in the jsonObject format: a JSON array of objects where the keys match the Orgvue property keys. For example:

[
  {
    "id": "a",
    "name": "Ana",
    "_id": "ED821EEB-0022-44A4-9469-ED90E4CDA8D8",
    "_sortOrder": 1,
    "_modifiedAt": "2023-01-18T18:42:13.089Z",
    "_access": "Item.delete"
  },
  {
    "id": "b",
    "name": "Bob",
    "parent_id": "a",
    "_id": "ED821EEB-014C-4D7D-8A04-86A768E6C8B2",
    "_sortOrder": 2,
    "_modifiedAt": "2022-12-07T16:53:58.588Z",
    "_access": "Item.delete"
  }
]

Note that empty properties will not be present on an item.

Filtering items (POST)

1. Authenticate your request and obtain the URL as described above.
2. Filter the data by supplying a filter and/or projection in the JSON payload. A sample payload might look like this:

   {
     "filter": {
       "name": "Ana"
     },
     "projection": {
       "id": 1,
       "name": 1
     }
   }
   Note that returned items are simple objects with keys, so column sort order has no meaning. Projection should just be used in this case to show desired columns. Also note that filter and projection objects are specified at the root level of the JSON payload.
3. Make a POST request to the URL including your JSON query payload.
4. Assuming the request succeeds you will receive a response with a 200 status code and the requested data will be be found in the response body.

Internal properties

In addition to user-defined properties, some additional internal properties are stored against each item:

Property Key	Description	Can Update?
_id	Orgvue internal unique identifier for this item	No
_sortOrder	The sort order of the records in this dataset	Yes
_access	Access permissions for this item	No
_modifiedAt	Date and time at which the record was last modified	No

In particular, the _id property can be useful to identify items for update, while the _modifiedAt property can be used to query records updated inside a certain time window.

note

These internal properties were initially always returned (if present) as core item information, even when not specified in the projection object. This behavior has since changed, and you will need to configure your projection accordingly.

Limitations

There is a 6MB upper limit to the size of a synchronous response. If your request is likely to exceed this limit you will need to filter the data.

Security and permissions

Items can be subject to a number of security rules around read and update.

It is possible to restrict permissions for certain properties, individual records and so on.

Usually rules are set up around Roles via Role Based Access Control (RBAC).

In special cases it may be necessary to use Attribute Based Access Control (ABAC).

Either of these can lead to restrictions on what certain users will be able to read and update.