Skip to main content
System StatusContact Support
VersionOne Community

Bulk API Quick Start

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

Overview

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


•    Create/Delete large amounts of data without iterating through OIDS
•    Create/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 VersionOn Lifecyle Rest API Tutorial prior to attempting to work with this quickstart. 

 

Authentication

When using any of the VersionOne API, 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 VersionOne 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 is in the format

http://MyVersionOneInstance/api/asset

2. Headers - The two headers that must be set are

Authorization: Bearer 1.jnzHS3VHv80DE/coUak6OcXBvGQ=
Content-Type: application/json

3. 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 VersionOne 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 minimal, the following attributes
Name : Text
Scope : Relation to a scope

 

These are defined as system defaults by VersionOne business rules.  In addition to these required attributes, your VersionOne 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"
}]

Here are some interesting things about...

  • Was this article helpful?