Skip to main content

Usage Examples

A number of query parameters are available to better tune the handling of the update. In all the following examples, consider a dataset of employees, tracked by the internal _id property.

Performing updates​

Creating a new entry in the dataset​

You can create a new employee in the dataset by providing a payload item specifying the "create" action, along with the properties you wish to populate.

[
  {
    "_action": "create",
    "firstName": "John",
    "lastName": "Doe",
    "EmployeeID": "123456",
    "DOB": "1970-12-31",
    "Salary": "35000",
    "Location": "London"
  }
]
note

Keys used in the payload must exactly match property keys already defined in the dataset.

In the payload above, as part of your request, you have provided a value for the Date property. The default format for dates is YYYY-MM-DD, but you can use alternative formats by specifying the dateFormat query parameter. In this instance you can choose one of the following: YYYY-MM-DD, DD/MM/YYYY and MM/DD/YYYY so ?dateFormat=MM/DD/YYYY for instance.

The response you receive, assuming your request has the permission to perform the above action, will follow our response schema.

[
  {
    "_id": "{uuid}",
    "_action": "create",
    "_status": "success"
  }
]

You should keep track of the unique identifier generated for this item, as it is one of multiple ways to identify this row in the dataset.

Updating individual entries in the dataset​

Consider the following examples that explain how to change a property for the employee in the previous example.

If you know the internal Orgvue _id unique identifier of the employee record, you can provide it in the update payload:

[
  {
    "_action": "update",
    "_id": "{uuid}",
    "Location": "Manchester"
  }
]

Alternatively, if you want to track the employee by means of a unique identifier from a system you are integrating with, you can use the idKey query parameter. In this instance, specify ?idKey=EmployeeID (matching the property key exactly):

[
  {
    "_action": "update",
    "EmployeeId": "123456",
    "Location": "Manchester"
  }
]

You can specify the idKey query parameter multiple times to select an individual employee for update. In this instance, we are working with the firstName and lastName of the employee, and these fields are assumed to uniquely identify them in the dataset (your request will fail with an error response otherwise). Specify ?idKey=firstName&idKey=lastName, and provide the firstName and lastName property values in the payload:

[
  {
    "_action": "update",
    "firstName": "John",
    "lastName": "Doe",
    "Location": "Manchester"
  }
]

Updating individual items and the autoId query parameter​

Consider the example above, where the unique identifiers for employees are known ahead of time and originate in another system. Prior to using the API, you can configure EmployeeID as the automatic unique identifier for the dataset by navigating to the Settings app, editing the desired dataset, and selecting EmployeeID for the "Auto ID" field. The autoId will be the dataset property In this instance, specify ?autoId=true, and provide the EmployeeID with each item being updated.

[
  {
    "_action": "update",
    "EmployeeID": "123456",
    "Location": "Manchester"
  }
]

Batch updates​

note

This early beta version of our API does not produce an error if you attempt to mix individual item updates with a batch update. Subsequent post-beta versions will show an explicit error. For the time being batch updates are quietly dropped if specified in the same payload as individual updates.

Consider the example above, with a number of employees in a dataset. You can match multiple employees and update a property across all of them by using the mergeKey query parameter. In this instance, to update the OfficeCode for all employees whose Location is London, we match via the mergeKey provided, and perform the update specifying ?mergeKey=Location.

[
  {
    "_action": "update",
    "Location": "London",
    "OfficeCode": "301"
  }
]

Replacing every item in a dataset​

You can replace every item in a dataset by setting the query parameter ?implicitDelete=true and specifying the createOrReplace action for each payload item (along with any properties). Any items or properties not specified in the request payload will be deleted. All of the items/properties which are specified will be replaced with the value in the request payload.

[
  {
    "_action": "createOrReplace",
    "EmployeeID": "123456",
    "Location": "Manchester",
    ...
  }
  {
    "_action": "createOrReplace",
    "EmployeeID": "789000",
    "Location": "London",
    ...
  }
]

Identifier immutability​

As per the previous examples, there are a number of mechanisms you can use to update items individually or in batches. In all scenarios, the mechanism used to update must be immutable for the duration of the update transaction. So whether identifying an entry via _id, autoId, or one or more idKeys, you cannot change the property used to identify the employee. You cannot identify an employee to update by ?idKey=EmployeeID, and update to a new EmployeeID. To accomplish an update to an idKey you must identify the item by _id or one or more other idKeys, for example ?idKey=FirstName&idKey=lastName:

[
  {
    "_action": "update",
    "firstName": "John",
    "lastName": "Doe",
    "EmployeeID": "234567"
  }
]

The same limitation applies for mergeKey, you cannot track all individuals in Location: London and update to Location: Manchester in the same request.

Calculated updates are not supported​

You cannot perform calculations as part of this API, for example "add an amount of money to each Salary property". To accomplish this update, you should first export your dataset, perform the calculation on your side, and call the update endpoint with the updated values.

Clearing and deleting​

You can clear individual properties in dataset rows or delete rows entirely, as long as you have the relevant permissions to perform the action. The following section explains how to perform these actions.

Clearing a property​

You can choose to clear the value for individual employees, or for a batch of employees. The request payload to do so must set the property to null. In this instance, we want to clear the OfficeCode property for a single employee.

[
  {
    "_action": "update",
    "_id": "{uuid}",
    "OfficeCode": null
  }
]

To achieve the same for everyone who works in the London office, we would use the following query parameter: ?mergeKey=Location.

[
  {
    "_action": "update",
    "Location": "London",
    "OfficeCode": null
  }
]

Deleting a row in the dataset​

Deletion operations on dataset rows are allowed by means of _id, autoId, one or multiple idKeys as well as batched via mergeKeys. In this instance we will use the ?autoId=true query parameter to default to using the EmployeeID value to find the employee.

[
  {
    "_action": "delete",
    "EmployeeID": "123456"
  }
]

To delete all nodes in one location, we would use the following query parameter: ?mergeKey=Location.

[
  {
    "_action": "delete",
    "Location": "London"
  }
]

Import Items from a CSV​

All of the CRUD operations and query parameters mentioned above can also be performed using CSV payloads.

_action,firstName,lastName,EmployeeID,DOB,Salary,Location
create,John,Doe,123456,1970-12-31,35000,London
update,,,111111,,,Manchester
delete,,,654321,,,

CSV payloads must adhere to the following restrictions:

  • The file must be UTF-8 encoded
  • The file must be uploaded to a secure temporary file created by the "Create a secure file" endpoint.
  • The file must be comma delimited, other delimiters (e.g. pipes or semicolons) are not supported.
note

CSV payloads are currently only supported by the "Async Import" endpoint. Synchronous requests must use JSON payloads.