Query Parameters

Query parameters may be added to the request URL to provide additional controls to your API query

The table below contains the full list of query parameters that are supported by the Items endpoint

Parameter	Description
dateFormat	Date format used in parsing date values from strings
onPropertyAccessDenied	Controls behavior on a Property security access failure
onActionValidationFailure	Controls behavior on an Item Operation validation failure
onItemAccessDenied	Controls behavior on an Item security access failure
autoId	Specifies whether to use autoId to associate Item Operation to Item
idKey	Specifies whether to use keys to associate Item Operation to Item
mergeKey	Specifies whether to use keys to associate Item Operation to Item(s)
implicitDelete	Specifies whether to delete items not in the payload
noopToken	Specifies string value to result in no change to a value
clearToken	Specifies string values to clear out a value

AutoId

AutoId

When loading data into an Orgvue Dataset a unique identifier in the source data is selected as the Id property.

Within a people dataset this would be an employee number or payroll number while a Position Dataset will use a Position Number

This selected property from the source data is assigned as the autoId of the dataset

The autoId for a dataset may be viewed on the dataset metadata page in

Orgvue will also assign a unique identifier to every node to the _id property in the format 7918D0B4-24AC-8A3E-E21C-1302FAE4937E

When working with the "Sync import" endpoint the _id property is the default identifier used but setting autoId=true in the query parameter means that the autoId property will be used to identify the node

Base query example: https://{baseUrl}/api/v1/{tenantId}/datasets/{datasetId}/items

The JSON Payload below uses the default identifier _id

[
  {
    "_action": "update",
    "_id": "7918D0B4-24AC-8A3E-E21C-1302FAE4937E",
    "salary": 65000
  },
  {
    "_action": "delete",
    "_id": "ECFB8805-002D-441C-92AE-39FFE9D88A20"
  }
]

Adding the query parameter autoId=true to the query string https://{baseUrl}/api/v1/{tenantId}/datasets/{datasetId}/items?autoId=true allows the autoid property, employee_no in this example, to be used in the JSON payload

[
  {
    "_action": "update",
    "employee_no": "1122334",
    "salary": 65000
  },
  {
    "_action": "delete",
    "employee_no": "7653214"
  }
]

Duplicate Ids

onActionValidationFailure

When loading data via the Items endpoint the Orgvue API will deal with duplicate autoId or _id in the following scenarios

The data load will totally fail when:

• When there are duplicate autoIds or _ids in a payload then the complete data load will fail, however it will show which nodes failed and the nodes that would been successful if the duplicates were not present
• When there are duplicates autoIds already present in the Dataset you are loading data into, and you attempt to merge data against it then it will fail to load

The use of the query parameter ?onActionValidationFailure=skipAction in either of the above scenarios will ensure that all data will load except for the duplicates

In order to load data for the duplicates that were skipped the root cause of the error will need to be identified to establish if it is an issue with the payload or the target dataset and the duplicate removed to ensure only one record exists

Invalid Actions

onActionValidationFailure

An Item Operation can fail validation for a number of reasons, these include -

• Unsupported or missing Action
• Missing a relevant Id field
• Invalid sortOrder type
• Trying to create an item which already exists
• Trying to update or delete an item which does not exist

When set to its default value (failTransaction), the whole transaction will fail when you attempt one of these invalid actions

A 400 error response will be returned

The alternative is to set the value to skipAction to ignore the action if it is invalid, and complete the remaining actions requested in the payload

e.g., ?onActionValidationFailure=skipAction as query parameter

// 200 Response payload
[
  { "_id": "{uuid}", "_action": "create", "_status": "success" },
  {
    "_id": "{uuid}",
    "_action": "update",
    "_status": "skipped",
    "_failures": [
      {
        "name": "ActionIsForbidden",
        "code": 400803,
        "message": "Action for Item denied"
      }
    ]
  },
  { "_id": "{uuid}", "_action": "delete", "_status": "success" }
]

Item Access

OnItemAccessDenied

If a user is attempting to create, update or delete a record and they don’t have sufficient access rights, this will cause Item Access to be denied

When set to its default value of failTransaction, the whole transaction will fail when you attempt to update an item to which you do not have access

A 400 error response will be returned

Item Access can also be denied when the user is trying to update an items Property value and they don't have access for that property and onPropertyAccessDenied is set to denyItemAccess

By setting the value to skipAction Orgvue will ignore this one action if item access is denied, and complete remaining create, update or delete actions requested in the payload.

e.g., ?onItemAccessDenied=skipAction as query parameter

