Managing Adaptors

Introductions to  Adaptors can be found on the Introduction to YOUnite page and the Adaptors page.

Developing adaptors can be found on the YOUnite Adaptor Guide for Java Developers page.

The YOUnite API Documentation can be found at https://younite.us/api

Adaptor Workflow

The workflow required in getting a fully functioning adaptor are as follows

1. Register an Adaptor using the YOUnite API which will generate the necessary configuration details the Adaptor will need at startup time.
2. Develop an adaptor in your development environment using a YOUnite Adaptor SDK (see YOUnite Adaptor Guide for Java Developers)
3. Deploy the adaptor on a server (e.g. on a physical server, virtual server, instance, container, etc.) that has access to the YOUnite message bus
4. Connect the adaptor to the native data store or service that it is connect to YOUnite  (e.g. CRM, MIS, SIS, DB, etc)
5. Configure the adaptor with the details from the "Register" step above 
6. Start the adaptor so it can connect to the YOUnite DataHub over the YOUnite Message Bus
7. Change an adaptor's state
   1. Pause
   2. Play
   3. Play Read Only
8. Manage the adaptor
   1. Delete an Adaptor
   2. Get new Credentials for an adaptor

The first step is covered in the "Adding an Adaptor" section below. Steps two through four are implementation specific. The remainder of this page covers steps five through eight. 

Adding an Adaptor

Adding an adaptor merely informs the hub that there is an intention to add an adaptor to a zone. Only users with POST /zones/zone-uuid/adaptors permissions can add in adaptor to a zone. By default only the zone data steward (ZDS) has this permission.

All that is required to POST an adaptor is an adaptor name. If the request succeeds, an adaptor UUID and security credentials are returned. 

POST /zones/3c9000a9-3eb6-41fe-a11b-5a5859020c65/adaptors

{
	"name": "My First Adaptor"
}

The response would look similar to:

{
    "uuid": "3dfcc03d-e5d4-4d57-9e9b-5c5d2db32f9a",
    "zoneUuid": "3c9000a9-3eb6-41fe-a11b-5a5859020c65",
    "clientId": "8c9167a6-bb83-4f77-bdfc-1947a946f77b",
    "clientSecret": "de02e3fa-4b23-46cb-aed6-5665a16e73d3"
}

Configuring an Adaptor

On startup an adaptor consults either a properties file (e.g. adaptor.yml) or configuration object (TODO Kevin) for its configuration information. The file resides on the same system as the adaptor and the following is a list of the minimum properties needed by an adaptor. Consult the adaptors documentation for a definitive list and property names since they can change from adaptor to adaptor:

Example:

# Configuration
# Transport implementation class
className: com.younite.adaptor.sdk.transport.amq.AMQConnect

# UUID of the zone this adaptor belongs to
zoneUuid: 6ab9380f-d7f2-477c-b93c-3a762e70095e

# Adaptor UUID
adaptorUuid: 3dfcc03d-e5d4-4d57-9e9b-5c5d2db32f9a

# ClientID and Secret to be used by JMS to verify adaptor has valid access to message bus (and API)
clientId: 8c9167a6-bb83-4f77-bdfc-1947a946f77b
clientSecret: de02e3fa-4b23-46cb-aed6-5665a16e73d3

# Message Broker URL
brokerUrl: nio+ssl://192.2.200.25:61617

# OAUTH Server to validate adaptor access credentials
oauthServerUrl: http://192.2.200.15:8080

Adaptors States

Once an adaptor is added it is in the "Posted" state. The adaptors moves between states as follows:

Start the Adaptor - Connect to the Hub

Once the adaptor has been added and configured, it can be launched. It should successfully connect to the hub and move briefly into the "Configured" state and then into the "Play" state unless otherwise configured.

TODO KEVIN: Debugging

Change an Adaptor's State

An adaptor state can be changed using the request:

PUT /zones/zone-uuid/adaptors/adaptors-uuid

 Before making a request, the adaptor's changeVersion needs to be retrieved by peforming a GET on the adaptor:

GET /zones/3c9000a9-3eb6-41fe-a11b-5a5859020c65/adaptors/3dfcc03d-e5d4-4d57-9e9b-5c5d2db32f9a

A response that includes the adaptor's changeVersion is returned:

{
    "uuid": "3dfcc03d-e5d4-4d57-9e9b-5c5d2db32f9a",
    "name": "Test Adaptor1",
    "zoneUuid": "661f5d76-6bc7-4fc0-97fd-f331ab683379",
    "state": "ADAPTOR_POSTED",
    "dateCreated": 1503634367407,
    "lastUpdated": 1503635641288,
    "changeVersion": 4117664412
}

Pause 

The following request and request body will change an adaptor's state to "pause": 

PUT /zones/661f5d76-6bc7-4fc0-97fd-f331ab683379/adaptors/3dfcc03d-e5d4-4d57-9e9b-5c5d2db32f9a

{
	"state": "ADAPTOR_PAUSE",
	"changeVersion": 4117664412
}

Play 

The following request and request body will change an adaptor's state to "play": 

PUT /zones/661f5d76-6bc7-4fc0-97fd-f331ab683379/adaptors/3dfcc03d-e5d4-4d57-9e9b-5c5d2db32f9a

{
	"state": "ADAPTOR_PLAY",
	"changeVersion": 4117664412
}

Play Read Only

The following request and request body will change an adaptor's state to "play read only": 

PUT /zones/661f5d76-6bc7-4fc0-97fd-f331ab683379/adaptors/3dfcc03d-e5d4-4d57-9e9b-5c5d2db32f9a

{
	"state": "ADAPTOR_PLAY_RO",
	"changeVersion": 4117664412
}

Manage an Adaptor

See the YOUnite API documentation (https://younite.us/api) for more requests that can be made to the adaptors endpoint. A few common requests include:

Deleting an Adaptor

DELETE /zones/661f5d76-6bc7-4fc0-97fd-f331ab683379/adaptors/3dfcc03d-e5d4-4d57-9e9b-5c5d2db32f9a

Get Credentials for an Adaptor

By default only the zone data steward can retrieve the credentials for an adaptor:

GET /zones/661f5d76-6bc7-4fc0-97fd-f331ab683379/adaptors/3dfcc03d-e5d4-4d57-9e9b-5c5d2db32f9a/registration

The response would look similar to:

{
    "uuid": "3dfcc03d-e5d4-4d57-9e9b-5c5d2db32f9a",
    "zoneUuid": "661f5d76-6bc7-4fc0-97fd-f331ab683379",
    "clientId": "64ed6954-3987-4020-9553-54d9e4e7d258",
    "clientSecret": "76e33a67-8e8c-4209-ae38-5e4fa59fd452"
}