openapi: '3.1'
servers:
  - url: //{baseUrl}
    description: Sample link
security:
  - bearerAuth: []
info:
  title: Orgvue API specification
  description: >

    ## Introduction

    This page contains the Open API specification of the Orgvue API. It contains
    all the information needed to configure your integration.
tags:
  - name: datasets
    x-displayName: Dataset Operations
    description: Dataset level operations
  - name: links
    x-displayName: Linking Dataset Operations
    description: Linking dataset level operations
  - name: drafts
    x-displayName: Draft Operations
    description: Draft level operations
  - name: files
    x-displayName: File Operations
    description: File level operations
  - name: webhooks
    x-displayName: Webhook Operations
    description: Webhook level operations
  - name: jobTicket
    x-displayName: jobTicket
    description: >

      The asynchronous result entity produced by the export API, containing next
      link actions

      <SchemaDefinition schemaRef="#/components/schemas/jobTicket"
      showReadOnly={true} showWriteOnly={true} />
  - name: jobLink
    x-displayName: jobLink
    description: >

      The self link to the jobTicket entity produced by the export API

      <SchemaDefinition schemaRef="#/components/schemas/jobLink"
      showReadOnly={true} showWriteOnly={true} />
  - name: resultLink
    x-displayName: resultLink
    description: >

      The link to the dataset export location produced by the export API

      <SchemaDefinition schemaRef="#/components/schemas/resultLink"
      showReadOnly={true} showWriteOnly={true} />
  - name: clientError4xx
    x-displayName: Client Error
    description: >

      Receiving one or more of these objects in a response indicates that the
      server cannot process the request due to a client side error. You can use
      the information in the error object to correct and retry your request.

      <SchemaDefinition schemaRef="#/components/schemas/clientError4xx"
      showReadOnly={true} showWriteOnly={true} />
  - name: serverError5xx
    x-displayName: Internal Server Error
    description: >

      Receiving one or more of these objects in a response indicates that the
      server cannot process the request due to an internal server error. You may
      or may not be able to retry your request.

      >

      If the request specified that customer owned infrastructure be used, the
      server might encounter asynchronous errors. Optional error attributes will
      contain the downstream error received by the server from the customer
      owned resource. The request can be retried after issues with the resource
      have been addressed.

      <SchemaDefinition schemaRef="#/components/schemas/serverError5xx"
      showReadOnly={true} showWriteOnly={true} />
