Skip to content

RFC: Dynamic Pulse Form API Design

Status: In Review (until 07/11/2025)

Owners: Mingzhe Li

Reviewers: Nadim Rafehi

Decision date: (fill when accepted)

0. Background

This RFC proposes an API change design for the control room backend and form backend to support dynamic form features. Before we start, we need to quickly review the current pulse form.

The Skyledge platform uses pulse forms to capture data, using them to onboard new customers, new assets, and calibration data. In the future, the platform will use pulse forms to manage fleet TPMS data, and for the driver app, the forms will also be used for pre-trip checklists and other business-related forms.

Let’s take the asset onboarding form as an example. The dynamic form API design here focuses on specific fields in the asset and calibration onboarding process, even though the general idea and the proposed solution will be expanded to other forms.

Site workers use their mobile phones to access the pulse form web app and input form data. What really happens behind the scenes? Let’s review the existing workflow. Before the API change, the current pulse form workflow is as follows:

  • Form templates are created using the API Server and stored in the database. The form template contains the form definition and form actions. Form actions have an action called “send webhook” that calls a Lambda function to create related events and tasks in the Skyledge Platform.
  • The pulse form web app calls the form backend to retrieve the form template and renders a form based on the template, then captures the form data from the user.
  • When a user inputs form data, the form backend creates a draft form response, saves it to the database by calling the API server, and keeps updating the draft form response until the user submits the form.
  • When the user submits the form, the form backend calls the API server to update the form response from draft to submitted. The API server listens to the form submission event and calls the form action “send webhook” to create related events and tasks in the Skyledge Platform.

The approach described above is the existing workflow. There are some pain points we want to solve; let’s discuss them one by one.

1. Problem & Goals

After reading the introduction, you should have a basic understanding of the current workflow. To help us understand the pain points and goals, consider the following questions:

  • How many asset onboarding forms do we have now?
  • How many countries are we supporting now?
  • How many customers do we have now?
  • How many assets do we have now?

What pain are we solving?

Problem 1: Customer selections are not easy to update

Currently, the asset onboarding form template is created for each customer. This works if we only have O-Group, Lawsons and one or two more customers, but the new business model we will use in Kenya will allow partners to find and onboard new customers. However, we are using a static customer list with hardcoded values, which is not flexible. This leads to two major issues:

  1. We need to manually update the customer list when a new customer is added or removed. Currently, we manually update the template, and with multiple customers doing new asset onboarding, this will become a nightmare.
  2. We need to display different customer lists for different countries. A single asset onboarding form makes it harder to split the form by country.

Problem 2: Input vehicle registration number is easy to make mistakes

Assets on the Skyledge platform have increased from 200 to 700 in the past two years, and this will increase faster and faster. We are using an input field for vehicle registration numbers when onboarding new assets and calibration data, which is prone to mistakes when users manually input values. We are doing manual validation when checking the onboarding task before it’s approved by the team, but this is not efficient and not scalable.

Problem 3: Validating forms for different business domains

Skyledge is a platform for different business domains. It can be used not only for fleet management, but also for other business domains, such as energy, agriculture, etc. Each business domain has its own requirements for forms, such as fields, validation rules, and data structures.

Handling different domains in the current form backend design is not easy. We need a way to handle different domains without increasing the complexity of the form backend design.

Success criteria (business + tech)

  • The customer list can be updated easily and instantly. When a new customer is added or removed, site workers can always select from a current, real-time customer list while onboarding assets on-site.
  • Site workers should have an improved experience entering vehicle registration numbers. The form will offer auto-complete suggestions as they type, validate the input, and clearly show an error if the number is invalid.
  • The form should flexibly support different business domains (such as fleet management, energy, or agriculture). It must adapt to each domain’s unique fields, validation rules, and data structures.

These goals will result in:

  • Saving site workers time and reducing errors when entering vehicle registration numbers.
  • Streamlining form maintenance for the team by eliminating time-consuming and error-prone manual edits.
  • Making customer list updates easier and less time-intensive for the team.

2. Context

Current state

Currently, we are using a static form template with hardcoded fields and values, which is not flexible. The only way to change the form is to update the form template, which is not efficient and not scalable.

The input field for some fields is easy to make mistakes when users manually input the value. It is not easy to validate the value, and it is not easy to display the error message to the user.

The form is not able to handle different business domains, such as fleet management, energy, agriculture, etc. The form is not able to handle different fields, the validation rules, the data structure, etc. for different business domains.

