| Table of Contents |
|---|
...
YOUnite Adaptors are essentially extensions to the YOUnite Data Hub, allowing access to managed data. Third parties implement these adaptors using the YOUnite Adaptor SDK. Adaptors are a fundamental component to federated data domains.
Additionally, an Adaptor is software located within a system that shares data through the YOUnite Data Hub and acts as the connection point between that system and the Data Hub. An adaptor focuses on ETL (Extract, Transform, and Load) and CRUD functions, ensuring the outbound data from that system meets the format requirements of the Data Hub and transforming the inbound data from the hub into what any other system requires. It may have additional business logic such as filtering for specific data from the Data Hub.
...
For more information on YOUnite adaptors see:
...
Once an adaptor is connected to the YOUnite Data Hub through the YOUnite Message Bus, it is able to send and receive data and ops messages. The SDK has minimal configuration steps, allowing developers to focus on their adaptor's business logic instead of the inner workings of sending and receiving messages, parsing those messages, etc. To facilitate getting your adaptor up and running, the YOUnite Adaptor SDK makes use of annotations. Developers use these annotations to define the adaptor's capabilities: what their adaptor can produce and/or consume. Capabilities loosely translate into a Pub/Sub configuration on the YOUnite Data Hub.
...
As mentioned previously, when an adaptor is started (by calling the AdaptorSDK.init() method), it builds the list of capabilities that it must send to the YOUnite Data Hub. The Adaptor Capabilities List consists of the capabilities an adaptor declares to the YOUnite Data Hub upon initialization that 1) link records in the underlying application/service to YOUnite data records, 2) POST entries in the underlying application/service that link to YOUnite data records, and 3) manipulate data in the underlying service.
The capabilities list lets the Data Hub know:
...
We are defining which properties of a specified domain/version the adaptor is able to work with.
===DAB: Between here and the 2nd red text, is the YAML info that replaces annotations - In progress as of 5/25/18 ===
Adaptor YAML File
As a developer implementing the YOUnite SDK to create an adaptor, there are two components to write:
- a YAML file to initialize your adaptor (includes: a data notification handler to notify your adaptor when data has been sent)
- something goes here...not sure what the 2nd component is
Write Your Adatpor YAML File for Initializing Your Adaptor
You will need to initialization from a YAML file, which is one or more adaptor_x.yml files that you create (where x represents the adaptor number).
The adaptor_x.yml file you create will provide:
- The UUID of the registered adaptor (register via the YOUnite UI or API call to get back a UUID that identifies that adaptor at the YOUnite Data Hub
- You will also have a a zone user and client ID and secret object from registering the adaptor (lines 3 and 4 of the YAML file above). That's how this particular UUID will be authorized as matching and validating the adaptor. All this is done by the SDK behind the scenes; it just needs to be in the YAML file so we can read it so it's configurable.
- The YAML file format is:
- UUID
- Client ID
- Client Secret
- Domains
- Specific domain (person on line 5, above)
- Version
- "in" actions/properties/ids
- "out" actions/properties/ids
- Version
- Specific domain (person on line 5, above)
You will also write a data notification handler that will send a notification to your adaptor YAML file with the corresponding UUID from a YOUnite notification. For example, the following data handler with uuidA, equates to the UUID for adaptro_0.yml file above:
DAB: Kevin, is this ^ ^ a realistic example?
The data notification handler is a kind of anonymous action handler that lets your adaptor know that the router has a message for it. You, the developer, will add these notifications and listen for these messages.
So that when data changes it comes back and there is a mapping from the YOUnite UUIDs that are coming in to an internal ID or UUID on your side (DAB: Kevin–the adaptor_0.yml file's UUID is the mapping, right?).
At this point you've written a YAML file for each of your adaptors and data notification handlers that correspond to each.
Next you will initialize your adaptor:
Note: The timer on line 219 delays the actions for debugging purposes.
The init call takes all the resources for each and every one of your adaptors and it will try to authenticate against YOUnite. You must have a YOUnite server up and running and your adaptors must be registered.
A successful init call for all adaptors will be followed by some code that simulates sending code to YOUnite. For example:
Note: If you implement YOUnite with Netflix's Conductor for orchestration, you would likely have a Conductor adaptor that makes a call to the example master adaptor (see below) which then sends some data to YOUnite based on whatever data came in. In this scenario you would have an event system in your master adaptor YAML file, where the master adaptor is called and sends the data to YOUnite.
In the example above, the SDK is internally mapping the domain version UUIDs that are created in YOUnite. When the example Person object (in image above) is registered (the Person JSON schema, for example):
Step 2 ... (DAB: as mentioned above in intro to this section there are two things to do...maybe more?)
Note: You can also create your own YAML-formatted file where, if you have more than one adaptor each with its own YAML file, you can read all the adaptor YAML definitions in as an array of objects in one master YAML file. The example below shows multiple adaptor YAML files being read into a resources array that can be passed into a config object and called at the same time. The config object then gets passed to the AdaptorSDK.init function.
===DAB: From here, below, is the annotation info that should be replaced with YAML file information (above)===
The YOUnite Adaptor SDK provides a set of annotations for annotating methods within an annotated Adaptor class. The annotation properties indicate the domain's name, version, and properties names within the domain that the annotated method expects as input or returns as output.
...