// 200 Response payload
[
  { "_id": "{uuid}", "_action": "create", "_status": "success" },
  {
    "_id": "{uuid}",
    "_action": "update",
    "_status": "skipped",
    "_failures": [
      {
        "name": "ActionIsForbidden",
        "code": 400803,
        "message": "Action for Item denied"
      }
    ]
  },
  { "_id": "{uuid}", "_action": "delete", "_status": "success" }
]

Property Access

onPropertyAccessDenied

When set to its default value (denyItemAccess), item access will be denied when you attempt to update a property you do not have access to

If onItemAccessDenied is also set to failTransaction, then whole transaction will fail with a 400 error response

The alternative is to set the value to skipProperty to ignore that property if access is denied.

Other properties will be updated, and the remaining create, update or delete actions requested in the payload will be completed

e.g., ?onPropertyAccessDenied=skipProperty as query parameter

// 200 Response payload
[
  { "_id": "{uuid}", "_action": "create", "_status": "success" },
  {
    "_id": "{uuid}",
    "_action": "create",
    "_status": "partialSuccess",
    "_failures": [
      {
        "name": "ItemPropertyUpdateForbidden",
        "code": 400807,
        "message": "Insufficient access to change Item properties",
        "properties": ["Salary", "ManagerId"]
      }
    ]
  },
  { "_id": "{uuid}", "_action": "delete", "_status": "success" }
]

No Operation Token

noopToken

You can specify string values which result in no change, in effect the key-values are ignored on your imported data.

tip

A No-op token always takes precedence over Clear Tokens, so you can set null or emptyString to be ignored rather than to remove a property value by stating is as a query parameter.

Examples:

?noopToken=IGNORE_ME use this to perform no operation on any cell containing the string IGNORE_ME

?noopToken=null or ?noopToken=emptyString using either of these query parameters will perform no operation on any cell that is blank instead of the default operation of clearing the existing value

Clear Token

clearToken

By default any cell in your import data that is null or empty will result in clearing any existing values in the dataset cells when imported

These default clear tokens may be overridden if used with a noopToken instead

You can also specify your own String values to represent clearing out a value.

If you wish to clear on the string value "null" or "emptyString" they should provide it with the double quotes as these represent reserved words.

Examples:

?clearToken=REMOVE_ME This example will clear the existing values in dataset for any cell in the imported data where the value is REMOVE_ME

?clearToken=null This is always the case but can be explicitly stated if required

?clearToken="null" This example will use the string value "null" to identify any data to be cleared

Actions

The table below contains the full list of actions that are supported by the Items endpoint for standard datasets using the various options for identifying items

For the actions available and recommended approach for Links datasets see Links Actions

The recommended method for identifying items with actions is to use the dataset autoId property along with the query parameter autoId=true although it is also possible to use the Orgvue assigned _id if this has been recorded in your source data

Note that not all actions are available for all the possible ways to select items

Action	Description	autoId	_id	Bulk Operations
create	Create a new item	✅	✅	❌
update	Update an existing item (property values not included in payload will remain unchanged)	✅	✅	✅
delete	Delete an existing item	✅	✅	✅
createOrUpdate	Create a new item or update an existing item if it exists	✅	❌	❌
replace	Replace an existing item (property values not included in payload will be cleared)	✅	✅	❌
createOrReplace	Create a new item or replace an existing item if exists	✅	❌	❌
noop	Do nothing to the item	✅	✅	❌

Please read the General Usage Information page for information about item identifiers.

Implicit Delete

implicitDelete

When a user wishes to replace a dataset with a newly uploaded dataset, this flag will tell the process to remove any items which are not in the payload

This requires that the user account performing the operation to have full delete Item access for all possible Items in the Dataset

If an operation is skipped, the item corresponding to it will also not be deleted

The noop action can be used to mark records to not be deleted which are otherwise known to be unchanged

If a Create Item operation is skipped due to already existing, the original Item will be treated as being part of the payload and will not be deleted

Use ?implicitDelete=true as the query parameter

Dates

dateFormat

Use this query parameter to set the date format of items in the payload

Possible date format options are:

• YYYY-MM-DD
• DD/MM/YYYY
• MM/DD/YYYY

This query parameter can only be set once per request, and all items must be presented in the same format in the payload

Items presented in a different dateFormat, will be ingested as strings and not dates

Example:

To set the Date Format as YYYY-MM-DD when importing data use

https://{baseUrl}/api/v1/{tenantId}/datasets/{datasetId}/items?dateFormat=YYYY-MM-DD