Implementing acquire

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.

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 clientConfigType of 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.

Note: From version 1.2 of the SPI, clientConfigType is deprecated. The client configuration type should be defined in the clientConfig object instead.

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.

Note: It is not possible to follow the same procedure for every different kind of external data source. The following steps do not apply in all cases. Rather, they describe tasks that you are likely to require.

  1. 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.

  2. 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.

  3. Run the command to retrieve data from the external data source:

    1. 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.

    2. If data retrieval from the external source fails, add the optional errorMessage field to the response from the endpoint.

      The errorMessage field 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.

  4. 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 that you face if you prepare data for ingestion into the Information Store.

  5. Create the arrays of entity and link data objects that must appear in the response from the acquire endpoint.

  6. Populate the arrays according to the descriptions in the SPI documentation, taking care to ensure that you provide values for all mandatory properties.