Implementing an acquire endpoint
In a connector, an acquire endpoint must perform two tasks in succession. Its roles are to retrieve data from an external source, and to return that data to the i2® Connect gateway in a form that the latter can use to create i2 Analyze records.
Refer again to the example connector projects at https://github.com/IBM-i2/Analyze-Connect. They contain implementations of the acquire endpoint for several services, which cover many of the common considerations.
When a user runs a synchronous query against an external data source through their client application, the i2 Connect gateway makes a request to the acquire endpoint of the relevant service. The request always has a payload that can contain information (often, parameter values or seed records) that the user provided to the query.
In general, your implementation of an acquire endpoint uses the contents of the payload to refine the commands that it sends to the external source. If the service that owns the endpoint specified a
FORM, then the identifiers of conditions in the form match the identifiers of conditions in the payload. If the service specified
seedConstraints, then the payload contains the property values of seed records.
For a query with no parameters and no seeds, the payload is empty. You can focus your development effort on making sure that the response from the acquire endpoint meets the requirements of the i2 Connect gateway.
- In i2 Analyze Schema Designer, open the schema file that contains the definitions of the i2 Analyze entity, link, and property types that data from the external source must align with.
- Make a note of the identifiers and logical types of the property types of each of the entity and link types in the retrieved data. Make sure that you know which property types are mandatory.
- Run the command to retrieve data from the external data source:
- If data retrieval from the external source succeeds, store the data in a structure that you can manipulate easily, and continue with the next step in this procedure.
If data retrieval from the external source fails, add the optional
errorMessagefield to the response from the endpoint.
errorMessagefield contains a string that users of the connector see when a problem occurs. When the field is present (and not empty), the operation fails and any data in the arrays of entities and links is ignored.
- If the data from the external source contains information about links between entities,
but the links in the data have no natural identifiers, you must manufacture those
identifiers.This problem is similar to the one you face if you prepare data for ingestion into the Information Store.
- Create the arrays of entity and link data objects that must appear in the response from the acquire endpoint.
- Populate the arrays according to the descriptions in the SPI documentation, taking care to ensure that you provide values for all mandatory properties.