Skip to main content

Export dataset via asynchronous request

This guide will walk you through the steps required to export your dataset including linked and on-demand calculations from Orgvue via an asynchronous post request

Flowchart​

flowchart image

Prerequisites to integrating​

  • Dataset created in Orgvue
  • All properties pre-configured in the dataset
  • You will also need access to an Orgvue tenant and the permission to use tokens for that API user (See User Management in Settings for more information)

Recipe for exporting data from Orgvue​

To export the data from Orgvue using an asynchronous export you will require the POST: Async export endpoint

1. Generate an API Token​

Orgvue API requires a JWT in order for you to authenticate into Orgvue which can be obtained from the Tokens page
Token must be captured at time of creation and cannot be re-surfaced in the interface at a later date

2. Obtain your Base URL, Tenant ID, & Dataset ID​

In order to integrate into Orgvue you will require the Base URL along with your Tenant ID and Dataset ID that can be found at the following addresses

3. HTTP Header​

Set the Content-Type header: application/json; charset=UTF-8

4. HTTP Header​

Set the Authorization header, passing the API Token generated in step 1: Bearer {APIToken}

5. Export format​

{exportFormat} data may be exported in any of the following formats as defined in query parameter:

  • "jsonRows"
  • "jsonColumns"
  • "jsonObjects"
  • "csv"
  • "tsv"

The lineEndings query parameter defaults to "windows"

If "csv" or "tsv" are selected as the export format in a UNIX environment, then the lineEndings="unix" query parameter must be added to ensure correct export with multi line data cells.

6. Linking Relationships​

If the export contains properties calculated as a result of a linked dataset, then the dataset Id of the Links dataset should be specified within the request body linkingRelationships to ensure the correct linked dataset is used to perform the calculations

7. Result Location​

By default the Async Export endpoint will create a secure temporary file location and provide the job ticket URL in the response body which should be polled to obtain result location URL once job is complete.

Alternatively a PUT URL within your own hosted file location may be used and specified within the "resultLocation" of the request body

8. On Demand Calculations​

If the export dataset contains on-demand calculations then these should be executed in the correct order as specified in the request body executeOnDemand

9. Filtering Nodes and Hiding Columns in export​

By default this export will contain all rows and properties within the dataset including Orgvue generated properties e.g. _depth and _span

The use of a Projection allows you to both hide columns from the export as well as apply sort criteria too

The rows contained within the dataset export can be filtered with the use of a filter object see Filtering Nodes for more details

10. Create Async Export​

Create the export request with the following path parameter POST https://{baseUrl}/api/v1/{tenantId}/datasets/{datasetId}/export/{exportFormat}

Example: https://orgvue.eu-west-1.concentra.io/api/v1/DIGITAL_LEARNING/datasets/DA08093D-B517-F6FB-32F2-076B7050D607/export/"csv"

Example request body schema

{
  "dataset": {
    "linkingRelationships": [
      {
        "datasetId": "6586F21B-AD4D-4D06-A309-712AF47184A2"
      }
    ]
  },
  "executeOnDemand": [
    "onDemandProperty1",
    "onDemandProperty2"
  ],
  "query": {
    "output": {
      "filter": {
        "department": "Engineering",
        "salary": {
          "$gte": 50000
        },
        "employeeGrade": {
          "$lt": 5
        },
        "role": {
          "$nin": [
            "Manager",
            "Senior Engineer",
            "Team Lead"
          ]
        }
      },
      "projection": {
        "id": 1,
        "age": 0,
        "salary": 1,
        "employeeGrade": 2,
        "role": 3
      },
      "projectionMode": "add"
    }
  }
}

11. Poll job ticket to obtain export once complete​

The response from the export request will produce a job ticket resource which in turn contains a URL to be polled for the requested export data