x-tagGroups:
  - name: Datasets
    tags:
      - datasets
  - name: Links
    tags:
      - links
  - name: Drafts
    tags:
      - drafts
  - name: Files
    tags:
      - files
  - name: Models
    tags:
      - jobTicket
      - jobLink
      - resultLink
  - name: Error Models
    tags:
      - clientError4xx
      - serverError5xx
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Token
  variables:
    itemActionsList: &ref_0
      - create
      - update
      - replace
      - delete
      - createOrUpdate
      - createOrReplace
      - noop
    datasetId: 6586F21B-AD4D-4D06-A309-712AF47184A2
    draftId: 36A1E02D-DC20-61C5-A11F-DD85440C652C
    linksDatasetName: PEOPLE to ROLES Links Dataset
  headers:
    xAmznTraceId:
      type: string
      example: Root=1-62bcb5d3-3b211f8616879dea3bde593f
      description: Unique tracking identifier for this request
    content-Type:
      type: string
      example: application/json; charset=UTF-8
      description: Type of payload content
    content-Encoding:
      type: string
      example: gzip
      description: Type of payload encoding (if compressed)
    content-Length:
      type: number
      example: 1000
      description: Length of payload content (taking compression into account)
  schemas:
    callbackPayload:
      type: object
      description: >-
        The callback mechanism allows you to configure a request to be made by
        the Orgvue API when processing your asynchronous request is complete.
        The callback request is sent when the jobTicket is 'completed' or
        'failed'.
      properties:
        method:
          type: string
          enum:
            - GET
        urlTemplate:
          type: string
          description: >-
            A templated string composed of your `url`, desired query parameters,
            and Orgvue API supported values. The available parameters are
            `jobStatus`, `tenantId`, `traceId`. Compile an expression using the
            `{{}}` notation. This expression will be translated when the
            callback is sent.
          example: >-
            https://example.com?status={{jobStatus}}&traceId={{traceId}}&tenantId={{tenantId}}
      required:
        - method
        - urlTemplate
    jobLink:
      type: object
      description: Next action link to poll for getting jobTicket updates
      properties:
        url:
          type: string
          format: url
          example: https://
        contentType:
          type: string
          example: application/json; charset=UTF-8
          enum:
            - application/json; charset=UTF-8
        type:
          type: string
          example: jobTicket
          enum:
            - jobTicket
    resultLink:
      type: object
      description: >-
        <b>Optional</b> next action. Only available if we are providing the
        storage location for the results. Available once the jobStatus is
        `"completed"`. May also be available if the job status is `"failed"`, in
        which case detailed failure information will have been written to this
        location.
      properties:
        url:
          type: string
          format: url
          example: https://
        contentType:
          type: string
          example: application/json; charset=UTF-8
          enum:
            - application/json; charset=UTF-8
            - text/csv; charset=UTF-8
            - text/tab-separated-values; charset=UTF-8
        type:
          type: string
          example: downloadLink
          enum:
            - downloadLink
            - uploadLink
    jobTicket:
      type: object
      required:
        - _links
        - jobStatus
        - _createdAt
        - _createdBy
        - X-Amzn-Trace-Id
      properties:
        _links:
          description: HATEOAS next available actions links
          type: object
          required:
            - self
          properties:
            self:
              $ref: '#/components/schemas/jobLink'
            result:
              $ref: '#/components/schemas/resultLink'
        jobStatus:
          type: string
          description: The status of the job tracked by this jobTicket
          enum:
            - created
            - running
            - failed
            - completed
        _createdAt:
          type: string
          example: '2022-03-20T17:53:23.282Z'
          description: ISO8601 creation timestamp of this job
        _createdBy:
          type: string
          format: email
          description: Email address of the account that created this job
        _modifiedAt:
          type: string
          example: '2022-03-20T17:53:26.321Z'
          description: ISO8601 latest update timestamp of this job
        X-Amzn-Trace-Id:
          $ref: '#/components/headers/xAmznTraceId'
        errors:
          type: array
          description: Only present if the job has completed in the `"failed"` status
          $ref: '#/components/schemas/serverError5xx/properties/errors'
    orgvueURL:
      type: string
      format: url
      description: The URL of this next action link to dereference
      example: https://orgvue.location/
    orgvueContentType:
      type: string
      format: contentType
      description: >-
        Hint indicating what the media type of the result of dereferencing the
        link should be
      example: application/json; charset=UTF-8
    getLink:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/orgvueURL'
        method:
          type: string
          description: The HTTP method to use when dereferencing the link
          enum:
            - GET
            - POST
          example: POST
        type:
          $ref: '#/components/schemas/orgvueContentType'
      required:
        - url
        - method
        - type
    exportGetLink:
      allOf:
        - $ref: '#/components/schemas/getLink'
      description: >-
        Follow this next action link to export the nodes of this dataset in the
        {exportFormat} provided
    retrieveLink:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/orgvueURL'
        method:
          type: string
          description: The HTTP method to use when dereferencing the link
          enum:
            - GET
          example: GET
        type:
          $ref: '#/components/schemas/orgvueContentType'
      required:
        - url
        - method
        - type
    retrieveDatasetLink:
      allOf:
        - $ref: '#/components/schemas/retrieveLink'
      description: >-
        Follow this next action link to extract additional information for this
        dataset
    retrieveDraftLink:
      allOf:
        - $ref: '#/components/schemas/retrieveLink'
      description: >-
        Follow this next action link to receive additional information for this
        draft
    baseFilterAndProjection:
      type: object
      description: The MongoDB Filter and Projection fields for querying
      properties:
        filter:
          $ref: '#/components/schemas/mongoFilter'
        projection:
          $ref: '#/components/schemas/itemsProjection'
    draftLayersArray:
      type: array
      description: >-
        An array of draft layer objects in the order in which they should be
        applied.
      items:
        type: object
        properties:
          draftId:
            type: string
            format: uuid
            description: The UUID for the draft containing the layer you wish to resolve.
            example: 36A1E02D-DC20-61C5-A11F-DD85440C652C
          layerKey:
            type: string
            example: default
            description: >-
              The key for the layer within the draft designated by the `draftId`
              you wish to resolve. This will commonly be the value `"default"`.
        required:
          - draftId
          - layerKey
    draftLayers:
      type: object
      properties:
        layers:
          $ref: '#/components/schemas/draftLayersArray'
        foldScheme:
          type: string
          description: >
            The type of folding required when multiple draft layers are
            provided. Defaults to "distinct".


            `distinct` Any node autoID 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.  



            `lossless` Attempts to merge layer records that share the same node
            autoID. If attributes conflict, merging fails for those nodes.



            `ordered` Performs layered merging of records with the same node
            autoID, respecting the order of layers provided in the array. Later
            layers can overwrite earlier ones for overlapping attributes.
          enum:
            - distinct
            - lossless
            - ordered
        callback:
          $ref: '#/components/schemas/callbackPayload'
        resultLocation:
          $ref: '#/components/schemas/resultLocation'
      required:
        - layers
    itemsProjection:
      type: object
      description: Property filtering using a projection object
      format: '{ [propertyKey]: 1 }'
      example:
        employee_id: 1
        location: 1
        city: 1
    mongoFilter:
      type: object
      description: Row level filtering using MongoDB query
      format: MongoDB query
      example:
        department: Engineering
        salary:
          $gte: 50000
        employeeGrade:
          $lt: 5
        role:
          $nin:
            - Manager
            - Senior Engineer
            - Team Lead
    methodAsString:
      type: string
      enum:
        - PUT
      example: PUT
    resultLocation:
      type: object
      description: >-
        Provide this object to divert your result data to a storage location of
        your choice. It must be a secure resource compatible with the [presigned
        URL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html)
        mechanism for an object for which you own the lifecycle, which our API
        can use to upload data via an http `"PUT"` request.
      properties:
        method:
          $ref: '#/components/schemas/methodAsString'
        url:
          type: string
          format: uri
          description: The URL where our API will attempt to "PUT" data to
          example: https://example.com
      required:
        - method
        - url
    action:
      type: string
      enum: *ref_0
      description: >-
        The action to perform on this item. Please note that not all actions are
        available at all times. Further, you might not have permission to
        perform some actions.
      example: create
    singleItemResult:
      type: object
      required:
        - _status
        - _action
      properties:
        _status:
          type: string
          enum:
            - success
            - failed
            - skipped
            - implicitDelete
            - partialSuccess
        _action:
          type: string
          enum: *ref_0
        _id:
          type: string
          description: >-
            The unique identifier of the item. It will only be present when the
            item is created, or when performing an action and selecting the item
            by the default `_id` property.
          example: 5C9EF1F8-0048-4CE9-91E7-789B857EE73C
        _failures:
          type: array
          description: Array of errors for this item
          items:
            type: object
            required:
              - message
              - code
              - name
            properties:
              message:
                type: string
                description: The descriptive message of the error
                example: Item Property update denied.
              code:
                type: number
                description: The error code
                example: 400807
              name:
                type: string
                description: The formalised error name
                example: ItemPropertyUpdateForbidden
              action:
                type: string
                description: The action requested for the item
                example: Read
              documentType:
                type: string
                description: The type of document referred to in this error context
                example: Dataset
              id:
                type: string
                description: The id of the dataset in this error context
                example: 5C8F2E99-CDFA-65C2-BFB6-84702EF73420
              key:
                type: string
                description: The key of the Id property in this error context
                example: employeeId
              properties:
                type: array
                items:
                  type: string
                description: Array of properties for in this error context
            additionalProperties:
              type:
                - string
                - boolean
                - number
              description: >-
                If using the `idKey` or `autoId` query parameters, you will
                receive one or more property attributes to match the properties
                in the request payload you provided.
    singleLinkItemResult:
      type: object
      required:
        - _status
        - _action
      properties:
        _status:
          type: string
          enum:
            - success
            - failed
            - skipped
            - implicitDelete
            - partialSuccess
        _action:
          type: string
          enum: *ref_0
        _id:
          type: string
          description: >-
            The unique identifier of the item. It will only be present when the
            item is created, or when performing an action and selecting the item
            by the default `_id` property.
          example: 5C9EF1F8-0048-4CE9-91E7-789B857EE73C
        link_id:
          type: string
          description: >-
            The autoId of a links dataset, consisting of the from_id and the
            to_id
          example: '["p_01269","pos_a120"]'
        _failures:
          type: array
          description: Array of errors for this item
          items:
            type: object
            required:
              - message
              - code
              - name
            properties:
              message:
                type: string
                description: The descriptive message of the error
                example: Item Property update denied.
              code:
                type: number
                description: The error code
                example: 400807
              name:
                type: string
                description: The formalised error name
                example: ItemPropertyUpdateForbidden
              action:
                type: string
                description: The action requested for the item
                example: Read
              documentType:
                type: string
                description: The type of document referred to in this error context
                example: Dataset
              id:
                type: string
                description: The id of the dataset in this error context
                example: 5C8F2E99-CDFA-65C2-BFB6-84702EF73420
              key:
                type: string
                description: The key of the Id property in this error context
                example: employeeId
              properties:
                type: array
                items:
                  type: string
                description: Array of properties for in this error context
    canonItemsResult:
      type: array
      description: >-
        Array of item
        [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete)
        results - successful and failed results combined
      items:
        oneOf:
          - $ref: '#/components/schemas/singleItemResult'
          - type: object
            required:
              - _status
              - _action
              - _results
            properties:
              _status:
                type: string
                enum:
                  - success
                  - failed
                  - skipped
                  - implicitDelete
                  - partialSuccess
                description: The result of the action applied to the item
                example: success
              _action:
                type: string
                enum: *ref_0
                description: The action requested for the item
                example: update
              _results:
                type: array
                description: Array of singular item results for same bulk action
                items:
                  $ref: '#/components/schemas/singleItemResult'
            additionalProperties:
              type:
                - string
                - boolean
                - number
              description: >-
                If using one or more `mergeKey` query parameters, you will
                receive one or more property attributes to match the properties
                in the request payload you provided.
              example: Area
    canonLinksItemsResult:
      type: array
      description: >-
        Array of item
        [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete)
        results - successful and failed results combined
      items:
        $ref: '#/components/schemas/singleLinkItemResult'
    clearDraftsResult:
      type: array
      description: Array of clear draft results - successful and failed results combined
      items:
        singleClearDraftResult:
          type: object
          required:
            - status
            - draftId
            - layerKey
          properties:
            status:
              type: string
              enum:
                - success
                - failed
            draftId:
              type: string
              description: The unique identifier of the draft
              example: 5C9EF1F8-0048-4CE9-91E7-789B857EE73C
            layerKey:
              type: string
              example: default
              description: >-
                The key for the layer within the draft designated by the
                `draftId`. This will commonly be the value `"default"`.
            failures:
              type: array
              description: Array of errors for this item
              items:
                type: object
                required:
                  - message
                  - code
                  - name
                properties:
                  message:
                    type: string
                    description: The descriptive message of the error
                    example: Draft layer update denied.
                  code:
                    type: number
                    description: The error code
                    example: 400807
                  name:
                    type: string
                    description: The formalised error name
                    example: DraftLayerUpdateForbidden
                  id:
                    type: string
                    description: The id of the draft in this error context
                    example: 5C8F2E99-CDFA-65C2-BFB6-84702EF73420
                  key:
                    type: string
                    description: The key of the Id property in this error context
                    example: employeeId
                  properties:
                    type: array
                    items:
                      type: string
                    description: Array of properties for in this error context
    propertyType:
      type: string
      enum:
        - boolean
        - date
        - image
        - number
        - text
        - unknown
      example: text
    propertiesListItem:
      type: object
      properties:
        key:
          type: string
          description: The property key
          example: firstName
        name:
          type: string
          description: The descriptive name of the property
          example: First Name
        type:
          $ref: '#/components/schemas/propertyType'
        isAutoId:
          type: boolean
          enum:
            - true
          description: Whether this property is the autoId
        isLabelId:
          type: boolean
          enum:
            - true
          description: Whether this property is the labelId
        isCore:
          type: boolean
          enum:
            - true
          description: >-
            Whether this property is one of autoId, lableId, treeId or
            treeParentId
        isRequired:
          type: boolean
          description: Whether this property is set as required
        sortOrder:
          type: number
          description: The sort order position of the property
        isTreeId:
          type: boolean
          enum:
            - true
          description: Whether this property is the treeId
        isTreeParentId:
          type: boolean
          enum:
            - true
          description: Whether this property is the treeParentId
        isOnDemand:
          type: boolean
          enum:
            - true
          description: True if this property is evaluated on demand
        expression:
          type: string
          description: The expression for an evaluated property
      required:
        - key
        - name
        - type
        - isRequired
    updatePropertiesListItem:
      type: object
      properties:
        key:
          type: string
          description: The property key.
          example: firstName
        name:
          type: string
          description: The descriptive name of the property. Defaults to the `key` value.
          example: First Name
        type:
          allOf:
            - $ref: '#/components/schemas/propertyType'
            - description: The type of the property.
            - example: text
        isRequired:
          type: boolean
          description: >-
            Whether this property is set as required. `autoId`, `labelId`,
            `treeId` and `treeParentId` properties should have `true` value
      required:
        - key
      example: &ref_1
        - key: firstName
          name: First Name
          type: text
        - key: position_id
          name: Position ID
          type: text
        - key: position_title
          name: Position Title
          type: text
        - key: salary
          name: Salary
          type: number
    datasetLinking:
      type: object
      description: >-
        Provide relevant dataset configuration information. A Links `datasetId`
        may be supplied in the `linkingRelationships` to allow calculations to
        be executed with the context of a specific linked dataset.
      properties:
        linkingRelationships:
          type: array
          items:
            type: object
            properties:
              datasetId:
                type: string
                format: uuid
                example: 6586F21B-AD4D-4D06-A309-712AF47184A2
            required:
              - datasetId
      required:
        - linkingRelationships
    linksData:
      description: Source or target dataset information
      type: object
      properties:
        name:
          type: string
          description: The name of the dataset
        datasetId:
          type: string
          format: uuid
          description: The unique identifier of this dataset
          example: 6586F21B-AD4D-4D06-A309-712AF47184A2
        type:
          type: string
          description: The type of the dataset
          example: ROLES
        _links:
          type: object
          properties:
            dataset:retrieve:
              $ref: '#/components/schemas/retrieveDatasetLink'
          required:
            - dataset:retrieve
      required:
        - name
        - datasetId
        - type
    retrieveDatasetBasic:
      type: object
      properties:
        datasetId:
          type: string
          format: uuid
          description: The unique identifier of this dataset
          example: 6586F21B-AD4D-4D06-A309-712AF47184A2
        cacheKey:
          type: string
          description: >-
            Unique key for the user and dataset version. The cache key is
            updated when a change is applied to either the dataset or its
            security rules.
          example: >-
            abc5DeFgh3IjK5L76/ABCdeEFGHIJklMNo+pqRstuvwxYZENuHvV863y5BtEhGTuqnP2cLZhys9EQ==
        createdAt:
          type: string
          description: ISO8601 creation timestamp of this dataset
          example: '2022-03-20T17:53:23.282Z'
        createdBy:
          type: string
          format: email
          description: Email address of the account that created the dataset
        modifiedAt:
          type: string
          description: ISO8601 timestamp of latest modification to this dataset
          example: '2022-03-20T17:53:23.282Z'
        modifiedBy:
          type: string
          format: email
          description: Email address of the account that last modified this dataset
        name:
          type: string
          description: The name of the dataset
          example: Positions
        type:
          type: string
          description: The type of the dataset
          example: POSITIONS
        autoId:
          type: string
          description: The property key configured as autoId for this dataset
          example: position_id
        labelId:
          type: string
          description: The property key configured as `labelId` for this dataset
          example: position_title
        tags:
          type: array
          items:
            type: string
            example: hr
          description: Array of shared `tags` for the dataset
        treeId:
          type: string
          description: The default hierarchy key property
          example: position_id
        treeParentId:
          type: string
          description: The default hierarchy parent key property
          example: position_managerid
        properties:
          description: Array of property objects
          type: array
          items:
            $ref: '#/components/schemas/propertiesListItem'
          example: *ref_1
      required:
        - datasetId
        - name
        - type
        - createdBy
        - autoId
        - labelId
        - properties
    retrieveDataset:
      allOf:
        - $ref: '#/components/schemas/retrieveDatasetBasic'
        - properties:
            items:
              type: object
              description: >-
                Metadata for the items in this dataset (not metadata of the
                dataset)
              properties:
                lastTransactionId:
                  type: string
                  format: uuid
                  example: 00000172-5FD0-4411-4140-B5A82D1111CD
                  description: >-
                    The unique identifier of the last transaction to change the
                    state of an item in the dataset
                modifiedAt:
                  type: string
                  format: iso8601
                  example: '2020-05-29T09:43:03.953Z'
                  description: >-
                    ISO8601 timestamp for the last change of state of an item in
                    the dataset
              required:
                - lastTransactionId
                - modifiedAt
            drafts:
              description: List of drafts attached to this dataset
              type: array
              items:
                type: object
                properties:
                  draftId:
                    type: string
                    format: uuid
                    example: 36A1E02D-DC20-61C5-A11F-DD85440C652C
                  name:
                    type: string
                  _links:
                    description: >-
                      HATEOAS next action links for drafts related to this
                      dataset
                    type: object
                    properties:
                      draft:retrieve:
                        $ref: '#/components/schemas/retrieveDraftLink'
                required:
                  - draftId
                  - name
                  - _links
            linkingRelationships:
              description: >-
                List of linking dataset relationships. If a dataset is part of
                more than one links relationships, the list will contain more
                than one objects. A source dataset will contain `"link"`, and
                `"target"`, a linking dataset will contain `"source"` and
                `"target"`, while a target dataset will contain `"source"` and
                `"link"`.
              type: array
              items:
                type: object
                properties:
                  datasetId:
                    type: string
                    format: uuid
                    example: 6586F21B-AD4D-4D06-A309-712AF47184A2
                  name:
                    type: string
                    example: People to Positions Dataset
                  type:
                    type: string
                    example: LINKS
                  source:
                    allOf:
                      - $ref: '#/components/schemas/linksData'
                      - type: object
                        properties:
                          type:
                            example: PEOPLE
                  target:
                    allOf:
                      - $ref: '#/components/schemas/linksData'
                      - type: object
                        properties:
                          type:
                            example: POSITIONS
                  _links:
                    description: >-
                      HATEOAS next action links facilitating the export of a
                      linking dataset
                    type: object
                    properties:
                      export:
                        type: object
                        properties:
                          url:
                            type: string
                            format: url
                            description: The URL of this next action link to dereference
                          method:
                            type: string
                            description: The HTTP method to use when dereferencing the link
                          contentType:
                            type: string
                            description: >-
                              Hint indicating what the media type of the result
                              of dereferencing the link should be
                          jsonBody:
                            description: >-
                              The payload to provide when performing an export
                              request that needs to perform linking calculations
                            type: object
                            required:
                              - dataset
                            properties:
                              dataset:
                                $ref: '#/components/schemas/datasetLinking'
                                required:
                                  - url
                                  - method
                                  - contentType
                                  - jsonBody
                              dataset:retrieve:
                                $ref: '#/components/schemas/retrieveDatasetLink'
                              required:
                                - export
                                - dataset:retrieve
                required:
                  - _links
            _links:
              type: object
              description: HATEOAS next action links having received a dataset resource
              properties:
                self:
                  $ref: '#/components/schemas/retrieveDatasetLink'
                dataset:export:jsonRows:
                  $ref: '#/components/schemas/exportGetLink'
                dataset:export:jsonColumns:
                  $ref: '#/components/schemas/exportGetLink'
                dataset:export:jsonObjects:
                  $ref: '#/components/schemas/exportGetLink'
                dataset:export:csv:
                  $ref: '#/components/schemas/exportGetLink'
                dataset:export:tsv:
                  $ref: '#/components/schemas/exportGetLink'
              required:
                - self
                - dataset:export:jsonRows
                - dataset:export:jsonColumns
                - dataset:export:jsonObjects
                - dataset:export:csv
                - dataset:export:tsv
          required:
            - _links
    createLinksDatasetResponse:
      type: object
      properties:
        datasetId:
          type: string
          format: uuid
          description: The unique identifier of this dataset
          example: 6586F21B-AD4D-4D06-A309-712AF47184A2
        name:
          type: string
          description: The name of the dataset
          example: PEOPLE to ROLES Links Dataset
        type:
          type: string
          description: The type of the dataset
          example: LINKS
        createdBy:
          type: string
          format: email
          description: Email address of the account that created the dataset
        cacheKey:
          type: string
          description: >-
            Unique key for the user and dataset version. The cache key is
            updated when a change is applied to either the dataset or its
            security rules.
          example: >-
            abc5DeFgh3IjK5L76/ABCdeEFGHIJklMNo+pqRstuvwxYZENuHvV863y5BtEhGTuqnP2cLZhys9EQ==
        autoId:
          type: string
          description: >-
            The property key configured as autoId for this dataset. This will
            always be link_id, a property automatically created from the from_id
            and to_id, of the form [from_id, to_id].
          example: link_id
        tags:
          type: array
          description: Array of shared tags for the links dataset
          example:
            - admin
            - people
            - roles
        properties:
          description: Array of property objects
          type: array
          items:
            $ref: '#/components/schemas/propertiesListItem'
          example: &ref_11
            - key: from_id
              name: from_id
              type: string
              isRequired: true
            - key: to_id
              name: to_id
              type: string
              isRequired: true
            - key: link_id
              name: link_id
              type: string
              isRequired: true
            - key: allocation
              name: allocation
              type: number
              isRequired: true
      required:
        - datasetId
        - name
        - type
        - createdBy
        - autoId
        - properties
    createOrUpdateDatasetShared:
      type: object
      properties:
        name:
          type: string
          description: The name of the dataset
          example: Positions
        type:
          type: string
          description: >-
            The type of the dataset. Note type `"LINKS"` is not available for
            this endpoint.
          example: POSITIONS
        autoId:
          type: string
          description: The property key configured as autoId for this dataset
          example: position_id
        labelId:
          type: string
          description: The property key configured as labelId for this dataset
          example: position_title
        tags:
          type: array
          items:
            type: string
            example: hr
          description: Array of shared tags for the dataset
        treeId:
          type: string
          description: The default hierarchy key property
          example: position_id
        treeParentId:
          type: string
          description: The default hierarchy parent key property
          example: position_managerid
    updateDataset:
      allOf:
        - $ref: '#/components/schemas/createOrUpdateDatasetShared'
        - properties:
            properties:
              description: Array of partial property objects.
              type: array
              items:
                $ref: '#/components/schemas/updatePropertiesListItem'
            treeId:
              type:
                - string
                - 'null'
            treeParentId:
              type:
                - string
                - 'null'
            tags:
              type:
                - array
                - 'null'
    createDataset:
      allOf:
        - $ref: '#/components/schemas/createOrUpdateDatasetShared'
        - properties:
            properties:
              description: Array of property objects
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/updatePropertiesListItem'
                  - required:
                      - type
                      - isRequired
      required:
        - name
        - type
        - autoId
        - labelId
        - properties
    updateLinksDataset:
      type: object
      properties:
        name:
          type: string
          description: The name of the links dataset.
          example: PEOPLE to ROLES Links Dataset
        additionalProperties:
          description: Array of partial property objects.
          type: array
          items:
            $ref: '#/components/schemas/updatePropertiesListItem'
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Array of shared tags for the links dataset.
          example:
            - people
            - roles
    createLinksDataset:
      type: object
      properties:
        name:
          type: string
          description: The name of the links dataset.
          example: PEOPLE to ROLES Links Dataset
        fromDatasetId:
          type: string
          format: uuid
          description: The unique identifier of the dataset you are linking from.
          example: 99CD8A1B-61A2-4768-87FA-3D10420FC535
        toDatasetId:
          type: string
          format: uuid
          description: The unique identifier of the dataset you are linking to.
          example: 2B44BAD6-6680-4A19-A00C-0366832E2BD6
        additionalProperties:
          description: Array of property objects
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/updatePropertiesListItem'
              - required:
                  - type
                  - isRequired
        tags:
          type: array
          items:
            type: string
          description: Array of shared tags for the links dataset.
          example:
            - admin
            - people
            - roles
      required:
        - name
        - fromDatasetId
        - toDatasetId
    retrieveDraft:
      type: object
      properties:
        draftId:
          type: string
          format: uuid
          description: The unique identifier of this draft
          example: 36A1E02D-DC20-61C5-A11F-DD85440C652C
        name:
          type: string
          description: The name of the draft
          example: Finance Scenario Model
        description:
          type: string
          description: The description of the draft
          example: A scenario of our future Finance organization structure.
        createdBy:
          type: string
          format: email
          description: Email address of the account that created the draft
        modifiedAt:
          type: string
          format: iso8601
          example: '2020-05-29T09:43:03.953Z'
          description: ISO8601 timestamp for the last change of state to the draft
        tags:
          type: array
          items:
            type: string
            example: Finance
          description: Array of tags for the draft
        _links:
          type: object
          description: HATEOAS next action links having received a draft resource
          properties:
            self:
              $ref: '#/components/schemas/retrieveDraftLink'
            draft:actions:
              allOf:
                - $ref: '#/components/schemas/getLink'
              properties:
                jsonBody:
                  type: object
                  properties:
                    layers:
                      $ref: '#/components/schemas/draftLayersArray'
                  example:
                    layers:
                      - draftId: 36A1E02D-DC20-61C5-A11F-DD85440C652C
                        layerKey: default
              description: >-
                Follow this next action link to retrieve an array of item
                actions capturing the changes held in the draft.
          required:
            - self
            - draft:actions
      required:
        - draftId
        - name
        - createdBy
        - modifiedAt
        - _links
    importPayload:
      type: object
      required:
        - importLocation
      properties:
        importLocation:
          type: object
          description: >-
            Resource location that our API will ingest data from. Must be a
            secure URL location to an infrastructure object the lifecycle of
            which you own, where our API can have access to perform a http
            `"GET"` request to.
          properties:
            method:
              type: string
              enum:
                - GET
            url:
              type: string
              format: uri
              description: The URL where our API will attempt to "GET" data from
              example: https://example.com
          required:
            - method
            - url
        resultLocation:
          $ref: '#/components/schemas/resultLocation'
        callback:
          $ref: '#/components/schemas/callbackPayload'
    fetch:
      type: object
      required:
        - url
      properties:
        url:
          format: url
          type: string
          description: URL of the data you want to fetch
          example: https://
        method:
          type: string
          description: HTTP request method
          example: PUT
        headers:
          type: object
          description: Headers you want to add to request
          example:
            Content-Type: application/json; charset=utf-8
        body:
          description: Body you want to add to request
        mode:
          type: string
          description: The mode you want to use for request
          example: cors
        credentials:
          type: string
          description: Controls what browsers do with credentials
          example: omit
        cache:
          type: string
          description: How request should interact with browser's HTTP cache
          example: no-store
        redirect:
          type: string
          description: How a 'redirect' response should be handled
          example: follow
        referrer:
          type: string
          description: Referrer of the request
          example: about:client
        referrerPolicy:
          type: string
          description: Referrer policy for the request
          example: no-referrer
        integrity:
          type: string
          description: Subresource integrity value of request
          example: sha256-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
        keepalive:
          type: boolean
          description: Controls whether the request should outlive the page
          example: 'true'
        signal:
          type: object
          description: Allows you to abort fetch request if desired
    generateTemporaryFile:
      type: object
      properties:
        get:
          format: url
          type: string
          description: URL to retrieve data from the storage location via a GET request
          example: https://...
        put:
          format: url
          type: string
          description: URL to write data to the storage location via a PUT request
          example: https://...
    getWebhook:
      type: object
      properties:
        webhookId:
          type: string
          description: webhook subscription unique identifier
        modifiedAt:
          type: string
          format: date-time
          description: ISO8601 latest update timestamp of this item
        url:
          type: string
          description: URL where event information will be sent.
          example: https://
        method:
          type: string
          description: HTTP method to be used when sending event.
          enum:
            - GET
          example: GET
        eventType:
          type: string
          description: type of the event to which you want to subscribe
        status:
          type: string
          description: status of subscription. Can be `active`, `inactive`, `suspended`
    clientError4xx:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            required:
              - code
              - name
            properties:
              code:
                type: string
                description: The unique code of the error
                example: '400020'
              name:
                type: string
                description: The unique name of the error
                example: FieldMustNotBeMultivalued
              message:
                type: string
                description: >-
                  A human readable message that helps you correct your request.
                  _Exact content may change. It should not be used to determine
                  subsequent actions._
                example: You cannot specify this field multiple times.
              pathParameter:
                type: string
                description: Points to the path parameter of the entity you need to correct
                example: '{tenantId}'
              queryParameter:
                type: string
                description: >-
                  Points to the query parameter of the entity you need to
                  correct
                example: includeBOM
              jsonBody:
                type: string
                description: Points to the JSON path of the entity you need to correct
                example: $.dataset.drafts[0].draftId
              resourcePath:
                type: string
                description: Points to the resource path of the entity you need to correct
                example: MY_TENANT/datasets/99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B
    serverError5xx:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            required:
              - code
              - name
            properties:
              code:
                type: string
                description: The unique code of the error
                example: '50001'
              name:
                type: string
                description: The unique name of the error
                example: InternalServerError
              message:
                type: string
                description: >-
                  A human readable message that helps you correct your request.
                  _Exact content may change. It should not be used to determine
                  subsequent actions._
                example: >-
                  There was an internal error. If the issue persists you should
                  contact support@orgvue.com.
              errorContentType:
                type: string
                description: >-
                  Only available when specifying customer owned infrastructure.
                  The Content-Type response header value of an error we received
                  from your infrastructure provider
                example: application/xml
              errorContent:
                type: string
                description: >-
                  Only available when specifying customer owned infrastructure.
                  String representation of the error payload that we received
                  from your infrastructure provider when we attempted a http PUT
                  to the location
                example: >-
                  <?xml version="1.0"
                  encoding="UTF-8"?><Error><Code>NoSuchKey</Code><Message>The
                  resource you requested does not
                  exist</Message><Resource>/mybucket/myfoto.jpg</Resource><RequestId>4442587FB7D0A2F9</RequestId></Error>
  parameters:
    tenantIdPathParam:
      in: path
      name: tenantId
      schema:
        type: string
        pattern: ^[A-Z][A-Z0-9_]{0,29}$
      required: true
      description: Tenant identifier
      example: TENANT_ID
    datasetIdPathParam:
      name: datasetId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Dataset unique identifier
      example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B
    draftIdPathParam:
      name: draftId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Draft unique identifier
      example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B
    linksDatasetIdPathParam:
      name: linksDatasetId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Links dataset unique identifier
      example: 99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B
    dateFormatQueryParam:
      in: query
      name: dateFormat
      schema:
        type: string
        enum:
          - YYYY-MM-DD
          - DD/MM/YYYY
          - MM/DD/YYYY
      description: >-
        The date format that items are presented in at the payload of your
        request. This query parameter can only be set once per request, and all
        items must be presented in the same format in the payload. Items
        presented in a different `dateFormat`, will be ingested as strings and
        not dates.
      example: YYYY-MM-DD
    noopTokenQueryParam:
      in: query
      name: noopToken
      schema:
        type: string
        description: >-
          A user can specify their own String values in import cells that result
          in no change to the data.
      example: IGNORE_ME
    clearTokenQueryParam:
      in: query
      name: clearToken
      schema:
        type: string
        description: >-
          A user can specify their own String values in import cells to
          represent clearing out a value. Null and emptyString are the default
          clear tokens.  As such these are always applied clear tokens without
          the requirement to explicitly state as a query parameter 
      example: REMOVE_ME
    encodingParam:
      in: query
      name: encoding
      schema:
        type: string
        enum:
          - gzip
          - identity
      description: >-
        Determines whether the data written to the result location will be
        compressed using [gzip](https://en.wikipedia.org/wiki/Gzip). Defaults to
        `identity` (meaning no compression). This will be deprecated in favour
        of `resultEncoding`.
      example: gzip
    encodingParamUpdated:
      in: query
      name: resultEncoding
      schema:
        type: string
        enum:
          - gzip
          - identity
      description: >-
        Determines whether the data written to the result location will be
        compressed using [gzip](https://en.wikipedia.org/wiki/Gzip). Defaults to
        `identity` (meaning no compression).
      example: gzip
    onPropertyAccessDeniedQueryParam:
      in: query
      name: onPropertyAccessDenied
      schema:
        type: string
        enum:
          - skipProperty
          - denyItemAccess
      example: denyItemAccess
      description: >-
        In the case where you do not have sufficient access rights to alter one
        or more properties, you can specify `denyItemAccess` to prevent all
        updates from taking place. Alternatively you can specify `skipProperty`
        to allow the update to take place only for properties you have been
        granted access to. Defaults to `denyItemAccess`.
    onItemAccessDeniedQueryParam:
      in: query
      name: onItemAccessDenied
      schema:
        type: string
        enum:
          - skipAction
          - failTransaction
      description: >-
        In the case where you do not have sufficient access rights to alter one
        or more items, you can specify `failTransaction` to prevent all updates
        from taking place. Alternatively you can specify `skipAction` to allow
        the update to take place only for items you have been granted access to.
        Defaults to `failTransaction`.
    onActionValidationFailureQueryParam:
      in: query
      name: onActionValidationFailure
      schema:
        type: string
        enum:
          - skipAction
          - failTransaction
        example: failTransaction
      description: >-
        In the case where you have provided an invalid action for one or more
        items, you can specify `failTransaction` to prevent all updates from
        taking place. Alternatively you can specify `skipAction` to allow the
        update to take place only for updates with valid actions. Defaults to
        `failTransaction`.
    autoIdQueryParam:
      in: query
      name: autoId
      schema:
        type: boolean
      description: >-
        Relies on the automatic identifier in your dataset (the property
        configured as the "autoId"), instead of the internal Orgvue `_id`
        property. Setting this query parameter to `true` allows you to
        substitute the `_id` attribute in the payload for your custom property
        identifier.
      example: true
    idKeyQueryParam:
      in: query
      name: idKey
      schema:
        type: string
      description: >-
        Consider the case where you can uniquely identify a node in your dataset
        by means of one or more property values in the node, instead of the
        Orgvue internal `_id` property value. Setting this query parameter to
        track the property or properties mentioned allows you to substitute the
        `_id` attribute in the payload for your custom property identifier(s).
        You can specify this query parameter multiple times.
      example: firstName
    mergeKeyQueryParam:
      in: query
      name: mergeKey
      schema:
        type: string
      example: area
      description: >-
        In the case of bulk updates you can use this query parameters to specify
        one or more properties that if present in an item, will include the item
        to the bulk update.
    implicitDeleteQueryParam:
      in: query
      name: implicitDelete
      schema:
        type: boolean
      description: >-
        Only use this query parameter when you want to replace all existing
        items in a dataset with the ones in this payload. Any items not in the
        payload of this request will be deleted in the dataset after the ingress
        completes. Assumes access to individual items in the dataset is granted
        ahead of time, for deletion purposes. If an operation is **skipped** the
        item corresponding to it will **not be deleted**.
      example: true
    exportFormatPathParam:
      name: exportFormat
      in: path
      required: false
      schema:
        type: string
        enum:
          - jsonRows
          - jsonColumns
          - jsonObjects
          - csv
          - tsv
      description: >-
        The data format to use in the response. If no export format is provided
        the default `jsonRows` will be used.
      example: jsonRows
    acceptEncodingHeader:
      name: Accept-Encoding
      in: header
      schema:
        type: string
        enum:
          - gzip
          - identity
      description: >-
        Add this request header to compress the response you receive. For
        asynchronous endpoints using this header compresses the response
        containing the `jobTicket` and not the result of the calculation.
    includeBOMQueryParam:
      in: query
      name: includeBOM
      required: false
      schema:
        type: boolean
        default: true
      description: >-
        Determines if a [Byte Order Mark
        (BOM)](https://en.wikipedia.org/wiki/Byte_order_mark) is added to the
        beginning of the response payload. This query parameter is only
        implemented for requests with an `exportFormat` value of `CSV` or `TSV`.
        Defaults to `true`.
    lineEndingsQueryParam:
      in: query
      name: lineEndings
      required: false
      schema:
        type: string
        default: windows
        enum:
          - unix
          - windows
      description: >-
        Determines the [line
        endings](https://en.wikipedia.org/wiki/Newline#Representation) (row
        separators) for data export. This query parameter is only implemented
        for requests with an `exportFormat` value of `CSV` or `TSV`. Defaults to
        `windows`.
    deleteOmittedPropertiesQueryParam:
      in: query
      name: deleteOmittedProperties
      required: false
      schema:
        type: boolean
        default: false
      description: >-
        Only use this parameter if you wish to delete any properties that don't
        appear in the `properties` array of your payload. If an array of
        properties is supplied and this query parameter is set to `true`, any
        existing properties that are not matched by key will be deleted. By
        default no properties are deleted.
    deleteOmittedPropertiesQueryParamLinks:
      in: query
      name: deleteOmittedProperties
      required: false
      schema:
        type: boolean
        default: false
      description: >-
        Only use this parameter if you wish to delete any properties that don't
        appear in the `additionalProperties` array of your payload. If an array
        of properties is supplied and this query parameter is set to `true`, any
        existing additional properties that are not matched by key will be
        deleted. By default no properties are deleted. Note that this does not
        apply to the core properties `from_id`, `to_id`, `allocation` and
        `link_id`, which may not be modified.
responses:
  jobTicket:
    description: >-
      Success - A resource that when polled allows you to check the status of
      your asynchronous request
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Encoding:
        $ref: '#/components/headers/content-Encoding'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/jobTicket'
  datasets:
    description: Success - All datasets in the tenant
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          type: array
          items:
            type: object
            properties:
              datasetId:
                type: string
                format: uuid
                description: The unique identifier of this dataset
                example: 6586F21B-AD4D-4D06-A309-712AF47184A2
              name:
                type: string
                description: The name of the dataset
                example: EXAMPLE_DATASET
              type:
                type: string
                description: The type of the dataset
                example: POSITIONS
              isPermissionedView:
                type: boolean
                description: Whether this item is a permissioned view
                example: false
              _links:
                type: object
                description: HATEOAS next available actions links
                properties:
                  dataset:retrieve:
                    $ref: '#/components/schemas/retrieveDatasetLink'
                  dataset:export:
                    $ref: '#/components/schemas/exportGetLink'
                required:
                  - dataset:retrieve
                  - dataset:export
            required:
              - datasetId
              - name
              - type
              - isPermissionedView
              - _links
  retrieveDataset:
    description: Success - The dataset resource
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/retrieveDataset'
  createDataset:
    description: Success - The dataset resource has been created
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/retrieveDatasetBasic'
  updateDataset:
    description: Success - The dataset resource has been updated
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/retrieveDatasetBasic'
  createLinksDataset:
    description: Success - The links dataset resource has been created
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/createLinksDatasetResponse'
  updateLinksDataset:
    description: Success - The links dataset resource has been updated
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/createLinksDatasetResponse'
  retrieveDraft:
    description: Success - The draft resource
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/retrieveDraft'
  putItems200Response:
    description: Success - the status of each item after the update.
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/canonItemsResult'
        example: &ref_4
          - _status: success
            _id: 5C9EF1F8-0048-4CE9-91E7-789B857EE73C
            _action: createOrUpdate
          - _status: success
            _id: 7918D0B4-24AC-8A3E-E21C-1302FAE4937E
            _action: createOrUpdate
          - _status: success
            _id: ECFB8805-002D-441C-92AE-39FFE9D88A20
            _action: delete
  putLinksItems200Response:
    description: Success - the status of each item after the update.
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/canonLinksItemsResult'
        example: &ref_5
          - _status: success
            _id: 5C9EF1F8-0048-4CE9-91E7-789B857EE73C
            _action: create
            link_id: '["p_01234","pos_a123"]'
          - _status: success
            _id: 7918D0B4-24AC-8A3E-E21C-1302FAE4937E
            _action: update
            link_id: '["p_01269","pos_a120"]'
          - _status: success
            _id: ECFB8805-002D-441C-92AE-39FFE9D88A20
            _action: delete
            link_id: '["p_01270","pos_a191"]'
  clearDrafts2xxResponse:
    description: Success - the status of each item after the update.
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/clearDraftsResult'
        example: &ref_9
          - status: success
            draftId: 331413BF-591C-031E-BAC4-D1C39AA28958
            layerKey: default
          - status: success
            draftId: 7918D0B4-24AC-8A3E-E21C-1302FAE4937E
            layerKey: default
          - status: success
            draftId: ECFB8805-002D-441C-92AE-39FFE9D88A20
            layerKey: default
  putItems4XXResponse:
    description: >-
      Failure - the status of each item after the update and a list of failures
      if it failed.
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/canonItemsResult'
        example: &ref_7
          - _status: failed
            _failures:
              - message: Item already exists.
                code: 400801
                name: ItemAlreadyExists
            _id: 5C9EF1F8-0048-4CE9-91E7-789B857EE73C
            _action: create
          - _status: failed
            _failures:
              - message: Item not found.
                code: 400804
                name: ItemNotFound
            _id: 7918D0B4-24AC-8A3E-E21C-1302FAE4937E
            _action: update
          - _status: success
            _id: ECFB8805-002D-441C-92AE-39FFE9D88A20
            _action: delete
  putLinksItems4XXResponse:
    description: >-
      Failure - the status of each item after the update and a list of failures
      if it failed.
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/canonLinksItemsResult'
        example: &ref_8
          - _status: failed
            _failures:
              - message: Item already exists.
                code: 400801
                name: ItemAlreadyExists
            link_id: '["p_01234","pos_a123"]'
            _action: create
          - _status: failed
            _failures:
              - message: Item not found.
                code: 400804
                name: ItemNotFound
            link_id: '["p_01269","pos_a120"]'
            _action: update
          - _status: success
            link_id: '["p_01270","pos_a191"]'
            _action: delete
  clearDrafts4xxResponse:
    description: >-
      Failure - the status of each draft layer after the clear and a list of
      failures if it failed.
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/clearDraftsResult'
        example: &ref_10
          - status: failed
            failures:
              - message: Layer not found.
                code: 400804
                name: LayerNotFound
            draftId: 331413BF-591C-031E-BAC4-D1C39AA28958
            layerKey: default
          - status: success
            draftId: 7918D0B4-24AC-8A3E-E21C-1302FAE4937E
            layerKey: default
          - status: success
            draftId: ECFB8805-002D-441C-92AE-39FFE9D88A20
            layerKey: default
  retrieveItems200Response:
    description: >-
      Success - The items contained in this dataset, each containing raw values
      only
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          type: array
          items:
            type: object
            properties:
              _id:
                type: string
                description: Item unique identifier
              _modifiedAt:
                type: string
                format: date-time
                description: ISO8601 latest update timestamp of this item
              _access:
                type: string
                description: CRUD permission level setting for this item
                enum:
                  - Item.create
                  - Item.delete
              _sortOrder:
                type: number
                description: The internal row sort order of the item
            additionalProperties:
              type:
                - string
                - boolean
                - number
              description: Item property keys paired with values.
              example: name
        example: &ref_6
          - employee_id: 1
            location: USA
            city: New York
            _id: 970725D4-436A-EDEB-E736-5EA5139F618A
            _access: Item.delete
            _modifiedAt: '2011-10-05T14:48:00.000Z'
          - employee_id: 2
            location: UK
            city: London
            _id: 970725D4-436A-EDEB-E736-5EA5139F618A
            _access: Item.delete
            _modifiedAt: '2011-10-05T14:48:00.000Z'
  clientError4xx:
    description: >-
      Failure - This indicates that the server cannot process the request due to
      one or more potential client errors.
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/clientError4xx'
  tenantError4xx:
    description: >-
      Failure - This indicates that the server cannot process the request due to
      one or more potential client errors.
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/clientError4xx'
        examples:
          tenantId4xx:
            value:
              code: '40401'
              name: TenantOrUserAccountNotFound
              message: The tenant or user account could not be found.
  serverError5xx:
    description: >-
      Failure - This indicates that the server cannot process the request due to
      one or more potential server errors.
    headers:
      X-Amzn-Trace-Id:
        $ref: '#/components/headers/xAmznTraceId'
      Content-Type:
        $ref: '#/components/headers/content-Type'
      Content-Length:
        $ref: '#/components/headers/content-Length'
    content:
      application/json; charset=UTF-8:
        schema:
          $ref: '#/components/schemas/serverError5xx'
paths:
  /api/v1/{tenantId}/datasets:
    get:
      tags:
        - datasets
      summary: List datasets
      description: >-
        Returns a list of JSON objects representing the datasets that are
        present in your tenant.

        Each dataset object contains additional
        [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) [link
        relations](https://en.wikipedia.org/wiki/Link_relation) provided to
        navigate to available next actions.
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      responses:
        '200':
          $ref: '#/responses/datasets'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/files/generate:
    post:
      tags:
        - files
      summary: Create a secure file
      description: >
        Generates a temporary secure file location and provides GET and PUT URLs
        to read from and write to the location.

        Data written to the location is securely encrypted at rest, and will be
        automatically deleted after a set period.

        The GET and PUT URLs also have fixed lifespans so that access is
        completely restricted once a reasonable usage period has concluded.


        This secure location can be used in tandem with import and export
        processes.


        For
        [import](./#tag/datasets/paths/~1api~1v1~1{tenantId}~1datasets~1{datasetId}~1items~1import/put),
        you would upload your required updates via the PUT URL and then send us
        the GET URL to process the update.


        For
        [export](./#tag/datasets/paths/~1api~1v1~1{tenantId}~1datasets~1{datasetId}~1export~1{exportFormat}/post),
        you would send us the PUT URL and use the GET URL to access your
        requested data once processing is complete.


        See the respective endpoints for further details.
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        required: true
        content:
          application/json; charset=UTF-8:
            schema:
              type: object
              description: type and encoding of file
              properties:
                targetType:
                  type: string
                  description: Determines format of the data written to the file
                  enum:
                    - json
                    - csv
                    - tsv
                  example: json
                targetEncoding:
                  type: string
                  enum:
                    - gzip
                    - identity
                  description: >-
                    Determines whether the data written to the file is
                    compressed by [gzip](https://en.wikipedia.org/wiki/Gzip)
                  example: identity
              required:
                - targetType
                - targetEncoding
      responses:
        '200':
          description: >-
            Success - A pair of URLs that allows the resource to be updated and
            the content fetched
          headers:
            X-Amzn-Trace-Id:
              $ref: '#/components/headers/xAmznTraceId'
            Content-Type:
              $ref: '#/components/headers/content-Type'
            Content-Length:
              $ref: '#/components/headers/content-Length'
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/generateTemporaryFile'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/datasets/create:
    post:
      tags:
        - datasets
      summary: Create dataset
      description: >
        Creates a new dataset resource with a set of defined properties. Item
        data is uploaded via subsequent requests.
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        required: true
        content:
          application/json; charset=UTF-8:
            schema:
              $ref: '#/components/schemas/createDataset'
      responses:
        '200':
          $ref: '#/responses/createDataset'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/datasets/{datasetId}:
    post:
      tags:
        - datasets
      summary: Update dataset
      description: >
        Updates a dataset resource. The configuration in the request payload is
        merged onto the existing dataset configuration.


        The value `null` may be used for keys that are not required in order to
        remove them. For example, `treeId` and `treeParentId` may be set to
        `null` in order to convert a hierarchical dataset into a flat dataset.


        Properties are merged based on the `key` value. If an existing key is
        matched the property is updated, otherwise a new property is created. If
        it is necessary to delete properties, the `deleteOmittedProperties`
        query parameter must be used. If set to `true`, any existing properties
        not matched in the provided payload by `key` will be removed.
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/datasetIdPathParam'
        - $ref: '#/components/parameters/deleteOmittedPropertiesQueryParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        required: true
        content:
          application/json; charset=UTF-8:
            schema:
              $ref: '#/components/schemas/updateDataset'
      responses:
        '200':
          $ref: '#/responses/updateDataset'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
    get:
      tags:
        - datasets
      summary: Dataset metadata
      description: >-
        Returns a representation of the dataset resource

        ### Drafts

        Each dataset object may contain a list of drafts. A draft contains a set
        of changes that may be applied on top of a dataset. It may be used to
        model different scenarios without modifying the underlying dataset items
        themselves. Once satisfied with the changes you may wish to apply them
        to the dataset to make them permanent changes. We provide additional
        [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS) [link
        relations](https://en.wikipedia.org/wiki/Link_relation) to navigate to
        available next actions.

        ### Linking dataset relationships

        Each dataset object may contain a list of linking dataset relationships.
        If a dataset is part of more than one links relationships, the list will
        contain more than one objects. A source dataset will contain `"link"`,
        and `"target"`, a linking dataset will contain `"source"` and
        `"target"`, while a target dataset will contain `"source"` and `"link"`.
        We provide additional [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS)
        [link relations](https://en.wikipedia.org/wiki/Link_relation) to
        navigate to available next actions.

        ### Linking dataset export

        Once you have received the response from this endpoint we have prepared
        all the data necessary for all possible linking calculations in this
        tenant. Track the linking relationship you care to calculate and follow
        the HATEOAS relation under
        `$.linkingRelationships[index]._links.export`. Use this content to
        perform your next request to our export endpoint.
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/datasetIdPathParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      responses:
        '200':
          $ref: '#/responses/retrieveDataset'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/datasets/{datasetId}/export/{exportFormat}:
    post:
      tags:
        - datasets
      summary: Async export including calculations
      description: >
        Creates a job in the background and produces a
        [`jobTicket`](../api/#tag/jobTicket) resource which in turn contains a
        URL to poll for the requested job data. Other endpoints will lead you to
        the correct usage of this endpoint via HATEOAS links.

        ### Calculations

        &#x2705; Pre-Filter </br> &#x2705; Post-Filter </br>         &#9881;
        Linking Calculations (Configurable in Request Body)</br> &#9881;
        On-Demand (Configurable in Request Body)
      parameters:
        - $ref: '#/components/parameters/encodingParam'
        - $ref: '#/components/parameters/encodingParamUpdated'
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/datasetIdPathParam'
        - $ref: '#/components/parameters/exportFormatPathParam'
        - $ref: '#/components/parameters/includeBOMQueryParam'
        - $ref: '#/components/parameters/lineEndingsQueryParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        required: false
        content:
          application/json; charset=UTF-8:
            schema:
              type: object
              properties:
                dataset:
                  $ref: '#/components/schemas/datasetLinking'
                resultLocation:
                  $ref: '#/components/schemas/resultLocation'
                exportLocation:
                  type: object
                  description: >-
                    Provide this object to divert your result data to a storage
                    location of your choice. It must be a secure resource
                    compatible with the [presigned
                    URL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html)
                    mechanism for an object for which you own the lifecycle,
                    which our API can use to upload data via an http `"PUT"`
                    request. This will be deprecated in favour of
                    `resultLocation`.
                  properties:
                    method:
                      $ref: '#/components/schemas/methodAsString'
                    url:
                      type: string
                      format: uri
                      description: The URL where our API will attempt to "PUT" data to
                      example: https://example.com
                  required:
                    - method
                    - url
                callback:
                  $ref: '#/components/schemas/callbackPayload'
                executeOnDemand:
                  type: array
                  items:
                    type: string
                  description: >-
                    On-demand properties to calculate as part of the export.
                    These will need to be configured ahead of time, and passed
                    to the API in the correct order for your on-demand
                    calculation to be meaningful.
                  example:
                    - onDemandProperty1
                    - onDemandProperty2
                  minItems: 1
                  uniqueItems: true
                query:
                  type: object
                  description: Query object to apply filter on exported data
                  properties:
                    output:
                      type: object
                      description: Output filtering configuration
                      properties:
                        filter:
                          $ref: '#/components/schemas/mongoFilter'
                        projection:
                          type: object
                          description: >-
                            Column filtering and sorting using internal
                            projection object
                          format: '{ [propertyKey]: integer }'
                          example:
                            id: 1
                            age: 0
                            salary: 1
                            employeeGrade: 2
                            role: 3
                        projectionMode:
                          type: string
                          description: >-
                            How projection object will be applied regarding
                            existing default projection
                          enum:
                            - add
                            - replace
                          default: add
      responses:
        '202':
          $ref: '#/responses/jobTicket'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
    get:
      tags:
        - datasets
      summary: Sync export including calculations
      description: >
        Alternative to the POST version of the endpoint, for integrations that
        can only rely on *synchronous* GET requests. Use of this endpoint is
        **not recommended** as it might lead to timeouts if the data
        calculations exceed a certain size.

        ### Calculations

        &#x2705; Pre-Filter<br> &#x2705; Post-Filter<br> &#x274C; Linking
        Calculations<br> &#x274C; On-Demand
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/datasetIdPathParam'
        - $ref: '#/components/parameters/exportFormatPathParam'
        - $ref: '#/components/parameters/includeBOMQueryParam'
        - $ref: '#/components/parameters/lineEndingsQueryParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      responses:
        '200':
          description: Success - The content of the dataset including calculated properties
          headers:
            X-Amzn-Trace-Id:
              $ref: '#/components/headers/xAmznTraceId'
            Content-Type:
              $ref: '#/components/headers/content-Type'
            Content-Length:
              $ref: '#/components/headers/content-Length'
          content:
            application/json; charset=UTF-8:
              schema:
                type: object
                properties:
                  headers:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        name:
                          type: string
                        type:
                          type: string
                      required:
                        - key
                        - name
                        - type
                  rows:
                    type: array
                    items:
                      type:
                        - string
                        - boolean
                        - number
                        - 'null'
                  columns:
                    type: array
                    items:
                      type:
                        - string
                        - boolean
                        - number
                        - 'null'
                required:
                  - headers
              examples:
                jsonRows:
                  $ref: '#/examples/jsonRows'
                jsonColumns:
                  $ref: '#/examples/jsonColumns'
                jsonObjects:
                  $ref: '#/examples/jsonObjects'
            text/csv; charset=UTF-8:
              schema:
                type: string
              examples:
                csv:
                  $ref: '#/examples/csv'
            text/tab-separated-values; charset=UTF-8:
              schema:
                type: string
              examples:
                tsv:
                  $ref: '#/examples/tsv'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/datasets/{datasetId}/items:
    get:
      summary: Sync export excluding calculations
      description: |
        A synchronous endpoint that retrieves data from Orgvue.
      tags:
        - datasets
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/datasetIdPathParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      responses:
        '200':
          $ref: '#/responses/retrieveItems200Response'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
    post:
      summary: Sync export with filters excluding calculations
      description: >
        A synchronous endpoint that retrieves and filters data from Orgvue.
        [Internal properties](../egress/retrieve-items/#internal-properties) are
        only returned when requested via a projection.
      tags:
        - datasets
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/datasetIdPathParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        content:
          application/json; charset=UTF-8:
            schema:
              $ref: '#/components/schemas/baseFilterAndProjection'
      responses:
        '200':
          $ref: '#/responses/retrieveItems200Response'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
    put:
      summary: Sync import
      description: >-
        A synchronous endpoint that enables data ingress into Orgvue. The
        payload consists of a sequence of
        [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete)
        items operations, one each for an object of the dataset. Ingress
        behaviour can be controlled by the query parameters provided. Setting
        **an attribute to `null`** has the effect of **clearing the value** in
        Orgvue.
      tags:
        - datasets
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/datasetIdPathParam'
        - $ref: '#/components/parameters/dateFormatQueryParam'
        - $ref: '#/components/parameters/onPropertyAccessDeniedQueryParam'
        - $ref: '#/components/parameters/onItemAccessDeniedQueryParam'
        - $ref: '#/components/parameters/onActionValidationFailureQueryParam'
        - $ref: '#/components/parameters/autoIdQueryParam'
        - $ref: '#/components/parameters/idKeyQueryParam'
        - $ref: '#/components/parameters/mergeKeyQueryParam'
        - $ref: '#/components/parameters/implicitDeleteQueryParam'
        - $ref: '#/components/parameters/clearTokenQueryParam'
        - $ref: '#/components/parameters/noopTokenQueryParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        content:
          application/json; charset=UTF-8:
            schema:
              type: array
              title: Standard actions
              items:
                type: object
                description: >-
                  May contain additional json attribute pairs if you are using
                  `autoId` or `idKey` query parameters
                required:
                  - _action
                properties:
                  _action:
                    $ref: '#/components/schemas/action'
                  _id:
                    type: string
                    description: >-
                      The internal value used to uniquely identify an item in
                      the dataset by Orgvue in the default mode.
                    example: 5C9EF1F8-0048-4CE9-91E7-789B857EE73C
                  _sortOrder:
                    type: number
                    description: The internal row sort order of the item
                    example: 12
                additionalProperties:
                  type:
                    - string
                    - boolean
                    - number
                  description: >-
                    Dataset property keys paired with values, to be updated as
                    part of this request. The keys must match dataset properties
                    exactly. If you have specified the `autoId` query parameter,
                    you must provide a value for the property mapped to
                    `autoId`. If you have specified one or more `idKey`s you
                    must provide a value for each of the `idKey` properties. If
                    you have specified one or more `mergeKey`s you must provide
                    a value for each of the `mergeKey` properties.
                  example: Age
            example: &ref_2
              - _action: createOrUpdate
                position_id: 10
                position_title: CEO
              - _action: createOrUpdate
                position_id: 12
                position_title: Admin Assistant
              - _action: delete
                position_id: 15
      responses:
        '200':
          $ref: '#/responses/putItems200Response'
        4XX:
          $ref: '#/responses/putItems4XXResponse'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/links/create:
    post:
      summary: Create links dataset
      description: |
        Creates a new links dataset resource.
      tags:
        - links
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        required: true
        content:
          application/json; charset=UTF-8:
            schema:
              $ref: '#/components/schemas/createLinksDataset'
      responses:
        '200':
          $ref: '#/responses/createLinksDataset'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/links/{linksDatasetId}:
    post:
      tags:
        - links
      summary: Update links dataset
      description: >
        Updates a links dataset resource. The configuration in the request
        payload is merged onto the existing links dataset configuration.


        The value `null` may be used for keys that are not required in order to
        remove them. For example, `tags` may be set to `null` in order to
        completely remove tags from the links dataset.


        Additional properties are merged based on the `key` value. If an
        existing key is matched the property is updated, otherwise a new
        property is created. If it is necessary to delete properties, the
        `deleteOmittedProperties` query parameter must be used. If set to
        `true`, any existing properties not matched in the provided payload by
        `key` will be removed. Note that this does not apply to the core
        properties `from_id`, `to_id`, `allocation` and `link_id`, which may not
        be modified.
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/linksDatasetIdPathParam'
        - $ref: '#/components/parameters/deleteOmittedPropertiesQueryParamLinks'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        required: true
        content:
          application/json; charset=UTF-8:
            schema:
              $ref: '#/components/schemas/updateLinksDataset'
      responses:
        '200':
          $ref: '#/responses/updateLinksDataset'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/links/{linksDatasetId}/populate:
    put:
      tags:
        - links
      summary: Populate links dataset
      description: >
        If you have a single dataset which contains the `from_id`, `to_id` and
        `allocation` property of a links dataset you have already created, you
        can use this endpoint to automate the uploading of nodes to that links
        dataset.

         *Note*: this endpoint will create or replace *all* nodes in the links dataset; any items in the links dataset but not in either of the source or target datasets will be deleted.
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/linksDatasetIdPathParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
        - $ref: '#/components/parameters/encodingParamUpdated'
      requestBody:
        content:
          application/json; charset=UTF-8:
            schema:
              type: object
              required:
                - sourceDatasetId
                - targetDatasetAutoId
              properties:
                sourceDatasetId:
                  type: string
                  description: >-
                    The id of the source dataset that contains the `from_id` and
                    `to_id` properties of the links dataset
                  example: 6586F21B-AD4D-4D06-A309-712AF47184A2
                targetDatasetAutoId:
                  type: string
                  description: The property which holds the `autoId` of the target dataset
                  example: positionsId
                allocationId:
                  type: string
                  description: >-
                    The property which holds the `allocation` property of the
                    links dataset
                  example: fte
                resultLocation:
                  $ref: '#/components/schemas/resultLocation'
                callback:
                  $ref: '#/components/schemas/callbackPayload'
      responses:
        '202':
          $ref: '#/responses/jobTicket'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/links/{linksDatasetId}/items:
    put:
      summary: Sync import
      description: >-
        A synchronous endpoint for modifying data in linking datasets (with type
        `"LINKS"`).

        The payload consists of a sequence of
        [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete)
        items operations, one each for an object of the dataset.

        Records are uniquely identified via the combination of the `from_id` and
        `to_id` properties. These values will be used to generate the unique
        `autoId` value for a specific link.
      tags:
        - links
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/linksDatasetIdPathParam'
        - $ref: '#/components/parameters/dateFormatQueryParam'
        - $ref: '#/components/parameters/onPropertyAccessDeniedQueryParam'
        - $ref: '#/components/parameters/onItemAccessDeniedQueryParam'
        - $ref: '#/components/parameters/onActionValidationFailureQueryParam'
        - $ref: '#/components/parameters/implicitDeleteQueryParam'
        - $ref: '#/components/parameters/clearTokenQueryParam'
        - $ref: '#/components/parameters/noopTokenQueryParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        required: true
        content:
          application/json; charset=UTF-8:
            schema:
              description: >-
                When updating a linking dataset (dataset with type `"LINKS"`),
                certain properties are required in order to correctly link
                between nodes in the two linked datasets.
              type: array
              title: Links actions
              items:
                type: object
                description: May contain additional properties such as 'allocation'.
                required:
                  - _action
                  - from_id
                  - to_id
                properties:
                  _action:
                    $ref: '#/components/schemas/action'
                  from_id:
                    type:
                      - string
                      - boolean
                      - number
                      - 'null'
                    description: >-
                      The value of the autoId property of the node in the linked
                      dataset you wish to create a link 'from'. You can review
                      which dataset is configured as the 'from' dataset in
                      Orgvue Settings.
                  to_id:
                    type:
                      - string
                      - boolean
                      - number
                      - 'null'
                    description: >-
                      The value of the autoId property of the node in the linked
                      dataset you wish to create a link 'to'. You can review
                      which dataset is configured as the 'to' dataset in Orgvue
                      Settings.
                    example: 5C9EF1F8-0048-4CE9-91E7-789B857EE73C
                additionalProperties:
                  type:
                    - string
                    - boolean
                    - number
                  description: >-
                    Dataset property keys paired with values, to be updated as
                    part of this request. The keys must match dataset properties
                    exactly. Note that the value for the `autoId` property will
                    be generated from the required `from_id` and `to_id` values.
                    If explicitly supplied it will be ignored.
                  example: Age
            example: &ref_3
              - _action: create
                from_id: p_01234
                to_id: pos_a123
                allocation: 1
              - _action: update
                from_id: p_01269
                to_id: pos_a120
                allocation: 0.5
              - _action: createOrReplace
                from_id: p_01270
                to_id: pos_a191
      responses:
        '200':
          $ref: '#/responses/putLinksItems200Response'
        4XX:
          $ref: '#/responses/putLinksItems4XXResponse'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/datasets/{datasetId}/items/import:
    put:
      tags:
        - datasets
      summary: Async import
      description: >
        An asynchronous endpoint that enables data ingress into Orgvue.


        Creates a [`jobTicket`](../api/#tag/jobTicket) resource which in turn
        contains a URL to poll for the requested job data.

        Ingress behaviour can be controlled by the query parameters provided.


        You can use this endpoint with the resources produced by the ["Create a
        secure
        file"](../api/#tag/files/paths/~1api~1v1~1%7BtenantId%7D~1files~1generate/post)
        endpoint.

        Before making a request to this endpoint, upload your data to the
        intended import location in either JSON or CSV format. JSON payloads
        should have the same structure as the example provided for the [PUT
        items
        endpoint](../api/#tag/datasets/paths/~1api~1v1~1%7BtenantId%7D~1datasets~1%7BdatasetId%7D~1items/put).

        Data provided in CSV format should follow the rules outlined in the
        ["Import Items from a
        CSV"](../items/usage-examples/#import-items-from-a-csv) section of the
        Usage Examples.


        Note the following recommended max files sizes when used with Async
        import:


        | File Type |Uncompressed| Zipped |

        |-----------|------------|--------|

        | JSON      | 200MB      | 300MB  |

        | CSV       | 450MB      | 400MB  |  


        If your payload exceeds these recomendations we advise splitting larger
        updates into batches. 
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/datasetIdPathParam'
        - $ref: '#/components/parameters/dateFormatQueryParam'
        - $ref: '#/components/parameters/onPropertyAccessDeniedQueryParam'
        - $ref: '#/components/parameters/onItemAccessDeniedQueryParam'
        - $ref: '#/components/parameters/onActionValidationFailureQueryParam'
        - $ref: '#/components/parameters/autoIdQueryParam'
        - $ref: '#/components/parameters/idKeyQueryParam'
        - $ref: '#/components/parameters/mergeKeyQueryParam'
        - $ref: '#/components/parameters/implicitDeleteQueryParam'
        - $ref: '#/components/parameters/clearTokenQueryParam'
        - $ref: '#/components/parameters/noopTokenQueryParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        content:
          application/json; charset=UTF-8:
            schema:
              $ref: '#/components/schemas/importPayload'
      responses:
        '202':
          $ref: '#/responses/jobTicket'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/links/{linksDatasetId}/items/import:
    put:
      tags:
        - links
      summary: Async import
      description: >
        An asynchronous endpoint that enables data ingress into Orgvue.


        Creates a [`jobTicket`](../api/#tag/jobTicket) resource which in turn
        contains a URL to poll for the requested job data.

        Ingress behaviour can be controlled by the query parameters provided.


        You can use this endpoint with the resources produced by the [temporary
        resources](../api/#tag/files/paths/~1api~1v1~1%7BtenantId%7D~1files~1generate/post)
        endpoint.

        Before making a request to this endpoint you should upload data to the
        intended import location in the same format as the payload for the [PUT
        links items
        endpoint](../api/#tag/links/paths/~1api~1v1~1%7BtenantId%7D~1links~1%7BdatasetId%7D~1items/put).


        Note that we advise splitting larger updates into batches of no more
        than 25,000 actions for up to 100 properties. If more properties are
        being updated the number of actions in a batch should be reduced
        proportionally.
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/linksDatasetIdPathParam'
        - $ref: '#/components/parameters/dateFormatQueryParam'
        - $ref: '#/components/parameters/onPropertyAccessDeniedQueryParam'
        - $ref: '#/components/parameters/onItemAccessDeniedQueryParam'
        - $ref: '#/components/parameters/onActionValidationFailureQueryParam'
        - $ref: '#/components/parameters/implicitDeleteQueryParam'
        - $ref: '#/components/parameters/clearTokenQueryParam'
        - $ref: '#/components/parameters/noopTokenQueryParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        content:
          application/json; charset=UTF-8:
            schema:
              $ref: '#/components/schemas/importPayload'
      responses:
        '202':
          $ref: '#/responses/jobTicket'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/drafts:
    post:
      summary: List drafts
      description: >
        A synchronous endpoint that retrieves drafts for a tenant from Orgvue
        with specified filters and/ or projections.


        **Note**: You can only filter by a draft's `name`, `description` or
        `createdBy`.
      tags:
        - drafts
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        content:
          application/json; charset=UTF-8:
            schema:
              type: object
              description: The MongoDB Filter and Projection fields for querying
              properties:
                filter:
                  type: object
                  description: >-
                    Row level filtering using MongoDB query. Note: for this
                    endpoint you can only filter by a draft's `name`,
                    `description` or `createdBy`.
                  format: MongoDB query
                projection:
                  $ref: '#/components/schemas/itemsProjection'
            example:
              filter:
                name: John Smith
              projection:
                draftId: 1
                name: 1
                description: 1
      responses:
        '200':
          description: Success - List of draft resources
          headers:
            X-Amzn-Trace-Id:
              $ref: '#/components/headers/xAmznTraceId'
            Content-Type:
              $ref: '#/components/headers/content-Type'
            Content-Length:
              $ref: '#/components/headers/content-Length'
          content:
            application/json; charset=UTF-8":
              schema:
                $ref: '#/components/schemas/retrieveDraft'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/drafts/{draftId}:
    get:
      tags:
        - drafts
      summary: Draft metadata
      description: >
        Returns a representation of the draft resource.


        We provide additional [HATEOAS](https://en.wikipedia.org/wiki/HATEOAS)
        [_links](https://en.wikipedia.org/wiki/Link_relation) to navigate to
        available next actions.
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/draftIdPathParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      responses:
        '200':
          $ref: '#/responses/retrieveDraft'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/drafts/actions:
    post:
      tags:
        - drafts
      summary: Async export excluding calculations
      description: >-
        An asynchronous endpoint that returns a `jobTicket` resource, which in
        turn contains a URL to poll for the requested data. An array of item
        actions represented by the requested draft layers will be written to the
        result location once the process is complete. These actions may be sent
        to the [items import
        endpoint](./#tag/items/paths/~1api~1v1~1%7BtenantId%7D~1datasets~1%7BdatasetId%7D~1items~1import/put)
        to apply the draft changes to the dataset.
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/encodingParam'
        - $ref: '#/components/parameters/encodingParamUpdated'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        content:
          application/json; charset=UTF-8:
            schema:
              $ref: '#/components/schemas/draftLayers'
      responses:
        '202':
          $ref: '#/responses/jobTicket'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/drafts/clear:
    post:
      tags:
        - drafts
      summary: Clear draft actions
      description: >
        Remove all or specific edits, changes, or additions that you have made
        to the dataset in draft. 


        To remove specific edits include the filter object and properties you
        want to filter by.


        Otherwise, all edits will be removed and the dataset will be restored to
        its original state. This would effectively erase all of your work on the
        draft.
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        content:
          application/json; charset=UTF-8:
            schema:
              type: object
              required:
                - layers
              properties:
                layers:
                  type: array
                  description: >-
                    An array of draft layer objects in the order in which they
                    will be cleared.
                  items:
                    type: object
                    properties:
                      draftId:
                        type: string
                        format: uuid
                        description: >-
                          The UUID for the draft containing the layer you wish
                          to resolve.
                        example: 36A1E02D-DC20-61C5-A11F-DD85440C652C
                      layerKey:
                        type: string
                        example: default
                        description: >-
                          The key for the layer within the draft designated by
                          the `draftId` you wish to resolve. This will commonly
                          be the value `"default"`.
                    required:
                      - draftId
                      - layerKey
                filter:
                  type: object
                  description: >-
                    An object containing mongoDB queries that filter the actions
                    you want cleared from the draft layers specified in
                    'layers'.
                  additionalProperties:
                    type:
                      - string
                      - boolean
                      - number
                    description: AutoId property key paired with values.
              example:
                layers:
                  - draftId: 331413BF-591C-031E-BAC4-D1C39AA28958
                    layerKey: default
                  - draftId: 7918D0B4-24AC-8A3E-E21C-1302FAE4937E
                    layerKey: default
                  - draftId: ECFB8805-002D-441C-92AE-39FFE9D88A20
                    layerKey: default
                filter:
                  location:
                    $in:
                      - UK
                      - USA
                  approval_status: Approved
      responses:
        '200':
          $ref: '#/responses/clearDrafts2xxResponse'
        4XX:
          $ref: '#/responses/clearDrafts4xxResponse'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/datasets/{datasetId}/applyDrafts:
    post:
      tags:
        - datasets
      summary: Apply draft data to a dataset
      description: >
        An asynchronous endpoint that returns a `jobTicket` resource, which in
        turn contains a URL to poll for the result of the draft application.


        The updates represented by the combined drafts will be applied to the
        dataset as if sent to the [items import
        endpoint](./#tag/items/paths/~1api~1v1~1%7BtenantId%7D~1datasets~1%7BdatasetId%7D~1items~1import/put).
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/datasetIdPathParam'
        - $ref: '#/components/parameters/encodingParam'
        - $ref: '#/components/parameters/encodingParamUpdated'
        - $ref: '#/components/parameters/onPropertyAccessDeniedQueryParam'
        - $ref: '#/components/parameters/onItemAccessDeniedQueryParam'
        - $ref: '#/components/parameters/onActionValidationFailureQueryParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        content:
          application/json; charset=UTF-8:
            schema:
              allOf:
                - $ref: '#/components/schemas/draftLayers'
      responses:
        '202':
          $ref: '#/responses/jobTicket'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
  /api/v1/{tenantId}/datasets/{datasetId}/updateOnDemand:
    post:
      tags:
        - datasets
      summary: Evaluate on-demand calculations
      description: >
        An asynchronous endpoint that returns a `jobTicket` resource, which in
        turn contains a URL to poll for the result of the job.


        To use this endpoint your dataset needs to be configured ahead of time
        to contain on-demand calculations. Using this endpoint re-calculates all
        values for the on-demand properties in your dataset, and then applies
        the changes to the dataset.


        **Note:** This endpoint performs an update on your dataset. As such, it
        is a governance issue on your side to ensure there are no other updates
        sent to the dataset at the same time. As with all updates to your
        datasets: the last update wins.
      parameters:
        - $ref: '#/components/parameters/tenantIdPathParam'
        - $ref: '#/components/parameters/datasetIdPathParam'
        - $ref: '#/components/parameters/acceptEncodingHeader'
        - $ref: '#/components/parameters/acceptEncodingHeader'
      requestBody:
        required: false
        content:
          application/json; charset=UTF-8:
            schema:
              type: object
              properties:
                executeOnDemand:
                  type: array
                  items:
                    type: string
                  description: >-
                    Array of unique on-demand properties to calculate and update
                    in the dataset. These properties must be configured ahead of
                    time. They must be passed to the API in the correct order
                    for your on-demand calculation to be meaningful.
                  example:
                    - onDemandProperty1
                    - onDemandProperty2
                  minItems: 1
                  uniqueItems: true
                dataset:
                  $ref: '#/components/schemas/datasetLinking'
                callback:
                  $ref: '#/components/schemas/callbackPayload'
                resultLocation:
                  $ref: '#/components/schemas/resultLocation'
              required:
                - executeOnDemand
      responses:
        '202':
          $ref: '#/responses/jobTicket'
        4XX:
          $ref: '#/responses/clientError4xx'
        5XX:
          $ref: '#/responses/serverError5xx'
examples:
  csv:
    value: >
      id,name,parent_id,_change,_depth,_descendants,_has_unique_id,_height,_is_duplicate,_is_ghost,_is_leaf,_is_orphan,_label,_layers,_level_1,_level_2,_outgoing_count,_records,_span,_subtree

      a,Ana,,none,1,,TRUE,2,FALSE,FALSE,FALSE,FALSE,Ana,2,Ana,,2,1,2,

      b,Bob,a,none,2,Ana,TRUE,1,FALSE,FALSE,TRUE,FALSE,Bob,1,Ana,Bob,0,1,,Ana

      c,Caz,a,none,2,Ana,TRUE,1,FALSE,FALSE,TRUE,FALSE,Caz,1,Ana,Caz,0,1,,Ana
    summary: A sample csv string
  tsv:
    value: "id\tname\tparent_id\t_change\t_depth\t_descendants\t_has_unique_id\t_height\t_is_duplicate\t_is_ghost\t_is_leaf\t_is_orphan\t_label\t_layers\t_level_1\t_level_2\t_outgoing_count\t_records\t_span\t_subtree\na\tAna\t\tnone\t1\t\tTRUE\t2\tFALSE\tFALSE\tFALSE\tFALSE\tAna\t2\tAna\t\t2\t1\t2\t\nb\tBob\ta\tnone\t2\tAna\tTRUE\t1\tFALSE\tFALSE\tTRUE\tFALSE\tBob\t1\tAna\tBob\t0\t1\t\tAna\nc\tCaz\ta\tnone\t2\tAna\tTRUE\t1\tFALSE\tFALSE\tTRUE\tFALSE\tCaz\t1\tAna\tCaz\t0\t1\t\tAna\n"
    summary: A sample tsv string
  jsonObjects:
    value:
      - id: a
        name: Ana
        parent_id: null
      - id: b
        name: Bob
        parent_id: a
      - id: c
        name: Caz
        parent_id: a
    summary: A sample jsonObjects array of objects
  jsonColumns:
    value:
      headers:
        - key: id
          name: Id
          type: text
        - key: name
          name: Name
          type: text
        - key: parent_id
          name: Parent Id
          type: text
        - key: _change
          name: Change
          type: text
      columns:
        - - a
          - b
          - c
        - - Ana
          - Bob
          - Caz
        - - null
          - a
          - a
    summary: A sample jsonColumns object
  jsonRows:
    value:
      headers:
        - key: id
          name: Id
          type: text
        - key: name
          name: Name
          type: text
        - key: parent_id
          name: Parent Id
          type: text
        - key: _change
          name: Change
          type: text
      rows:
        - - a
          - Ana
          - null
        - - b
          - Bob
          - a
        - - c
          - Caz
          - a
    summary: A sample jsonRows object
  itemsRequestBody: *ref_2
  linksItemsRequestBody: *ref_3
  putItems200Response: *ref_4
  putLinksItems200Response: *ref_5
  retrieveItems200Response: *ref_6
  putItems4xxResponse: *ref_7
  putLinksItems4xxResponse: *ref_8
  clearDrafts2xxResponse: *ref_9
  clearDrafts4xxResponse: *ref_10
  createLinksDatasetResponseProperties: *ref_11
  genericDatasetProperties: *ref_1