The customer list is not easy to update when a new customer is added or a customer is removed. It is not easy to display different customer lists for different countries.

Constraints & assumptions

We have some constraints and assumptions we need to consider before we start the design, let’s review them one by one.

Constraints:

For the asset onboarding and calibration:

  • We need to support different fields, the validation rules, the data structure, etc. for different business domains.
  • We need to support different customer lists for different countries.
  • We need to support different vehicle registration number for different countries.

For the development experience and cost:

  • We need to keep the existing form backend and API server architecture
  • The RFC should focus on the API design changes, which means the lambda function and frontend development should be out of scope.

Assumptions:

  • The pulse form web app is not in production yet; we are still in the development phase.
  • The schema changes for the form definition and form template should be backward compatible.

3. Proposed Decision

The RFC will skip the options section, and directly propose the chosen option and the rationale.

Decision: Dynamic form template with hidden fields

We will use a dynamic form template to handle the dynamic fields and values. It will be a JSON file that will be stored in the database, and it will be used to render the form on the frontend.

Scope boundaries (in/out)

In scope:

  • Dynamic field loading based on target users of the form
  • Dynamic field types: select (dropdown lists) or autocomplete input fields
  • Support for hidden fields in form definition schema
  • Support for dynamic fields with resource references
  • Support for targeting different resources for different fields
  • API Server changes for form template management

Out of scope:

  • Dynamic field loading lambda function design
  • Form response validation lambda function before submission
  • Detailed form backend service changes
  • Frontend implementation details (covered in separate documentation)

It’s time to discuss the proposed solution details. Let’s start with the API design changes. To support the new dynamic form features, the following changes are required across the API components:

API Server (Control Room Backend)

Current state:

The API Server is a Spring Boot server. It is responsible for creating and updating form templates, and creating and updating form responses.

Please refer to the existing form template in form-template-existing.json. This is the example asset onboarding form template, which is the instance of the form template class.

Form Template:

Form Template stores form configurations, including field names, types, and other metadata. The current form class has the following attributes:

Form.java
public class Form implements Serializable, Entity<Form> {
@Id private UUID id;
private String formIdentifier;
private FormName name;
private FormDescription description;
private int version = 1;
private FormDefinition formDefinition;
private FormActions actions = new FormActions();
private UUID ownerId;
private UUID organizationId;
private Instant createdAt;
private Instant lastModifiedAt;
private List<FormVersion> formVersions = new ArrayList<>();
private transient String encryptedKey;

Form Definition:

Form Definition stores form configurations, including field names, types, and other metadata. It follows a JSON schema, which enforces constraints and validation on form definition details.

form-definition.schema.json

  • key*
    • unique identifier for the field
    • string
  • type*
    • type of the field
    • enum: input, select, radio, number, checkbox, multicheckbox, address, file
  • title*
    • title of the field
    • string
  • description
    • string
    • description of the field
  • placeholder
    • string
  • required
    • boolean
  • options (if type is select)
    • array of objects
      • value
        • string
      • label
        • string
  • min & max (if type is number)
    • number
    • number

Proposed changes:

  1. Changes on the form template, to update the form.java class

    1.1. New attribute for the form template: resources:

  • resources

    • The resources attribute is a list of resources the form template points to.

    • Each resource has the following attributes:

      • key: the key of the resource
      • url: the URL of the resource
      • headers: the headers of the resource
    • example of the resources attribute:

    {
    "resource": [
    {
    "key": "form-serverless-lambda",
    "url": "https://lambda-endpoint-url",
    "headers": [
    {
    "name": "X-Skyledge-Token",
    "value": "your-token-or-method-to-retrieve",
    "isSecret": false
    }
    ]
    }
    ]
    }

    The changes of the form.java class will lead to the following changes on the API Server codebase:

    • FormCreator
    • FormUpdater

    After the changes, the example asset onboarding form template will be as follows form-template-proposed.json.

  1. Changes on the form definition class, to update the form-definition.schema.json
  • Modify the existing form definition schema:

  • type:

    • Removed: Number

      • The number type is removed since it can be replaced by the input type with inputType=‘number’.
    • New: hidden

      • The hidden type is added since it can be used to store the value of the resource, it will not be displayed on the frontend.
  • New attribute for the form definition:

  • resource:

    • type: object
      • the resource is a JSON object, it has the following attributes:
        • key:
          • string
          • the key of the resource, it should be the same as the key of the resource in the resources attribute of the form template
        • path:
          • string
          • the path of the resource, it should be the path of the resource in the resources attribute of the form template
          • example: customers
  • value:

