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
- Register an Adaptor using the YOUnite API, which will generate the necessary configuration details the Adaptor will need at startup time.
- Develop an adaptor in your development environment using a YOUnite Adaptor SDK (see YOUnite Adaptor Guide for Java Developers).
- 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.
- Connect the adaptor to the native data store or service that it is connect to YOUnite (e.g. CRM, MIS, SIS, DB, etc.).
- Configure the adaptor with the details from step 1 "Register an Adaptor" above.
- Start the adaptor so it can connect to the YOUnite DataHub over the YOUnite Message Bus.
- Change an adaptor's state.
- Pause
- Play
- Play Read Only
- Manage the adaptor.
- Delete an Adaptor
- Get new Credentials for an adaptor
Step 1 ("Adding an Adaptor") and steps 5 through 8 are covered on this page. Steps 2 through 4 are implementation-specific.
1. Adding an Adaptor
Adding an adaptor merely informs the Data 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.
An adaptor name is all that is required to POST an adaptor. 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" }
Note: Steps 2 through 4 are implementation specific. After they are completed, continue on to step 5, below.
5. 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 properties file resides on the same system as the adaptor. The list below explains 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???:
Property | Description | Example Value |
---|---|---|
className | Transport implementation class (should be a constant value if using the YOUnite Java SDK) | com.younite.adaptor.sdk.transport.amq.AMQConnect |
zoneUuid | UUID of the zone this adaptor belongs to | 3c9000a9-3eb6-41fe-a11b-5a5859020c65 |
adaptorUuid | UUID of the adaptor | 3dfcc03d-e5d4-4d57-9e9b-5c5d2db32f9a |
clientId | ClientID returned from POST /adaptors used to connect to message broker | 8c9167a6-bb83-4f77-bdfc-1947a946f77b |
clientSecret | Secret returned from POST /adaptors used to connect to message broker | de02e3fa-4b23-46cb-aed6-5665a16e73d3 |
brokerUrl | Message Broker URL | nio+ssl://message-broker-uri:61617 |
oauthServerUrl | OAuth Server to validate adaptor access credentials. YOUnite runs an embedded OAuth server that your implementation may be using. By default it runs on port 8080 so, in this case the value would be http://ip-address-of-the-YOUnite-datahub:8080 | http://oauth-server-uri |
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
6. Start the Adaptor - Connect to the Hub
Once the adaptor has been added (posted) 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
7. Change an Adaptor's State
Once an adaptor is added (step 1, above) it is in the "Posted" state. The states normally set by the YOUnite Data Hub are: POSTED, CONFIGURED, and DOWN.
The adaptor moves between states as follows:
Adaptor States
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 adaptor has:
|
Pause | The adaptor 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. |
An adaptor state can be changed using the request:
PUT /zones/zone-uuid/adaptors/adaptor-uuid/ops
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 }
Changing an Adaptor's Operational State
The states normally set by the YOUnite Data Hub are: POSTED, CONFIGURED, and DOWN. The ../controls endpoint changes an adaptor's state to operational states and those normally set only by the datahub. However, there may be situations where you want to use this endpoint to set these states, such as if an adaptor is an unknown state and restarting the adaptor does not provide a remedy.
Note: Under normal circumstances this resource should never be used and it can render an adaptor and the source entity read/write requests in an unknown state.
This resource overwrites the adaptor to a state normally set by the YOUnite Data Hub. Valid states for this request are the normal adaptor operational states:
- ADAPTOR_PAUSE
- ADAPTOR_PLAY
- ADAPTOR_PLAY_RO
And the states normally set only by the datahub:
- ADAPTOR_POSTED
- ADAPTOR_CONFIGURED
- ADAPTOR_DOWN
PUT /zones/zone-uuid/adaptors/adaptor-uuid/controls
8. 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
Note: When you delete an adaptor it is a soft delete (meaning the adaptor's "active" setting will be set to false). A soft-delete for entities avoids purging important information, including that which can be used to associate past activity in the system, such as logged events, zone, and adaptor type.
However, the linking (mapping) between the (YOUnite) Data Record and the source entities in the source system attached to the deleted adaptor will be hard deletes. Linking for deleted adaptors is hard-deleted as this particular data carries no useful additional data or metadata (the link entities are just an adaptorUuid and a drUuid). Post-delete, an adaptor's linking history can still be viewed in system logs that should include all the relevant details about that link, as well as a log timestamp.
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" }