Agility Bulk API Quick Start

Overview

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

• Create/Delete large amounts of data without iterating through OIDS
• Create/Delete large amounts of data with 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.

Authentication

When using any of the Agility APIs, you will have to authenticate using the Access Token Authentication.

If you are doing "one-offs" in a browser-based REST tool and you are logged into Agility on a different tab, you are already authenticated and can do operations against your Agility 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

Below are the essential parts 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://MyAgilityInstance/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/syntax of the API safely. The response from the endpoint will include the set of assets that would have been 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 is 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 Agility API, 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 minimum, the following attributes

• Name: Text
• Scope: Relation to a scope

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