agilemanager-api

HPE's Agile Manager client API module for NodeJS

Example Use Case: Dashboard

Easily integrate with Agile Manager to create your very own dashboard UI:

Install

npm install agilemanager-api

Setup

Prepare an options object with clientId and clientSecret keys from Agile Manager's configuration area:

var options = {
	clientId: 'api_client_0000000_0',
	clientSecret: 'lknNSDASY6458ub'
};

Require the agilemanager-api npm module after it was installed and instantiate the object with the prepared options:

var AGM = require('agilemanager-api');
var agm = new AGM(options);

login Example

Perform an AGM login method to authenticate the API and continue working with the rest of the methods available

agm.login(function (err, body) {

  /** body is an object with the token information
   *
   * { 
   *   access_token: '197247213_2639ed2e-6c73-4abg-7991-9872dbccf1',
   *   token_type: 'bearer',
   *   expires_in: 3599,
   *   scope: 'read trust write'
   * }
   */ 
  
  // Do something with token...
});

query Example

Perform an AGM agm.query(fn) method on any type of resource.

The agm.query(fn) method expects an object with the following members:

• workspaceId - the workspace id in AGM
• resource - the resource type, can be any one of the listed resources
• query - the actual query to perform, accepting statements with ; char as a logical AND and || as logical OR
• fields - a list of specific fields to be filtered in the returned response
• orderBy - a field to order the results, by default results are of ascending order or with a prefix - symbol for decesending results (for example: fields: -name)
• limit and offset - both of these options allow to specify numbers for the purpose of paginated results

For example, to query for a list of backlog items, with id bigger than 2000, and getting back only the name field in the JSON response:

// Prepare the query options object
var queryOptions = {
	workspaceId: '1000',
	resource: 'backlog_items',
	query: 'id>2000',
	fields: 'id,name',
	orderBy: 'name',
	limit: 10,
	offset: 0
};

// Call the query method using the 
agm.query(queryOptions, function(err, body) {
  /**
   * body contains a JSON object response with data member and TotalResults member:
   * {
   *  data: 
   *   [{
   *     type: 'backlog_item',
   *     subtype: 'defect',
   *     id: 2012,
   *     name: 'URL uploaded images are not cropped
   correctly'
   *   }],
   *  TotalResults: 1
   * }
   *
   *
   *
   */

  // Do something with body JSON object resopnse
});

resources Example

Using the agm.resources(fn) method it's possible to perform CRUD operations directly on any type of supported resources.

Example of creating a user story:

/**
 * Perform a query on a workspace and resource
 * Create a user story
 *
 * @param {object} resourceOptions - expect an object with the following:
 *   - workspaceId - the workspace id
 *   - resource - the type of resource to perform the action on (@see list of [resources](https://github.com/lirantal/agilemanager-api#resources)
 *   - method - one of: GET, POST, PUT, DELETE
 *   - data - an array of objects with the backlog item supported fields, allowing to create more than one backlog item with fie
 */

var resourceOptions = {
	workspaceId: '1000',
	resource: 'backlog_items',
	method: 'POST',
	data: [{
		name: 'New user story',
		subtype: 'user_story'
	}]
};

agm.resource(resourceOptions, function(err, body) {

	// Returned JSON response object in body looks as follows:
	//
	// { data: 
	//    [ { type: 'backlog_item',
	//        subtype: 'user_story',
	//        story_priority: null,
	//        num_of_tasks: null,
	//        cover_status: 'Not Covered',
	//        release_id: null,
	//        id: 1945,
	//        kanban_status_id: null,
	//        author: 'api_client_49871541_16',
	//        rank: 3610000,
	//        remaining: null,
	//        estimated: null,
	//        description: null,
	//        name: 'New user story',
	//        dev_comments: null,
	//        kan_status_duration: 0,
	//        blocked: null,
	//        application_id: null,
	//        kanban_parent_status_id: null,
	//        status: 'New',
	//        story_points: null,
	//        sprint_id: null,
	//        creation_date: '2015-11-09',
	//        kan_parent_duration: 0,
	//        last_modified: '2015-11-09T18:44:20Z',
	//        theme_id: null,
	//        team_id: null,
	//        invested: null,
	//        assigned_to: null,
	//        actual: null,
	//        archive_status: 0,
	//        feature_id: null } ],
	//   TotalResults: 1 }

        // Do more things with the body response object...
});

Example of deleting a user story

Example of creating a user story:

/**
 * Perform a query on a workspace and resource
 * Create a user story
 *
 * @param {object} resourceOptions - expect an object with the following:
 *   - workspaceId - the workspace id
 *   - resource - the type of resource to perform the action on (@see list of [resources](https://github.com/lirantal/agilemanager-api#resources)
 *   - method - one of: GET, POST, PUT, DELETE
 *   - data - an array of objects with the backlog item supported fields, allowing to create more than one backlog item with fie
 */

var resourceOptions = {
	workspaceId: '1000',
	resource: 'backlog_items',
	method: 'DELETE',
	entityId: '1945'
};

agm.resource(resourceOptions, function(err, body) {
        // Do more things with the body response object...
});

Agile Manager API Usage

RESTful API

Agile Manager's API is RESTful and supports

• GET fetch a new item
• POST creates a new item
• PUT updates an item
• DELETE removes an item

As can be illustrated in the following screenshot

(image credit to HPE's Agile Manager API Intractive Help (beta)

Resources

The API supports the following resources, which can be used as part of the query method:

• applications
• backlog_items
• backlog_item (attachments)
• features
• feature (attachments)
• release_teams
• releases
• release (attachments)
• sprints
• tasks
• team_members
• teams
• themes
• theme (attachments)
• workspaces

Author

Liran Tal [email protected]