Skip to main content

Custom Task Provider API

Clients can configure a custom task provider (such as Financial Analysis Task) in the journey which will have a button that a user can click to send a message to a client hosted adapter. The call to that adapter will send task related data and your implementation.

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

Sample Use Case for External Policy Provider - Custom Task Provider​

Use Case
  AS: a Fenergo SaaS platform consumer:

      GIVEN: Our organization has functionality outside the Fenergo Platform

      AND: We want to send the task related information to an external destination

      WHEN: a user clicks a configurable button in the task

  THEN: I want Fenergo to call an external service and send that task data

Create External Policy Provider - Custom Task Provider​

You can create a new External Policy Provider by sending a POST to this URL endpoint {{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": "custom task provider name",
        "serviceUrl": "https://webhook.site/9589ac93-0713-4062-b6ea-ee83d68a69ca",
        "type": "Task",
        "encryptionKey": "{32 character Base64 Key}",
        "authenticationKey": "{32 character Base64 Key}"
    }
}

Understanding the Create Custom Task 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 Task 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 Custom Task Provider​

A request to the Task adapter is sent when a user click the specific button in the task. Once the Custom Task Provider is called from within a Journey, the Entity Id and the Draft Entity Id will be sent along with the Task Id and Journey Id. This will allow the provider to retrieve more context from system if required when asserting the status of the data sent.

note

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

POST REQUEST BODY from FENERGO -> YOUR ADAPTER
{
    "providerId": "validProductName",
    "entityId": "18d2ce82-3262-4eb2-b538-a7e7d8b91272",
    "entityDraftId": "a70dfd0f-6924-424d-9643-6d7be8313d16",
    "taskId": "18d2ce82-3262-4eb2-b538-a7e7d8b91272",
    "journeyId": "a70dfd0f-6924-424d-9643-6d7be8313d16"
}
  • taskId" The Task Id of where the reuqest is sending from.
  • journeyId" The Journey Id of where the request is sending from.
  • entityId" The entity Id of the Legal Entity which is the target of the Journey.
  • entityDraftId" The Draft Id of the Legal Entity.
RESPONSE BODY SAMPLE from YOUR ADAPTER -> FENERGO (VALID RESPONSE)
{
    "isSuccess": true,
    "message": "",
    "status": "Ok"
}
  • isSuccess" is the Custom Task Provider response with true as the result. This will ensure the data reload on the FenX UI.
RESPONSE BODY SAMPLE from YOUR ADAPTER -> FENERGO (INVALID RESPONSE)
{
    "isSuccess": false,
    "message": "What you entered in the field is not valid"
}
  • "isSuccess" is the Custom Task Provider response with false as the result. The FenX UI will present your custom validation message.
  • message" is the custom message displayed on the UI if the user has entered invalid data.