# VDM Integration Documentation / Overview

A VDM adapter plugin is basically an API wrapper that connects to  and retrieve data from external tool server. You can look at JIRA or Bamboo adapter module as reference to build your own.

## Table of Contents
* [Plugin structure](#plugin-structure)
* [Database Structure](#database-structure)
* [Integration Handout](#integration-handout)

## Plugin structure
|Litsen To| Required Inputs  | Description  |
|:---:|:---|:---|
| *Auth*  |  username | The username of the user account|
|		 |	 password  | The password of the user account|
|		 |	 host 		| The server url of the tool connect to|
|		 |  pname | The name of the adapter |
|		  | | |
|  | **Optional Inputs**  |  **Description** | 
|	|		lastUpdate		|	The last update parameter is used for APIs that supports partial qurey. For example, when we pass last update parameter to JIRA REST API, JIRA server will only  give the data after that date
|	|		timeInterval		|	The fetch time interval to external server
|		  | | |
|		  | **Required Inputs** | **Description**|
| *UpdateData*  |  username | The username of the user account|
|		 |	 password  | The password of the user account|
|		 |	 host 		| The server url of the tool connect to|
|		 |  pname | The name of the adapter |
|		  | | |
|  | **Optional Inputs**  |  **Description** | 
|	|		lastUpdate		|	The last update parameter is used for APIs that supports partial qurey. For example, when we pass last update parameter to JIRA REST API, JIRA server will only  give the data after that date
|	|		timeInterval		|	The fetch time interval to external server
|		  | | |
|  | **Optional Inputs**  |  **Description** | 
| *Cancel*  |  pname | The name of the adapter|


## Database structure
For different type of adapter, the information will be stored into different database in CouchDB. Data processing service will process data from the following information and calculate graph.


JIRA adapter saved information to two different databse, sprint and issue.   
Sprint DB:

```json
{
  "_id": "DEV SPRINT 1",
  "_rev": "225-asdasd",
  "start_date": "01/Jun/17 11:50PM",
  "end_date": "14/Jun/17 11:50PM"
}
```

Issue DB:

```json
{
  "_id": "225-asdasd",
  "_rev": "225-asdasd",
  "status": "In Progress",
  "assignee": "hyh19910105",
  "resolve_date": "2017-07-05T16:45:32.000-400",
  "due": NULL,
  "sprint": "DEV SPRINT 1",
  "creation_date": "2017-07-05T16:45:32.000-400",
  "logged": 22,
  "estimate": 13,
  "priority": "High",
  "summary": "A summary of the sprint"
}
```

Bitbucket adapter saved information to commits database.   
Commits DB:

```json
{
  "_id": "225-asdasd",
  "_rev": "225-asdasd",
  "author": "hyh19910105",
  "date": "2017-07-05T16:45:32.000-400",
  "diff": "+++ node.js"
}
```

## Integration Handout
* All adapter must be implement be implement under **/Vagrant/Adapters/**
* The connection to CouchDB is on localhost port 5984
* All adapter should send heart beat to VDM monitor service every 30 seconds, the is also served as a registration process to register adapter to web app.
	* A heart beat should be a post request send to local host 5689
	* The post body of heart beat should be following format:
	
```json
{
  "status": "alive",
  "port": "5656" (The port the adapter is running),
  "connector": "JIRA"  (The adapter name)
}
```
	
* After the adapter is implemented, the new adapter should be added to **/Vagrant/Monitor/setup/connectors.json**, providing adapter name, port which is running on, and type (issue trackers, build servers or code repository)
* Use the service template in /Adapters/Vagrant/setup folder and update $DAEMON, $ARGS and $PID
* Modify vagrant file in the main folder
  - Go to connectors section ##connectors
  - Add following lines:

         *sudo cp setup/YourConnector /etc/init.d/*
     
         *sudo chmod +x /etc/init.d/YourAdapter*
* Use uWSGI framework on top of your adapter to be able to run multiple adapter at the same time. 
* Your uWSGI framework configuration file should be created under **/vagrant/Adapters/setup/**. The configuration file should be following format:   

``` 
[uwsgi]
http-socket = :5656
chdir = /vagrant/Adapters/
plugin    = python
wsgi-file = /vagrant/Adapters/jiraserver.py
processes = 4
threads = 4
callable = app

```