openapi: 3.2.0
info:
title: Visier Data In Direct Data Intake API
description: Visier APIs for sending data to Visier and running data load jobs.
license:
name: Apache License, Version 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 22222222.99201.3040
security:
- ApiKeyAuth: []
BearerAuth: []
- ApiKeyAuth: []
CookieAuth: []
- ApiKeyAuth: []
OAuth2Auth: []
tags:
- name: DirectDataIntake
x-displayName: Direct Data Intake
description: 'Use the Direct Data Intake API to load data directly into Visier objects. These objects can be delivered as part of Visier Blueprint, locally modified objects, or even completely custom objects. Objects must be released to production to receive data through the DDI API.
You can load data into:
- Subjects
- Events
- Parent-child dimensions
- Multi-value properties'
paths:
/v1/data/directloads/{draftId}/configs:
get:
tags:
- DirectDataIntake
summary: Get the direct data intake configuration
description: Get the direct data intake configuration.
operationId: DirectDataIntake_GetConfig
parameters:
- name: draftId
in: path
description: The unique identifier of the project to load data into. Currently, the only supported value is `prod` to update the production version.
required: true
schema:
type: string
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.DirectDataLoadConfigDTO'
put:
tags:
- DirectDataIntake
summary: Update the direct data intake configuration
description: "Configure the data intake settings, such as the direct data intake job type. Only provide values for the configuration options that should change.\n\n Configuration options that are not present in the PUT request are ignored and left unchanged."
operationId: DirectDataIntake_PutConfig
parameters:
- name: draftId
in: path
description: The unique identifier of the project to load data into. Currently, the only supported value is `prod` to update the production version.
required: true
schema:
type: string
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.DirectDataLoadConfigDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.DirectDataLoadConfigDTO'
/v1/data/directloads/{draftId}/schemas/{objectName}:
get:
tags:
- DirectDataIntake
summary: Retrieve an object's data load schema
description: "Gets the load schema for a specified object. The object's load schema represents the structure that the data upload file must follow to upload data to the object.\n\n In the load schema, the listed columns must be present in the data file as column headers and exactly match the load schema (case sensitive), however, only the columns whose `isMandatory` field is `true` must contain values in the data file."
operationId: DirectDataIntake_ObjectSchema
parameters:
- name: draftId
in: path
description: The unique identifier of the project to load data into. Currently, the only supported value is `prod` to update the production version.
required: true
schema:
type: string
- name: objectName
in: path
description: The name of the object to return the load schema for.
required: true
schema:
type: string
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.DirectDataSchemaDTO'
/v1/data/directloads/{draftId}/transactions:
get:
tags:
- DirectDataIntake
summary: Retrieve a list of open transactions
description: Get a list of all open transactions. Doesn't return committed transactions or rolled back transactions.
operationId: DirectDataIntake_ListTransactions
parameters:
- name: draftId
in: path
description: Optionally specify the unique identifier of a project to retrieve open transactions from. Currently, the only supported value is `prod` to retrieve open transactions for the production version.
required: true
schema:
type: string
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.DirectDataListTransactionsResponseDTO'
post:
tags:
- DirectDataIntake
summary: Start a direct data intake transaction
description: "Create a transaction to contain your data files. To upload files to objects in Visier, you must first start a transaction.\n\n After starting a transaction and uploading files to the transaction, you can commit the transaction to process the uploaded files or roll back the transaction to discard the uploaded files."
operationId: DirectDataIntake_StartTransaction
parameters:
- name: draftId
in: path
description: The unique identifier of the project to load data into. Currently, the only supported value is `prod` to update the production version.
required: true
schema:
type: string
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.DirectDataTransactionStartResponseDTO'
/v1/data/directloads/{draftId}/transactions/{transactionId}:
get:
tags:
- DirectDataIntake
summary: Check transaction status
description: Retrieve the status of a committed transaction's processing job.
operationId: DirectDataIntake_JobStatus
parameters:
- name: draftId
in: path
description: The unique identifier of the project to load data into. Currently, the only supported value is `prod` to update the production version.
required: true
schema:
type: string
- name: transactionId
in: path
description: The unique identifier of the transaction.
required: true
schema:
type: string
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.DirectDataJobStatusResponseDTO'
post:
tags:
- DirectDataIntake
summary: Commit a transaction
description: "Process a transaction and its uploaded data files. This starts a processing job to load the data files into Visier.\n\n After committing a transaction, you cannot upload additional files to the transaction. Use the `Check transaction status` endpoint to monitor the progress of the processing job."
operationId: DirectDataIntake_CommitTransaction
parameters:
- name: draftId
in: path
description: The unique identifier of the project to load data into. Currently, the only supported value is `prod` to update the production version.
required: true
schema:
type: string
- name: transactionId
in: path
description: The unique identifier of the transaction.
required: true
schema:
type: string
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.DirectDataUploadFileResponseDTO'
delete:
tags:
- DirectDataIntake
summary: Roll back a transaction
description: "Rolls back the specified transaction. This discards all files uploaded within the transaction and deletes the transaction.\n\n After rolling back a transaction, you cannot use the transaction to upload data files."
operationId: DirectDataIntake_RollbackTransaction
parameters:
- name: draftId
in: path
description: The unique identifier of the project to load data into. Currently, the only supported value is `prod` to update the production version.
required: true
schema:
type: string
- name: transactionId
in: path
description: The unique identifier of the transaction.
required: true
schema:
type: string
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.DirectDataUploadFileResponseDTO'
/v1/data/directloads/{draftId}/transactions/{transactionId}/{objectName}/sample-data:
post:
tags:
- DirectDataIntake
summary: Load sample data
description: Load sample data in a previously-created transaction. The data is not processed in Visier until you commit the transaction. Sample data is available for `employee`, `employee_exit`, `employment_start`, and `organization_hierarchy`.
operationId: DirectDataIntake_LoadSampleData
parameters:
- name: draftId
in: path
required: true
schema:
type: string
- name: transactionId
in: path
required: true
schema:
type: string
- name: objectName
in: path
required: true
schema:
type: string
- name: sampleName
in: query
description: "The name of the target object to load sample data. Sample data is available for:\n * `employee`: The Employee subject.\n * `employee_exit`: The Employee Exit event.\n * `employment_start`: The Employment Start event.\n * `organization_hierarchy`: The Organization Hierarchy dimension."
schema:
type: string
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/servicing.DirectDataUploadFileResponseDTO'
/v1/data/directloads/{draftId}/transactions/{transactionId}/{objectName}:
put:
tags:
- DirectDataIntake
summary: Upload files
description: Send upload files to a previously-created transaction. Each upload file is associated with a target object in Visier. The files are not processed in Visier until you commit the transaction.
operationId: DirectDataIntake_UploadFile
parameters:
- name: draftId
in: path
description: The unique identifier of the project to load data into. Currently, the only supported value is `prod` to update the production version.
required: true
schema:
type: string
- name: transactionId
in: path
description: The unique identifier of the transaction to load data files into.
required: true
schema:
type: string
- name: objectName
in: path
description: 'The name of the object to upload the data to.
If uploading data to a multi-value property (MVP), specify the property in `{object}--{property}` format; for example, `Employee--Employee_Budgeted_Compensation`.'
required: true
schema:
type: string
- name: TargetTenantID
in: header
description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: The file to upload
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DirectDataUploadFileResponseDTO'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
components:
schemas:
DirectDataUploadFileResponseDTO:
type: object
properties:
transactionId:
type: string
description: The unique transaction identifier.
status:
type: string
description: The status of the request.
message:
type: string
description: The upload response message from the provisioning service.
description: 'The transaction results.
If uploading a file, a success response means the upload was successful and doesn''t always mean the file was successfully loaded into its target object.'
servicing.DirectDataSchemaDTO:
type: object
properties:
schema:
type: array
items:
$ref: '#/components/schemas/servicing.DirectDataSchemaFieldDTO'
description: The schema definition for loading a specific object
description: Public API Direct Intake schema response object
servicing.DirectDataLoadConfigDTO:
type: object
properties:
job:
allOf:
- $ref: '#/components/schemas/servicing.DirectDataJobConfigDTO'
description: The direct data intake job configuration.
description: The configuration for the direct data intake, such as the direct data intake job type.
servicing.DirectDataSchemaFieldDTO:
type: object
properties:
name:
type: string
description: The field's column name. Column names are case sensitive.
dataType:
type: string
description: The column's data type.
formats:
type: array
items:
type: string
description: The column's accepted formats, such as date formats like "yyyy-MM-dd".
isMandatory:
type: boolean
description: If true, the field must contain a value to successfully load data into the object.
emptyValuesAllowed:
type: boolean
description: If true, the value may be empty.
description: The definition of each field in an object's schema.
servicing.DirectDataUploadFileResponseDTO:
type: object
properties:
transactionId:
type: string
description: The unique transaction identifier.
status:
type: string
description: The status of the request.
message:
type: string
description: Upload response message from the provisioning service
description: "The transaction results.\n\n If uploading a file, a success response means the upload was successful and doesn't always mean the file\n was successfully loaded into its target object."
servicing.DirectDataJobConfigDTO:
type: object
properties:
supplementalMode:
enum:
- UNCHANGED
- IS_PRIMARY
- IS_SUPPLEMENTAL
type: string
description: "The configuration for the processing job as a primary job (default) or a supplemental job. If a primary job is already defined, the direct data \n intake job must be supplemental. The valid values are `IS_PRIMARY`, `IS_SUPPLEMENTAL`, and `UNCHANGED`."
format: enum
extendObjects:
type: array
items:
type: string
description: "The target analytic objects to load using extension tables.\n You can extend objects if the job type is supplemental and the target objects already contain data from a previous data version.\n This allows you to load data for objects that already contain data in Visier."
description: Whether the direct data intake job is a primary job or a supplemental job.
servicing.DirectDataListTransactionsResponseDTO:
type: object
properties:
transactions:
type: array
items:
$ref: '#/components/schemas/servicing.DirectDataTransactionDTO'
description: The list of open transactions.
description: A list of all currently open transactions.
servicing.DirectDataTransactionStartResponseDTO:
type: object
properties:
transactionId:
type: string
description: The transaction's unique identifier.
description: The response after successfully creating a transaction.
servicing.DirectDataTransactionDTO:
type: object
properties:
tenantCode:
type: string
description: The tenant for the data load.
transactionId:
type: string
description: The transaction's unique identifier.
created:
type: string
description: The transaction's creation date and time. The format is YYYY-MM-DDTHH:mm:ss.SSSZ (ISO 8601).
updated:
type: string
description: The transaction's last update date and time. The format is YYYY-MM-DDTHH:mm:ss.SSSZ (ISO 8601).
status:
type: string
description: The status of the transaction, such as open, progressing, or committed.
description: An open transaction.
servicing.DirectDataJobStatusResponseDTO:
type: object
properties:
tenantCode:
type: string
description: The tenant for the data load.
transactionId:
type: string
description: The unique identifier of the committed transaction.
jobId:
type: string
description: The unique identifier of the processing job.
status:
type: string
description: The status of the processing job.
message:
type: string
description: If the processing job fails, this field contains details specific to the failure.
description: The job status information for a committed transaction.
Status:
type: object
properties:
localizedMessage:
type: string
description: Localized error message describing the root cause of the error.
code:
type: string
description: Error classification.
message:
type: string
description: Not used.
rci:
type: string
description: Optional root cause identifier.
userError:
type: boolean
description: Indicates whether the error is a user error.
description: The response structure for errors.
securitySchemes:
CookieAuth:
type: apiKey
name: VisierASIDToken
in: cookie
ApiKeyAuth:
type: apiKey
name: apikey
in: header
BearerAuth:
type: http
scheme: bearer
OAuth2Auth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: /v1/auth/oauth2/authorize
tokenUrl: /v1/auth/oauth2/token
scopes:
read: Grants read access
write: Grants write access
password:
tokenUrl: /v1/auth/oauth2/token
scopes:
read: Grants read access
write: Grants write access
x-tagGroups:
- name: data in
tags:
- DirectDataIntake
- DataIntake
- DataAndJobHandling
- PGPKeys
- DataUpload
- TableSource