Form API

Introduction

The Form API allows you to interact with form data from a specified form within the current app context in Joget. This API supports various operations, including adding, updating, retrieving, and deleting form data, as well as handling file uploads.

Plugin information

This API is based on the specified form in the current app context. It can be used to manage form records and interact with file uploads associated with the form.

Get started

Prerequisites

• You have a form created in the current Joget app.
• You can access the form ID and understand the form's data schema.

Where to get the plugin

You can access the Form API within the Joget platform under the API section.

How to install

The Form API is a built-in feature in Joget and does not require separate installation.

How to use it

1. Drag and drop the Form API from the Palette to the Canvas.
2. Select Form
3. Enter Short Description (optional)
4. Select the endpoints

• Form: Select any form present in the current app for interaction with API.
• Short Description: Any description.
• Ignore form Permission: Check this option to ignore form & form section permission for current users when storing/retrieving form data.

 

List of API Endpoints

Add form data

Add a new record to the specified form.

URL: /form/{formId}

HTTP Method: POST

Path Parameters

Parameter	Description
formId	Form ID.

Body Parameters

The parameters required here are highly dependent on the form data schema of the specified form.

For example, for the Expense Claim Form in the Expenses Claim app found in most default Joget installations, it may look like this:

{
  "id": "string",
  "sfD": {
    "ref": "string",
    "title": "string",
    "remark": "string",
    "SelectApprover": "string",
    "claimant": "string",
    "username": "string",
    "status": "string",
    "id": "string"
  },
  "spECD": [
    {
      "id": "string",
      "category": "string",
      "date": "string",
      "purpose": "string",
      "amount": "string"
    }
  ],
  "total": "string",
  "receipt": "string",
  "CreatedDate": "string",
  "dateCreated": "2019-08-28",
  "dateModified": "2019-08-28",
  "createdBy": "string",
  "createdByName": "string",
  "modifiedBy": "string",
  "modifiedByName": "string"
}

Sample Response

The record ID will be returned as the successful response.

{
  "id": "d6cc05e4-c0a86310-60e35ca0-9dd035a0",
  "errors": {}
}

 

Add form data with file upload

Add a new record to the specified form, with support for file handling.

URL: /form/{formId}/addWithFiles

HTTP Method: POST

Path Parameters

Parameter	Description
formId	Form ID.

Body Parameters

The parameters required here are highly dependent on the form data schema of the specified form.

Sample Response

The record ID will be returned as the successful response.

{
  "id": "cd0f9c53-1e08-437f-868a-c8a76a9fad7f",
  "errors": {}
}

 

Delete form data

Delete a record of the specified form via record ID.

URL: /form/{formId}/{recordId}

HTTP Method: DELETE

Path Parameters

Parameter	Description
formId	Form ID.
recordId	Form record ID.

Sample Response

{
  "date": "Wed Aug 28 14:07:37 SGT 2019",
  "code": "200",
  "message": "Successful operation"
}

 

Download all uploaded files in zip

Download all uploaded files from a specified form upload field and compress them into a zip file.

Commonly used for form upload fields that support multiple file uploads.

URL: /form/{formId}/{recordId}/{fieldId}/files

HTTP Method: GET

Path Parameters

Parameter	Description
formId	Form ID.
recordId	Form record ID.
fieldId	Upload Field ID.

Sample Response

All files found will be bundled and downloaded as a zip file.

 

Download uploaded file

Download an uploaded file from a specified form upload field.

URL: /form/{formId}/{recordId}/download/{fileName}

HTTP Method: GET

Path Parameters

Parameter	Description
formId	Form ID.
recordId	Form record ID.
fieldId	Upload Field ID.

Query String Parameters

Parameter	Description
attachment	Option to set the file as attachment. Expect a boolean value.

Sample Response

The file will be downloaded.

 

Get form data by record ID

Retrieve data of a record from the specified form, via record ID.

URL: /form/{formId}/{recordId}

HTTP Method: GET

Path Parameters

Parameter	Description
formId	Form ID.
recordId	Form record ID.

 

Query String Parameters

Parameter	Description
includeSubformData	Include all subform(s) data present in the specified form in the response.
includeReferenceElements	Include all referenced elements present in the specified form in the response. (e.g., select box element referencing a list record)
flattenData	Option to flatten all JSON objects to a single-level key-value map.

 

Sample Response

{
  "createdByName": "Admin Admin",
  "dateModified": "2019-08-15 15:43:35.0",
  "remark": "",
  "title": "Spend everything",
  "SelectApprover": "admin",
  "ref": "0001",
  "total": "0.00",
  "modifiedByName": "Admin Admin",
  "dateCreated": "2019-04-25 20:14:28.0",
  "createdBy": "admin",
  "CreatedDate": "2019-08-15",
  "modifiedBy": "admin",
  "receipt": "",
  "id": "44_expenseclaim_process1",
  "claimant": "Admin Admin",
  "status": "Submitted",
  "username": "admin"
}

 

Update form data

Update a record in the specified form.

URL: /form/{formId}

HTTP Method: PUT

Path Parameters

Parameter	Description
formId	Form ID.

Body Parameters

The parameters required here are highly dependent on the form data schema of the specified form.

Sample Response

The record ID will be returned as the successful response.

{
  "id": "d6cc05e4-c0a86310-60e35ca0-9dd035a0",
  "errors": {}
}

 

Update form data with file upload

Update a record in the specified form with support for file handling.

URL: /form/{formId}/updateWithFiles

HTTP Method: POST

Path Parameters

Parameter	Description
formId	Form ID.

Body Parameters

The parameters required here are highly dependent on the form data schema of the specified form.

Sample Response

{
  "id": "d6cc05e4-c0a86310-60e35ca0-9dd035a0",
  "errors": {}
}