Tip of the day

Support tickets can be submitted directly from application

Field change

Estimated reading: 4 minutes 101 views

As a form is being edited by a client you are able to connect data from the form to get or validate data on remote source, such as your CRM. With field change webhook you can easily map and post fields and values from within a live form were to get an answer from your endpoint.

Why do I need this?

This webhook can be very useful when not all data can be exposed in a form but rather need to be fetched or validated as part of business process, such as verify client ID and fetch personal details:

To add field change webhook:

  1. Follow Webhook guide to add new webhook
  2. Find below details for field change body request and expected response
  3. Map fields and define when and how the data connector will act on live form. See below Setting up field change connector

Field change data request and response

Following are definitions for Body request posted from Cellosign to your API

ElementWhat it’s for?
EventObject that includes Event type: WHEF_FORM_FIELD_CHANGED and time stamp
SessionThis object includes details on the session the webhook was fired from. It includes the following elements:
1. “id”: session token
2. “reference”: aggregator ID for business process.
3. “transaction_number”: ID for transaction that can be located in cellosign UI application
4. “recipient”: in case of a workflow this will indicate the recipient id in the process and it’s convention name
5. “labels”: This is a key value object in reference to values injected to labels. See API documentation for details
clientObject that includes basic information regards the browser that webhook was fired form
changeObject that includes the field id, type and value that was triggering the request.
fieldsArray of objects, were each includes the id,type and value of fields that we need to post to the API.

Example post request

Your API can expect this API example for getting information from your API.

{
  "event": {
    "type": "WHEF_FORM_FIELD_CHANGED",
    "timestamp": "2023-06-30T13:35:51.579895"
  },
  "session": {
    "id": "UDi8E55p1O",
    "reference": "19dae31f-377c-44a4-be51-bf3e695dea9d",
    "process_id": "19dae31f-377c-44a4-be51-bf3e695dea9d",
    "process_number": 19,
    "transaction_number": 26,
    "recipient": {
      "id": 1,
      "name": "client"
    },
    "labels": {
      "CUSTOMER_TAG": "CUSTOMER_VALUE"
    }
  },
  "client": {
    "ip": "127.0.0.1",
    "user_agent": "Best browser ever",
    "device": "mobile"
  },
  "change": {
    "id": "myfield",
    "type": "text",
    "value": "new value here"
  },
  "fields": [
    {
      "id": "AccountID",
      "type": "number",
      "value": "999123456"
    },
    {
      "id": "FullName",
      "type": "text",
      "value": "Ron Jerome"
    }
  ]
}

Expected response

A successful response from the API should include array of objects, were each object includes “id” and “value” key/value pairs as in this example. Values will be injected into their corresponding id in a session.

{
  "data": [
    {
      "id": "OrderId",
      "value": "1234-45"
    },
    {
      "id": "OrderStatus",
      "value": "Open"
    }
  ]
}

Setting up field change connector

Follow these steps to apply the webhook into the template:

  1. Login to your template
  2. Select “Integrations” on the top right and then click on “Connectors”
  3. Field change connector can be applied to “LIVE” only. Click “Add Live Connector”
  4. On source, select “Webhook”
  5. On Type: select the your webhook [by alias]
  6. Turn it’s status to “Active”
  7. Define how the connector is trigerred, there are two options:
    • On button click: Select a button from the form that will fire the webhook
    • On change: Select a field from the form that on value change will fire the webhook
  8. Add mapping: Select the fields that will be posted to your API. For each field you have the option to modify it’s convention (alias), this can become handy if your API/DB has diferrent names for these fields. On the response the alias will be preserved to map it back into the form
  9. Save the connector and the template

Leave a Comment

Share this Doc

Field change

Or copy link

CONTENTS