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
- Develop an adaptor in your development environment using a YOUnite Adaptor SDK (see YOUnite Adaptor Guide for Java Developers)
- Install the adaptor on a server (e.g. on a physical server, virtual server, instance, container, etc.) that is connected the YOUnite message bus
- Connect the adaptor to the native data store or service that it is connect to YOUnite (e.g. CRM, MIS, SIS, DB, etc)
- Deploy the adaptor on a server (e.g. on a physical server, virtual server, instance, container, etc.) that is connected the YOUnite message bus
- Adding an adaptor to a zone using the YOUnite UI or YOUnite API
- Configure the adaptor
- Start the adaptor so it can connect to the Hub
- Change an adaptor's state
- Pause
- Play
- Play Read Only
- Manage the adaptor
- Delete an Adaptor
- Get new Credentials for an adaptor
The first step is covered in the adaptor guide and 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": "64ed6954-3987-4020-9553-54d9e4e7d258", "clientSecret": "76e33a67-8e8c-4209-ae38-5e4fa59fd452" }
Configuring an Adaptor
Properties from the above response body and other information need to be added to the adaptor's TODO file:
TODO: TABLE of KEY: VALUES
Example:
Adaptors States
Once an adaptor is added it is in the "Posted" state. The adaptors moves between states as follows:
State | Description |
---|---|
Posted | Adaptor is successfully POSTed. An API consumer can make this request or it can be done through the YOUnite UI. |
Configured | The adaptors had a:
|
Pause | The adaptors is running but not accepting adaptor (read/write) requests. |
Play Read-Only | The adaptor is accepting read requests only. |
Play | The adaptor is accepting read and write requests. |
Start the Adaptor - Connect to the Hub
Once the adaptor has been added and configured, it can be launced. 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 PUT /zones/zone-uuid/adaptors/adaptors-uuid request. 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 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 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 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" }