Supporting parameters

In nearly all real situations, users want to be able to customize the queries that they can run against an external data source. To make that possible, you must configure the service to present parameters to its users. In your implementation of the acquire endpoint, you can act on the values that they specify.

As you read the following information, also look at the config.json files in the example projects at https://github.com/IBM-i2/Analyze-Connect, some of which demonstrate the results of following this procedure.

To support parameters in an service, you add a fixed set of conditions for which users can supply values. In a query for people, you might allow users to search for particular names or characteristics. In a "find path" seeded query, you might allow users to specify how long the path can be.

Note: A significant difference between visual query and external searches is that in the latter, conditions are not bound to property types. A condition in a service can be anything that you can process usefully in your implementation.

To add parameters to a service, you add a client configuration to its definition that describes how each condition is presented to users. The REST SPI for the configuration endpoint describes the structure of clientConfig objects, which look like this outline:

{
  "id": "",
  "config": {
    "sections": [
      {
        "title": "",
        "conditions": [
          {
            "id": "",
            "label": "",
            "description": "",
            "mandatory": false,
            "logicalType": ""
          }
        ]
      }
    ]
  }
}

The client configuration is responsible for the appearance of the conditions that users see, and the restrictions on the values they can provide. As well as controlling the types of conditions, and specifying whether supplying a value is mandatory, you can add further validation that is appropriate to their type. For more information about this kind of validation, see the REST SPI documentation for the configuration endpoint.

When a user opens a query that supports parameters, they see a form that displays your conditions. When they provide values and run the query, your implementation of the acquire endpoint receives a payload that contains those values. You can write the implementation to act on those values in any way that makes sense for your data source.

Like many other aspects of developing a connector, supporting parameters means changing your implementations of the configuration and acquire endpoints.

  1. In your response from the configuration endpoint, write or modify the service definition so that its clientConfigType is "FORM", and add a clientConfigId.

    This identifier links to a client configuration elsewhere in the response. In some circumstances, it might be appropriate to use the same client configuration for more than one service.

  2. Add a clientConfigs array to the response, and within it a client configuration object whose id matches the identifier that you specified in Step 1.
  3. Add your conditions to the client configuration.
    To begin with, you might consider leaving out validation checks in the interests of getting a working implementation quickly.
  4. Add code to your implementation of the acquire endpoint that unpacks the condition values from the payload.
    You can then use those values to affect the query that you perform against the external source.
  5. Restart the i2 Analyze server or instruct the i2 Connect gateway to reload the configuration.
    You can now test the code and make sure that it does what you expect.
  6. Return to the response from the configuration endpoint, edit the condition descriptions, and add client-side validation to improve the user experience.
  7. Restart or reload again, and ensure that the validation has your intended effect.

The validation that you can specify in the response from the configuration endpoint is performed by the client, and applies to values in isolation. If your service (and your users) might benefit from some more complex validation, consider adding a validate endpoint.