Agilemanager-api NPM

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...
});