Skip to main content

Single Field External Validate API Walkthrough

Clients can configure a specific single field in their policy which will invoke a client hosted adapter when the user saves the content on the form or attempts to complete a task on the UI. The call to that adapter will send whatever has been typed into the text box and your implementation can match that and determine if the value is a valid result. If the Value is invalid, a Real-Time response will be displayed as an error message on screen along with whatever message your adapter returns. ALSO: The validator call when sent from within a journey will also send the Entity Id (for the target of that Journey) and the Draft Entity Id which is where the data changes are made.

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

Sample Use Case for External Policy Provider - Single Policy Field Validate​

Use Case
  AS: an FenX consumer:

      GIVEN: Our organization has functionality to validate data entered into a specific policy field

      AND: We want to validate that input as they are saving data from the User Interface

      WHEN: a user has entered the data

  THEN: I want FenX to call an external service which can assert the input is valid

Create External Policy Provider - Single Policy Field Validate​

You can create a new External Policy Provider by sending a POST to the following URL {{baseURL}}/policyproviderscommand/api/provider with the below body. In the below example, a Policy Field that validates a field to make sure a valid Product Name is used and displays an error of the data is invalid.

Create New Single Field Policy Validator - JSON POST Request
{
    "data": {
        "name": "validProductName",
        "serviceUrl": "https://webhook.site/9589ac93-0713-4062-b6ea-ee83d68a69ca",
        "type": "validate",
        "encryptionKey": "{32 character Base64 Key}",
        "authenticationKey": "{32 character Base64 Key}"
    }
}

#Understanding the Create Single 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" of the single field Adapter.
  • "serviceUrl" is the URL where the adapter is located. This URL will be called by Fenergo when interacting with your policy field adapter.
  • "type" is the Type of adapter. This is search for this example.
  • "encryptionKey" and "authenticationKey" are the Encryption and Authentication Keys used to secure and sign the messages sent to your adapter.

Request and Response Example for Single Field Suggestions​

A request to the Validate adapter (Adapter Implementation Contract) is sent when a user saves the data on the page or selects to complete the task. Once the Validator is called from within a Journey, the Entity Id and the Draft Entity Id will be sent along with the validation request. This will allow the validation to retrieve more context from system if required when asserting the status of the data sent.

Encryption

Remember the request body will be Encrypted and not sent in plaintext. These examples are the plaintext versions of encrypted exchange.

{
    "fieldName": "validProductName",
    "fieldValue": "Test Product C",
    "entityId": "18d2ce82-3262-4eb2-b538-a7e7d8b91272",
    "entityDraftId": "a70dfd0f-6924-424d-9643-6d7be8313d16"
}
  • "fieldName" is the datakey from a configured policy that gets sent with the request.
  • "fieldValue" is the value entered by the user into the policy field.
  • "entityId" The entity Id of the Legal Entity which is the target of the Journey.
  • "entityDraftId" The Draft Id of the Legal Entity.
note

If the validator is called from the new request screen because it has been configured in the "Basic Details" section of a policy, then the Entity Id and The Draft Entity Id values will be null as the call is being made from outside the context of a journey.

RESPONSE BODY SAMPLE from YOUR ADAPTER -> FENERGO (VALID RESPONSE)
{
    "isValid": true,
    "message": "",
    "status": "Ok"
}
  • "isValid" is the Validation response with true as the result. This will ensure the field passes validation on the FenX UI.
RESPONSE BODY SAMPLE from YOUR ADAPTER -> FENERGO (INVALID RESPONSE)
{
    "isValid": false,
    "message": "What you entered in the field is not valid"
}
  • "isValid" is the Validation response with false as the result. The FenX UI will use this value to highlight the text field and present your custom validation message.
  • "message" is the custom message displayed on the UI if the user has entered invalid data.

UI Result for Single Field Suggestions​

Once the adapter is configured, the UI will display the error message in the top right hand corner. The client configured error message will be displayed in the dialog box as below.