Skip to main content

Multi Field External Search and Details API

Clients can configure a multi cardinality data group in their policy which will invoke a client hosted adapter when the user types into a search box. The content from the search box will be sent in a call to that adapter and the implementation can search a repository or data store for matching results and return an ordered list of formatted data back. The result set is sent back Real-Time and the response will be displayed as a list of options on the UI. The user can then select one of the matching items and the ID of the selected item is sent to a second endpoint to retrieve the details mapped to the configured fields.

APIs Referenced
External Policy Provider Query
External Policy Provider Command
Adapter Implementation Contract

Sample Use Case for External Policy Provider - Multi-Field Search and Details​

Use Case for Multi-Field External Data Provider
  AS: a FenX consumer:

      GIVEN: Our organization has functionality to to support suggestions for a collection of policy fields in a Data Group

      AND: We want to present those suggestions to a UI user as they are filling in the User Interface

      WHEN: a user selects to add a result from the presented list

 THEN: I want FenX to call an external service which can populate the details into a Data Group Instance.

Create External Policy Provider - Multi-Field Search and Details UI​

For comparison with the API look at the screen in the Admin Section of the Fenergo UI. You can see the elements that need to be set, along with the two URLs to both the Search and Details endpoints.

Create External Policy Provider - Multi-Field Search and Details API​

The API can be used to create the provider above for multi field Search and Details by sending a POST to the following API Endpoint {{baseURL}}/policyproviderscommand/api/provider with the below body. In the below example, a multi-cardinality Data Group that allows a user to search for addresses is selected (it must already exist and the dataGroupId must be known).

Create New Multi-Field Policy Provider - JSON POST Request
{
    "data": {
        "name": "External Address Search",
        "serviceUrl": "https://webhook.site/9589ac93-0713-4062-b6ea-ee83d68a69ca",
        "type": "DataGroupSearch",
        "encryptionKey": "{32 character Base64 Key}",
        "authenticationKey": "{32 character Base64 Key}",
        "dataGroupId "xxxxxxxxxx",
         "resultFieldsConfig": [
            {
                "dataKey": "addressLine3"
            },
            {
                "dataKey": "addressLine1"
            },
            {
                "dataKey": "addressLine2"
            },
            {
                "dataKey": "country"
            }
        ],
        "searchFieldsConfigs": [
             {
                "name": "addressSearch",
                "label": "Start Typing to Find Address"
            }
        ],
        "detailsUrl": "https://webhook.site/2c37f678-bbbe-42a3-b870-16c3c7b24289"
    }
}

Understanding the Create Multi Field Provider Requests​

The above configuration request contains the details required to add a new custom adapter to your Tenant Configuration. Once Added you should receive a HTTP 202 Accepted response.

  • "name" is the name of the Adapter.
  • "serviceUrl" is the URL where your adapter is located. This URL will be called by Fenergo when interacting with your policy field adapter.
  • "type" is the Type of adapter. This can be search,validate or DataGroupSearch
  • "encryptionKey" and "authenticationKey" are the Encryption and Authentication Keys used to secure and sign the messages sent to your adapter.
  • "dataGroupId" is the ID of a configured data group. An instance of this "type" of data group will need to be included in a configured policy.
  • "resultFieldsConfig" This is the mapping for the data keys inside a data group from a configured policy.
  • "searchFieldsConfigs" is the Results Field Config. FenX will put a field and a Label in the UI of the Data Group Dialog box. This field name is what will be send to your provider and the label will be displayed on the UI.
  • "detailsUrl" is the endpoint for the Details URL. This is a separate endpoint to return the Data Mapped to Fields as will be shown in the API examples further down.

Request and Response Example for Multi Field Suggestions​

Below is is an example of the HTTP Body of a request to the Multi-Field Suggestions service, followed by an example of what a Valid response is.

POST REQUEST MULTI-FIELD SUGGESTIONS BODY from FENERGO -> YOUR ADAPTER
{

    "fields": [
        {
            "fieldName": "addressSearch",
            "fieldValue": "test"
        }
    ]
}
  • "fieldName" is the value set when creating the provider, This is not a policy field but is dynamically added to the UI and is displayed as configured in the "searchFieldsConfigs".
  • "fieldValue" is the value entered by the user into the policy field.
POST RESPONSE MULTI-FIELD SUGGESTIONS YOUR ADAPTER -> FENERGO 
{
    "Status": 0,
    "SearchSuggestions": [
        {
            "Id": "59822a61-9dd8-48c4-abb3-d932caa05f15",
            "DisplayValue": "Poland, Wroclaw, Rynek 36/37"
        },
        {
            "Id": "ed3f8007-9511-414f-b2a6-e4e293924732",
            "DisplayValue": "Spain, Alicante, Orihuela, 14, 03193"
        },
        {
            "Id": "71e56382-91f1-46b3-920d-78c912e05eed",
            "DisplayValue": "Ireland, Co Kildare, Clane, 30 Alexandra Walk"
        }
    ]
}
  • "Id" in the "Search Suggestions" "are the IDs being used by your service, In the example above GUIDs are used, but, you can use anything which makes sense to your service This is the identifier that will be sent back to retrieve the Mapped Details
  • "DisplayValue" is the neatly formatted display value. We have some comma separated values to make an address readable on a single line, but this can be anything which makes sense for your use case.

UI Result for Multi-Field Suggestions​

Once the adapter is configured, the UI will display the multi-field suggestions as below.

Request and Response Example for Multi Field Details​

Below is is an example of the HTTP Body of a request to the Multi-Field Details service, followed by an example of a response which contains the mappings to the fields inside the data group. As can be seen, the request to your adapter will only contain the suggestionId selected from the dropdown list.

POST REQUEST MULTI-FIELD DETAILS BODY from FENERGO -> YOUR ADAPTER
{
    "suggestionId": "71e56382-91f1-46b3-920d-78c912e05eed"
}
  • "suggestionId" is the identifier sent to your adapter. This example is using GUIDs but this could be the Primary Key from a database or whatever way your data is structured.
POST RESPONSE MULTI-FIELD DETAILS BODY from YOUR ADAPTER -> FENERGO 
{
    "Status": 0,
    "Values": [
        {
            "FieldName": "addressCountry",
            "FieldValue": "Ireland"
        },
        {
            "FieldName": "addressLineThree",
            "FieldValue": "Co Kildate"
        },
        {
            "FieldName": "addressLineTwo",
            "FieldValue": "Clane"
        },
        {
            "FieldName": "addressLineOne",
            "FieldValue": "30 Alexandra Walk"
        }
    ]
}

  • "FieldName" are the field names as they correlate to the field names within the data group. These must match the dataKeys in the data group configuration.
  • "FieldValue" are the values which will be populated into the the data group fields.

UI Result for Multi-Field Details​

After a user selects from the drop down list, the details will be populated into the data group as below. Simply need to click on save to save the data into the LE Record.