Digital.ai Agility Bulk API

This endpoint was introduced in 18.0, Winter 2018. Please view the About Digital.aiAgility information from the help icon in the menu bar to see if you are on this release or later.

Overview

The Digital.aiAgility Bulk API provides a rich set of bulk operations against your Digital.aiAgility instance. This enables you to:

• Create and delete large amounts of data without iterating through OIDS
• Create and delete large amounts of data given complex filtering criteria

Setup

To use the Bulk API, any rest client will do. For this quickstart, you can use any rest client to test out the samples.

If you are not familiar with using VersionOne APIs and related terminology, please visit the Digital.aiAgility Rest API Tutorial prior to attempting to work with this quickstart.

Authentication

When using any of the Digital.aiAgility APIs, you will have to authenticate. Authentication comes in two flavors:

1. Basic Authentication
2. Access Token Authentication

If you are doing "one-offs" in some browser based Rest tool and you are logged into VersionOne on a different tab, you are already authenticated and can do operations against your Digital.aiAgility instance. If you are not, you will have to use Access Token Authentication to perform any bulk operations. Please examine the documentation for Access Token Authentication if you have questions.

Basic Concepts of usage

There are essential 3 parts that are necessary for using the Bulk API:

1. URL - This is the endpoint that you are going to POST to. The Bulk API endpoint URL is in the format listed below.
   Note: "previewOnly=true" can be omitted if you are confident with the payload being sent to the endpoint.
   http://MyVersionOneInstance/api/asset?previewOnly=true
2. Preview Mode - Include "previewOnly=true" in URL query parameters
   We recommend executing commands in preview mode by including the query parameter "previewOnly=true" before executing commands in commit mode ("previewOnly=true" omitted). This will allow you to explore the usage or syntax of the API safely. The response from the endpoint will include the set of assets that would have be modified if the command had been executing in commit mode.
3. Headers - The two headers that must be set are
   Authorization: Bearer 1.jnzHS3VHv80DE/coUak6OcXBvGQ=
Content-Type: application/json
4. Payload - While there are some variation of complexity in the types of payloads, it is a json object and the simplest form to create an asset follows this basic format
   {
"AssetType" : "Story",
"Name" : "Fuzzy Story",
"Scope" : "Scope:12345"
}
   This payload creates a single new Story asset inside of a Scope (project) with the OID of Scope:12345.
   As with any Digital.aiAgility APIs, the default attributes are dictated by the metadata associated with the particular asset that you are creating. For example, if you are creating a Story, a Story has to have at a minimum, the following attributes:
   • Name : Text
   • Scope : Relation to a scope

These are defined as system defaults by Digital.aiAgility business rules. In addition to these required attributes, your Digital.aiAgility administrator can decide that in order to create a Story, some other attribute can be required to have a value when creating a new Story asset. Before you decide to create an asset, take a look at the corresponding metadata.

Creating multiple objects is what make the Bulk API special so here is an expansion of the previous payload to illustrate the creation of multiple assets.

[{
"AssetType" : "Story",
"Name" : "Fuzzy Story",
"Scope" : "Scope:12345"
},
{
"AssetType" : "Defect",
"Name" : "Fuzzy Defect",
"Scope" : "Scope:12345"
}]