Drafts

Drafts in Orgvue contain a list of modelled changes that represent your future organization

These changes are nodes, representing positions or people, that have been added, updated or removed from the base dataset

The following operations are possible via the Orgvue API

Drafts:

Export Draft

Exporting a draft will produce a list of changes as item actions

See the Draft API Documentation for details

The item actions will be exported to an S3 location and the URL will be provided within the response message

If you have your own S3 location then this object may be defined within the request body and the export will be diverted to it instead

{
  "layers": [
    {
      "draftId": "36A1E02D-DC20-61C5-A11F-DD85440C652C",
      "layerKey": "default"
    }
}

This list of actions could then be imported to a Dataset to apply the changes or imported back to the source HRIS system to make the changes there and allow re-syncing of the Dataset with the source HRIS

Apply Draft to Dataset

Applying a Draft to a Dataset will update the dataset with all the item actions contained within the Draft layer

Importing the Draft does not clear the changes from the Draft, therefore a single Draft may be applied to multiple Datasets if required

You can also apply a Draft by first exporting the changes to the result location PUT URL and then using the PUT https://{baseUrl}/api/v1/{tenantId}/datasets/{datasetId}/items/import to import the changes to a Dataset

The format for the Apply Draft JSON payload is

{
  "layers": [
    {
      "draftId": "36A1E02D-DC20-61C5-A11F-DD85440C652C",
      "layerKey": "default"
    }
  ],
  "foldScheme": "distinct",
  "callback": {
    "method": "GET",
    "urlTemplate": "https://example.com?status={{jobStatus}}&traceId={{traceId}}&tenantId={{tenantId}}"
  },
  "resultLocation": {
    "method": "PUT",
    "url": "https://example.com"
  }
}

important

Applying the draft to a dataset does not clear the contents of the draft itself. Therefore if you you wish to continue to use the draft to capture further changes it is highly recommended that you Clear the Draft to avoid duplicate record errors on further draft imports

Fold Scheme

The foldScheme is an optional array included within the request body when applying multiple drafts to a dataset. Each draft is described as a layer as multiple drafts may be merged on top of each other

The foldScheme defines whether any node autoID (typically your Position ID or People ID) that exists in multiple drafts due to be merged will cause conflicts, merge losslessly, or merge according to layer order.

If you only submit one draft layer, foldScheme has no effect.

If no foldScheme is declared in the request body it defaults to distinct

Choosing the correct fold scheme affects how node updates and conflicts are handled during the dataset merge.

Value	Behavior	Use case
`distinct`	Any node autoID (typically your Position ID or People ID) appearing in more than one draft layer results in a conflict in the output dataset. Any conflict will result in failure of merge for duplicated nodes	Use when you want to detect overlaps or conflicts explicitly (strict separation of layers).
`lossless`	Attempts to merge layer records that share the same node autoID. If attributes conflict, merging fails for those nodes.	Use when you expect compatible data across layers and want a single unified record per identifier.
`ordered`	Performs layered merging of records with the same node autoID, respecting the order of layers provided in the `layers` array. Later layers can overwrite earlier ones for overlapping attributes.	Use when layering drafts hierarchically or applying later corrections/overrides.

When merging more than one draft layer containing the same node autoID the table below shows the outcome for the draft merge depending on the foldScheme applied and the property being edited for the duplicated node autoID

foldScheme	Property being edited in each layer	Example	Outcome
distinct	Same	Edit grade property for same node in two drafts	Complete Merge Fails: Due to conflicts
distinct	Different	Edit grade property in draft A and department in draft B for same node	Complete Merge Fails: Due to conflicts
lossless	Same	Edit grade property for same node in two drafts	Conflicting Node Merge Fails: Due to conflicts
lossless	Different	Edit grade property in draft A and department in draft B for same node	Success: Data merges and loads
ordered	Same	Edit grade property for same node in two drafts	Success: Data merges and last draft wins
ordered	Different	Edit grade property in draft A and department in draft B for same node	Success: Data merges and loads

Clear Entire Draft

The actions of Exporting or Applying a Draft does not clear or delete the Draft layer

This allows a single draft to be applied to several Datasets if required

Clearing the Draft will clear all the changes within it but will not delete the Draft, leaving it available for further changes to be saved to it

To clear the contents of a Draft use POST: https://{baseUrl}/api/v1/{tenantId}/drafts/clear

The format for the Clear Draft JSON payload is

{
  "layers": [
    {
      "draftId": "36A1E02D-DC20-61C5-A11F-DD85440C652C",
      "layerKey": "default"
    }
  ]
}

Clear Specific Edits From a Draft

Including a MongoDB Filter object within the JSON body of the clear draft request will enable specific actions to be cleared from the Draft.

Any actions not matching the filter will remain in the Draft

{
  "layers": [
    {
      "draftId": "331413BF-591C-031E-BAC4-D1C39AA28958",
      "layerKey": "default"
    }
  ],
  "filter": {
    "location": {
      "$in": ["UK", "USA"]
    },
    "approval_status": "Approved"
  }
}

Export Draft​

Apply Draft to Dataset​

Fold Scheme​

Clear Entire Draft​

Clear Specific Edits From a Draft​

Export Draft

Apply Draft to Dataset

Fold Scheme

Clear Entire Draft

Clear Specific Edits From a Draft