gits-assignment-service

GITS Assignment Management Service

This is a NodeJS client library for GITS Assignment Management Service.

Structure

An assignment usually look like this :

{
  "_id": string_uuid_v4,
  "title": string,
  "description": string,
  "creation_date": integer_timestamp_in_seconds, // example: 1507000739
  "due_date": integer_timestamp_in_seconds,
  "update_date": integer_timestamp_in_seconds,
  "assignee": {
    "id": some_value, // could be string or interer, up to you
    ... // your custom fields, example: name, department_id, type, email, etc
  },
  "assignor": {
    "id": some_value, // could be string or interer, up to you
    ... // your custom fields, example: name, department_id, type, email, etc
  },
  "created_by": {
    "id": some_value, // could be string or interer, up to you
    ... // your custom fields, example: name, department_id, type, email, etc
  },
  "updated_by": {
    "id": some_value, // could be string or interer, up to you
    ... // your custom fields, example: name, department_id, type, email, etc
  },
  "state": {
    "id" : string, // the state id, for state references, keep scrolling
  },
  "extras": {
    ... // your custom fields, example: name, department_id, type, email, etc
  },
  "logs": [
    {
      "date": 12312,
      "type": "edit",
      "context": {
        ... // your custom fields, example: name, department_id, type, email, etc
      }
    },
    
  ]
}

A "State" looks like this

{
  "_id": "",
  "name": "",
  "nexts": [ "next_state_id_1", "next_state_id_2" ]
}

State Workflow

A state has a nexts field. This field contains array of state ids. Let's say an assignment is in a state called pending. The pending state has nexts which is [ 'active', 'invalid', 'rejected' ]. That means pending state can only move forward to one of those three states.

Installation

npm install --save gits-assigntment-service

Register

• Before you can use this service, you need to register first. Run this curl command

curl -X POST \
  http://159.203.169.253:3040/application/create \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'postman-token: a7bc2296-9215-6c0f-5010-6d7667bd65b3' \
  -d '{
	"name" : "<app-name>",
	"url": "<app-url>",
	"country": "<a-valid-country-code>",
	"email" : "<an-email-address-for-login>",
	"password": "<md5-string>"
}'

• Save your app Id (apiKey) and app secret.
• If you lost them, make a request at /application/login

curl -X POST \
  http://159.203.169.253:3040/application/login \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'postman-token: 37b17eb5-cb83-6178-d230-fdcc323775e7' \
  -d '{
	"email": "<your-email>",
	"password": "<md5-string>"
}'

Usage

const assignmentService = require('gits-assignment-service');

// mandatory
assignmentService.key("your-app-key");
assignmentService.secret("your-app-secret");

// a user is just an object with at least an id field (String)
assignmentService.user({ id: 'qwerty' }); 

// optional
// verbosity
assignmentService.verbose({error: 1, result: 1, info: 1});

Assignment API

Get Assignments

assignmentService.assignment.get( query, sort, limit, callback );

This api will return an array of assignments

• query is an object. It's structure follows mongodb query structure. ex: {_id: 'qwerty'} will find any assignment with _id equals qwerty
• sort is an object. It's structure follows mongodb $sort structure of mongodb aggregation. Detail here.
• limit is a positive integer
• callback is a standard es6 callback. (err, result) => {}

Get Assignments (Pagination Mode)

assignmentService.assignment.get( query, sort, limit, page, callback );

• page is an integer

This api will return an object like this :

{
    "list": [ /** list of assignments */ ],
    "page": {
        "total_page": 3,
        "total_data": 7,
        "current_page": 2
    }
}

Create Assignment

assignmentService.assignment.create( {
	"title": "fancy title",
	"description": "order from Vitsa",
	"creation_date": 1507631751,
	"updated_date": 0,
	"due_date": 1507770000,
	"assignee": { "id": "[e-mail]", "name": "Rahadian Ahmad" },
	"assignor": { "id": "[e-mail]", "name": "Ragil Kamal" },
	"extras": {},
	"stateId": "a-workflow-id"
}, callback )

This api will return the newly created assignment (String).

Edit Assignment

assignmentService.assignment.edit( query, update, callback );

This api will return an integer indicating how many documents was edited.

• update is an object. It's structure follows mongodb update command. Details here

Delete Assignment

assignmentService.assignment.delete( query, callback );

This api will return an integer indicating how many assignments was deleted

Change State

assignmentService.assignment.changeState(assignmentId, newWorkflowId, callback);

This api will return the updated id.

Workflow API

Workflow is a collection of states. A state has nexts field. nexts field could contain 0 state or a fuckton of states.

Create a State

assignmentService.workflow.create({
	"before": [ /** before ids  */ ], // array of string
	"state": {
		"name": "some-name",
		"type": "some-type",
		"next": [ /** next ids */ ] // array of string
	}
}, callback )

This api will return the newly created id

Delete a State

assignmentService.workflow.delete(stateId, callback);

This api will return the just deleted id.

Get state's next states

assignmentService.workflow.getNexts(stateId, callback);

This api will return an array of states

Get all states

assignmentService.workflow.getAll(callback);

This api will return all your states. (without their nexts field)

Add nexts to a state

assignmentService.workflow.addNexts(stateId, [ 'id-1', 'id-2', ... , 'id-n' ], callback);

This api will return the newly updated id

Remove nexts to a state

assignmentService.workflow.removeNext(stateId, [ 'id-1', 'id-2', ... , 'id-n' ], callback);

This api will return the newly updated id

Contributor / Contact

• Rahadian Ahmad ([e-mail])

How to Contribute

• Make a pull request / merge request