Links

Datasets of two different types may be joined by a Links dataset

The links between the datasets may be a one to one relationship such as people to positions where a position is occupied by a single person and each person occupies only one position or a many-to-many links' relationship such as people to activities where one person may conduct multiple activities and each activity may be conducted by multiple people

Link ID

When creating a link from one dataset to a second the AutoID from each dataset is used to create a link_id in the format [from_id,to_id]

An example would be a People to Positions link where the from_id would be the People dataset ID property e.g., Employee Number and the to_id would be the Position dataset ID property e.g., Position ID

The from_id and to_id must be included within the request body schema and the link_id is then automatically calculated by Orgvue from them

Create, update or delete links

To create, update or delete links the links "Sync import" endpoint is used

The format for the JSON payload is

[
  {
    "_action": "create",
    "from_id": 1133478,
    "to_id": "pos_a123",
    "allocation": 1
  },
  {
    "_action": "update",
    "from_id": 1273569,
    "to_id": "pos_a120",
    "allocation": 0.5
  },
  {
    "_action": "delete",
    "from_id": 3101881,
    "to_id": "pos_a191"
  }
]

Upon importing the data into the dataset the link_id will be automatically calculated for each node by Orgvue from the from_id and to_id which must be present in the payload

Links Actions

Actions available for Links datasets are the same as standard datasets create, update, replace, delete, noop, createOrUpdate, or createOrReplace

Importantly, updating a links dataset requires both that from_id and to_id to be present in the uploaded data so that the link_id may be calculated and the correct link updated

When updating a link between a from_id and a to_id, if the calculated link_id does not already exist it will be created however any previous links between either the from_id or to_id will still remain which may lead to duplicate or incorrect links

To avoid duplicate or incorrect links being left over when updating a links dataset it is recommended that all links are refreshed using the createOrUpdate action with the query parameter implicitDelete=true

This will update the link values for any links where the calculated link_id matches an existing link, creates a new link where no match is found, and deletes all links not present in the upload

The use of the createOrReplace action with the query parameter implicitDelete=true will yeld similar results with the important distinction that any additional property values in the links dataset will be removed if not present in the payload

Allocation Property

The allocation property is the default linking value property in Orgvue linked datasets, so will be required for most Create or Update actions

The property may be number or text based depending on the use case as it describes how one dataset is linked to the other

The table below gives examples of possible allocation values for different linking relationships

Linked Datasets	Link	Property Type	Example Values
People to Positions	FTE Value	Number	1 for full time, 0.75 for part time
People to Positions	Succession Planning	Text	Incumbent, Successor
People to Activities	% of time	Number	0.10, 0.05
People to Activities	RACI	Text	R,A,C,I
Positions to Competencies	Skill Level	Number	1 to 5
Positions to Competencies	Required Skill	Boolean	TRUE, FALSE

In addition to the default allocation property further properties may also be included in Links dataset

Populate Links Endpoint

The most common method to create or update links in a links dataset is to upload a file with the required actions as shown in Create or Update Links using the details from the two linked datasets

However if a single dataset (in this exqample the People dataset) in your tenant already contains the required property values for the from_id, to_id and allocation property of a links dataset then the Populate Links Endpoint can be used instead to extract these values from the People dataset and create or replace all nodes in the links dataset

The request body contains the following unique requirements:

sourceDatasetId this is the Id of the Source People dataset that contains the values to be uploaded for the default links properties from_id, to_id and allocation

The Populate Links Endpoint will automatically use the autoId of this dataset as either the from_id or to_id of the Links Dataset

targetDatasetAutoId is the property key in the People dataset to be used as either the from_id or to_id of the Links Dataset

Based on the setup of the links dataset e.g. People linked to Positions or Positions linked to People, the correct orientation of from_id and to_id will be automatically derived by the endpoint

allocationId is the property key in the people dataset to be used as the allocation property in the Link dataset, typically this would be FTE in a People to Positions configuration

{
  "sourceDatasetId": "6586F21B-AD4D-4D06-A309-712AF47184A2",
  "targetDatasetAutoId": "positionsId",
  "allocationId": "fte",
  "resultLocation": {
    "method": "PUT",
    "url": "https://example.com"
  },
  "callback": {
    "method": "GET",
    "urlTemplate": "https://yoururl.com?status={{jobStatus}}&traceId={{traceId}}&tenantId={{tenantId}}"
  }
}