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 |
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 settings
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
autoId
s or_id
s 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
autoId
s 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" }
]
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