ea-crm-service-connector/README.md

A connector for Microsoft Dynamics CRM instances

# EA CRM Service Connector

## SYNOPSIS

This module exists to provide connectivity and interaction with instances of Microsoft Dynamics through its [Web API](https://msdn.microsoft.com/en-gb/library/mt593051.aspx)
The following functionality is provided currently:
* Establishment of ongoing connectivity through [OAuth2](https://blogs.msdn.microsoft.com/crm/2013/12/12/use-oauth-to-authenticate-with-the-crm-service/)
* Basic CRUD operations

This module can be used independently or as a dependency of microservices spawned by the [EA Services Controller](https://github.com/DEFRA/ea-service-controller) module.

## Prerequisites

Node.js v4.x.x or above

## NPM based installation
npm i --save ea-crm-service-connector

## Configuration

### Introduction
The module uses the JSON configuration file **crm.json** to establish and maintain connectivity with a Microsoft Dynamics instance.

### Environment variables
#### Substitution in configuration files
All configuration file values can be set using environment variable substitution. Environment variable substitution is specified through the use of a double quote delimited string containing the environment variable name enclosed in angled brackets; for example *"<<AWS_REGION>>"*.  Multiple environment variables substitutions within the same string are supported; for example, "<<QUEUE_PREFIX>>sample_queue<<QUEUE_SUFFIX>>".
#### Multi-environment deployments
This module supports multi-environment deployments through the following pair of environment variables:
* **TARGET_ENV_NAME** - This environment variable should be set to the name of the environment to which the module is deployed; for example, **dev**.
* **AVAILABLE_TARGET_ENV_NAMES** - This environment variable should be set to a JSON compatible array of the environment names to which the module can be deployed. The environment variable name **MUST** be enclosed in single quotes. For example: '["dev","test","prod"]'.

This pair of environment variables must be used together or not at all. If the value of **TARGET_ENV_NAME** is not contained within the value of **AVAILABLE_TARGET_ENV_NAMES**.
the module will shutdown.  **TARGET_ENV_NAME** can be used in configuration files to provide consistent naming conventions between environments.
## Configuration file location
The JSON configuration files **MUST** be placed in the same directory as each other.
* If the module is used as a dependency of microservices spawned by the EA Services Controller module, it is recommended that all configuration files should be placed in the **config** directory of the EA Services Controller module.
 *  In this scenario the environment variable **SERVICES_CONFIG_LOCATION** **MUST** be set to the path of the chosen directory.
* If the module is used independently, the module assumes that the JSON configuration files are located in the **config** directory of this module by default.
 *  In this scenario, if you place the JSON configuration files in a different directory the environment variable **SERVICES_CONFIG_LOCATION** **MUST** be set to the path of the chosen directory.

### Configuration file validation
All configuration files used by the module are validated at startup against [Joi](https://github.com/hapijs/joi) schemas available in the [EA Service Schemas repository](https://github.com/DEFRA/ea-service-schemas).  If a configuration file fails validation, the module will shutdown.

### Configuration file sample

```
  {
    "CRM": {
      "dynamics": {
        "oauth": {
          // Microsoft Dynamics instance tenant.
          "tenant": "<<DYNAMICS_TENANT>>",
          // Microsoft Dynamics instance authority host URL.
          "authorityHostUrl": "<<DYNAMICS_AUTHORITY_HOST_HOST_URL>>",
          // Microsoft Dynamics instance client ID.
          "clientId": "<<DYNAMICS_CLIENT_ID">>,
          // The username used when establising a connection to the Microsoft Dynamics instance.
          "username": "<<DYNAMICS_USERNAME>>",
          // The password used when establising a connection to the Microsoft Dynamics instance.
          "password": "<<DYNAMICS_PASSWORD>>",
          // The URL of the Microsoft Dynamics instance.
          "resource": "<<DYNAMICS_RESOURCE>>"
        },
        // How often the bearer token should be refreshed (in milliseconds) to retain connectivity with the Microsoft Dynamics instance.
        "refreshTokenEveryMillisecs": 1800000,
        // The URL used to interact with the Microsoft Dynamics instance through the Web API. 
        "endpointUrl": "<<DYNAMICS_ENDPOINT_URL>>",
        // Timeout (in milliseconds) when calling the Web API.
        "endpointTimeOut": 40000,
        // How long to wait (in milliseconds) before retrying a failed call to the Web API.
        "endpointRetryWaitMillisecs": 2000,
        // How many timess to retry failed calls to the Web API before failing.
        "endpointRetries": 1,
        "connectionConfig": {
          "headers": {
            // OData version header used by the Web API.
            "OData-Version": "4.0",
            // Content type header used by the Web API. 
            "Content-Type": "application/json",
            // OData maximum version header rused by the Web API.
            "OData-MaxVersion": "4.0",
            // Authorization header used by the Web API.
            "Authorization": "",
            // Cache contol header used by the Web API.
            "Cache-Control": "no-cache"
          }
        }
      }
```



### Coding examples for using the connector


```
// Initialize the connector
var connector = require('ea-crm-service-connector')
var crm

// Connect to the Microsoft Dynamics instance.
connector.Crm(function (err, newCrm) {... crm = newCrm}

// Post payload to the specified URI to create an entity.
// Do not retry if the call fails.
crm.post(payload, uri, false, function (err, result) {...})

// Update an existing entity by sending a patch request to the specified URI,
// Do not retry if the call fails.
crm.patch(payload, uri, false, function (err, result) {...})

// Query the Microsoft Dynamics instance.
// Retry if the call fails.
crm.query(uri, true, function (err, result) {...})

// Perform a deletion using the specified URI.
// Do not retry if the call fails.
crm.delete(uri, false, function (err, result) {...})

// Authenticate as a particular user.
crm.authenticate(username, password, function (err, result) {...})

```


## Contributing to this project

If you have an idea you'd like to contribute please log an issue.

All contributions should be submitted via a pull request.

## License

THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

<http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3>

The following attribution statement MUST be cited in your products and applications when using this information.

>Contains public sector information licensed under the Open Government license v3

### About the license

The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.