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 link_id
is automatically calculated by Orgvue from the from_id
and to_id
which must be included within the request body schema
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 Orgvue dataset the link_id
will be calculated for each node from the required from_id
and to_id
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 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}}"
}
}