    • string
    • the value of the resource, it should be the value of the resource in the resources attribute of the form template
    • only used when the type is hidden
  • isAutoComplete:

    • boolean
    • the is auto complete of the field
    • only used when the type is input
  • rule:

    • object
    • the rule of the field
    • only used when the type is input
    • the rule is a JSON object, it has the following attributes:
      • regex:
        • string
        • the regex of the field
      • errorMessage:
        • string
        • the error message of the field

Add some existing attributes to the form definition schema:

These attributes are already used in the form template, but not in the form definition schema. Since they’re not in the schema, the validation will be ignored by the form backend service. We need to add them to the form definition schema.

  • inputType:
    • string
    • the input type of the field
    • example: text / number
  • fileType:
    • string
    • the file type of the field
    • example: jpg / jpeg / png / pdf
  1. Changes on the asset and calibration form template

The proposed changes above are for the general changes on the API server. There are some specific changes for the asset and calibration form templates when we create the templates using the proposed changed API server:

  • timezone/country: This is achievable after we have the hidden type in the form definition schema. The country code will be sent to the Lambda function in the POST body to enable location-specific data retrieval and processing. This is a hidden field and will not be displayed on the frontend.

  • resources: This is achievable after we have the resource attribute in the form definition schema. It will be used to point to the correct resource in the form template. For example:

    • key: form-service - it will point to the correct resource in the form template.
    • path: customers - it will point to the correct path in the resource in the form template.

After the changes, the example asset and calibration form template will be as follows form-template-proposed.json.

Form Backend (Express.js)

The form backend is an Express.js server. It retrieves the form template from the database and renders the form on the frontend.

Current state:

Currently, the form backend service (form.service.ts) is responsible for retrieving the form template from the database and rendering the form on the frontend. It directly calls the API server to retrieve the form template.

async loadForm(formIdentifier: string, formsApiKey: string) {
const apiService = new FormApiService(createSkyLedgeService(formsApiKey, 'FormsApiKey'));
return apiService.getForm(formIdentifier);
}

Proposed changes:

To support the new dynamic form features, the form backend service will need to call the Lambda function to retrieve the dynamic fields and values.

async loadDynamicForm(formIdentifier: string, formsApiKey: string) {
const formTemplate = await this.loadForm(formIdentifier, formsApiKey);
// loop through the form template and check if the field is a dynamic field
// if it is, check the resource attribute and call the Lambda function to retrieve the dynamic fields and values
// if it is not, return the form template
// return the form template with the dynamic fields and values
return formTemplate;
}

5. Risks & Mitigations

  • Risk: The form template is not saving correctly in the database, the resource attribute is not being saved correctly.

    • Mitigation: Add validation to the form template to ensure the resource attribute is being saved correctly. Make migration script to migrate the existing form template to the new schema.
    • Rollback: Revert the form template and form definition schema changes.
  • Risk: Schema changes may break existing form templates

    • Mitigation: Test the existing customer onboarding form with updated schema, to make sure the form is working as expected.
    • Rollback: Revert schema changes and maintain old form template structure
  • Risk: Lambda function failures could prevent form loading

    • Mitigation: Implement retry logic and fallback mechanisms in Form Backend service
    • Rollback: Fall back to static customer lists if Lambda is unavailable
  • Risk: Resource header values are not properly secured

    • Mitigation: Implement security measures to protect the resource header values. This is a TBD for a following version and is out of scope of the first version proposed here.
    • Rollback: Fall back to static customer lists if resource header values are not properly secured

6. Impact

Architecture / data / DX / cost / security

Architecture:

  • New form definition schema with hidden field type support
  • New resource attribute for form templates
  • New service layer in Form Backend for Lambda function calls
  • Changes to API Server for form template management

Data:

  • Form templates stored in database with new schema structure
  • Dynamic field data fetched from Lambda functions at runtime

Developer Experience:

  • Form creators can now define dynamic fields with resource references
  • Easier to maintain customer lists and other dynamic content
  • More flexible form configuration without code changes

Breaking changes

Breaking changes: No breaking changes

  • Form definition schema changes: Additional attributes should not break existing old form functionality

8. Alternatives & Appendix

  • Form Service Lambda Design: forms/service/form-service-lambda-design.md

Diagrams

  • Form New Design: forms/form-new-design.png

Further Reading