Activity Forms

Activity forms contain field definitions that define the prompts for the form. Each form is associated with a form type that tells the system how to process the information in the form.

Some form types have a pre-defined form with a standard set of field definitions. You can use pre-defined forms or create a copy of a form to collect information specific to your business.

Note: This API resource allows you to indicate which fields you want to be required, optional, read-only, or hidden. When you create new forms, take note of the fields specified as "Required" in the pre-defined forms as guidance for creating useful forms.

Prerequisites

If you do not plan to use pre-existing field definitions, you must create custom field definitions before creating activity forms.

Example

In this example, we create, verify, update, and delete an activity form.

Create an activity form

The create request:

creates a new activity form named: 12345
- Activity form names should consist of a unique alphanumeric code.
- Activity form names should match the formCode
defines the form type, locale policy, clock search configuration, default status, and other options

The building blocks for activity forms are added by object reference. You can retrieve a list of each type of activity form building block by calling the operations against the Activity Form Resources API resource. For example, you can retrieve a list of all form types in the system by calling the Retrieve All Form Types GET /v1/work/forms/setup/form_types operation.

For more information

To understand how activity forms are built, how steps are configured, how to configure access to forms to allow employees to enter activity data, and how to configure devices to collect activity form data, refer to the Form Builder section of the Activities Setup UI help documentation.

Example request

Call the Create Activity Form POST /v1/work/forms operation with the following request payload.

{
  "formCode": "12345",
  "description": "An example activity form.",
  "version": 1,
  "steps": [
    {
      "prompt": "Enter Badge Number",
      "matchFieldLength": false,
      "fieldDefinition": {
        "id": -12,
        "qualifier": "_Employee Badge"
      },
      "fieldType": {
        "id": 4,
        "qualifier": "Numeric"
      },
      "entryType": {
        "id": 1,
        "qualifier": "Required"
      },
      "validationType": {
        "id": 0,
        "qualifier": "None"
      },
      "inputSourceType": {
        "id": 1,
        "qualifier": "Keypad"
      },
      "initialResult": false,
      "multiSelect": false,
      "name": "Enter Badge Number"
    },
    {
      "prompt": "First Activity",
      "fieldLength": 50,
      "matchFieldLength": false,
      "fieldDefinition": {
        "id": -1,
        "qualifier": "_Activity Level 1"
      },
      "fieldType": {
        "id": 0,
        "qualifier": "Alpha numeric"
      },
      "entryType": {
        "id": 1,
        "qualifier": "Required"
      },
      "validationType": {
        "id": 0,
        "qualifier": "None"
      },
      "inputSourceType": {
        "id": 0,
        "qualifier": "Any"
      },
      "initialResult": false,
      "multiSelect": false,
      "name": "First Activity"
    },
    {
      "prompt": "Complete? Y/N",
      "fieldLength": 1,
      "matchFieldLength": true,
      "fieldDefinition": {
        "id": -7,
        "qualifier": "_Completion Status"
      },
      "fieldType": {
        "id": 0,
        "qualifier": "Alpha numeric"
      },
      "entryType": {
        "id": 1,
        "qualifier": "Required"
      },
      "defaultValue": "N",
      "validationType": {
        "id": 0,
        "qualifier": "None"
      },
      "inputSourceType": {
        "id": 0,
        "qualifier": "Any"
      },
      "initialResult": false,
      "multiSelect": false,
      "name": "Complete? Y/N"
    }
  ],
  "timeOut": 15,
  "formType": {
    "id": 0,
    "qualifier": "Activity Start (Start-Stop)"
  },
  "verifyBiometric": false,
  "offline": false,
  "localePolicy": {
    "id": 1,
    "qualifier": "American English"
  },
  "clocksSearchConfiguration": {
    "direct": true,
    "query": false,
    "hierarchy": false
  },
  "name": "12345",
  "default": false
}

Example response

A success response returns HTTP status code 200 and a response body similar to the following example.

{
    "id": 51,
    "formCode": "12345",
    "description": "An example activity form.",
    "version": 1,
    "steps": [
        {
            "id": 51,
            "prompt": "Enter Badge Number",
            "matchFieldLength": false,
            "fieldDefinition": {
                "id": -12,
                "qualifier": "_Employee Badge"
            },
            "fieldType": {
                "id": 4,
                "qualifier": "Numeric"
            },
            "entryType": {
                "id": 1,
                "qualifier": "Required"
            },
            "validationType": {
                "id": 0,
                "qualifier": "None"
            },
            "inputSourceType": {
                "id": 1,
                "qualifier": "Keypad"
            },
            "initialResult": false,
            "multiSelect": false,
            "name": "Enter Badge Number"
        },
        {
            "id": 52,
            "prompt": "First Activity",
            "fieldLength": 50,
            "matchFieldLength": false,
            "fieldDefinition": {
                "id": -1,
                "qualifier": "_Activity Level 1"
            },
            "fieldType": {
                "id": 0,
                "qualifier": "Alpha numeric"
            },
            "entryType": {
                "id": 1,
                "qualifier": "Required"
            },
            "validationType": {
                "id": 0,
                "qualifier": "None"
            },
            "inputSourceType": {
                "id": 0,
                "qualifier": "Any"
            },
            "initialResult": false,
            "multiSelect": false,
            "name": "First Activity"
        },
        {
            "id": 53,
            "prompt": "Complete? Y/N",
            "fieldLength": 1,
            "matchFieldLength": true,
            "fieldDefinition": {
                "id": -7,
                "qualifier": "_Completion Status"
            },
            "fieldType": {
                "id": 0,
                "qualifier": "Alpha numeric"
            },
            "entryType": {
                "id": 1,
                "qualifier": "Required"
            },
            "defaultValue": "N",
            "validationType": {
                "id": 0,
                "qualifier": "None"
            },
            "inputSourceType": {
                "id": 0,
                "qualifier": "Any"
            },
            "initialResult": false,
            "multiSelect": false,
            "name": "Complete? Y/N"
        }
    ],
    "timeOut": 15,
    "formType": {
        "id": 0,
        "qualifier": "Activity Start (Start-Stop)"
    },
    "verifyBiometric": false,
    "offline": false,
    "localePolicy": {
        "id": 1,
        "qualifier": "American English"
    },
    "clocksSearchConfiguration": {
        "direct": true,
        "query": false,
        "hierarchy": false
    },
    "name": "12345",
    "default": false
}

Verify

To verify, call either the Retrieve Activity Form by ID GET /v1/work/forms/{id} or the Retrieve All Activity Forms or by Name GET /v1/work/forms?name={name} operation.

Calling GET /v1/work/forms/51 or GET /v1/work/forms?name=12345 returns:

{
    "id": 51,
    "formCode": "12345",
    "description": "An example activity form.",
    "version": 1,
    "steps": [
        {
            "id": 51,
            "prompt": "Enter Badge Number",
            "matchFieldLength": false,
            "fieldDefinition": {
                "id": -12,
                "qualifier": "_Employee Badge"
            },
            "fieldType": {
                "id": 4,
                "qualifier": "Numeric"
            },
            "entryType": {
                "id": 1,
                "qualifier": "Required"
            },
            "validationType": {
                "id": 0,
                "qualifier": "None"
            },
            "inputSourceType": {
                "id": 1,
                "qualifier": "Keypad"
            },
            "initialResult": false,
            "multiSelect": false,
            "name": "Enter Badge Number"
        },
        {
            "id": 52,
            "prompt": "First Activity",
            "fieldLength": 50,
            "matchFieldLength": false,
            "fieldDefinition": {
                "id": -1,
                "qualifier": "_Activity Level 1"
            },
            "fieldType": {
                "id": 0,
                "qualifier": "Alpha numeric"
            },
            "entryType": {
                "id": 1,
                "qualifier": "Required"
            },
            "validationType": {
                "id": 0,
                "qualifier": "None"
            },
            "inputSourceType": {
                "id": 0,
                "qualifier": "Any"
            },
            "initialResult": false,
            "multiSelect": false,
            "name": "First Activity"
        },
        {
            "id": 53,
            "prompt": "Complete? Y/N",
            "fieldLength": 1,
            "matchFieldLength": true,
            "fieldDefinition": {
                "id": -7,
                "qualifier": "_Completion Status"
            },
            "fieldType": {
                "id": 0,
                "qualifier": "Alpha numeric"
            },
            "entryType": {
                "id": 1,
                "qualifier": "Required"
            },
            "defaultValue": "N",
            "validationType": {
                "id": 0,
                "qualifier": "None"
            },
            "inputSourceType": {
                "id": 0,
                "qualifier": "Any"
            },
            "initialResult": false,
            "multiSelect": false,
            "name": "Complete? Y/N"
        }
    ],
    "timeOut": 15,
    "formType": {
        "id": 0,
        "qualifier": "Activity Start (Start-Stop)"
    },
    "verifyBiometric": false,
    "offline": false,
    "localePolicy": {
        "id": 1,
        "qualifier": "American English"
    },
    "clocksSearchConfiguration": {
        "direct": true,
        "query": false,
        "hierarchy": false
    },
    "name": "12345",
    "default": false
}

Note: The Retrieve All Activity Forms or by Name GET /v1/work/forms?name=12345 operation returns the object above enclosed in an array, since omitting the name query parameter returns all activity forms in the system.

Note: The Retrieve All Activity Forms or by Name GET /v1/work/forms operation without the name query parameter returns all activity forms but omits the details inside the steps array.

Update the activity form

To update the activity form by removing the final step, call the Update Activity Form by ID PUT /v1/work/forms/51 opertion with the following request payload.

Example request

{
  "id": 51,
  "formCode": "12345",
  "description": "An example activity form.",
  "version": 1,
  "steps": [
    {
      "prompt": "Enter Badge Number",
      "matchFieldLength": false,
      "fieldDefinition": {
        "id": -12,
        "qualifier": "_Employee Badge"
      },
      "fieldType": {
        "id": 4,
        "qualifier": "Numeric"
      },
      "entryType": {
        "id": 1,
        "qualifier": "Required"
      },
      "validationType": {
        "id": 0,
        "qualifier": "None"
      },
      "inputSourceType": {
        "id": 1,
        "qualifier": "Keypad"
      },
      "initialResult": false,
      "multiSelect": false,
      "name": "Enter Badge Number"
    },
    {
      "prompt": "First Activity",
      "fieldLength": 50,
      "matchFieldLength": false,
      "fieldDefinition": {
        "id": -1,
        "qualifier": "_Activity Level 1"
      },
      "fieldType": {
        "id": 0,
        "qualifier": "Alpha numeric"
      },
      "entryType": {
        "id": 1,
        "qualifier": "Required"
      },
      "validationType": {
        "id": 0,
        "qualifier": "None"
      },
      "inputSourceType": {
        "id": 0,
        "qualifier": "Any"
      },
      "initialResult": false,
      "multiSelect": false,
      "name": "First Activity"
    }
  ],
  "timeOut": 15,
  "formType": {
    "id": 0,
    "qualifier": "Activity Start (Start-Stop)"
  },
  "verifyBiometric": false,
  "offline": false,
  "localePolicy": {
    "id": 1,
    "qualifier": "American English"
  },
  "clocksSearchConfiguration": {
    "direct": true,
    "query": false,
    "hierarchy": false
  },
  "name": "12345",
  "default": false
}

Example response

{
    "id": 51,
    "formCode": "12345",
    "description": "An example activity form.",
    "version": 2,
    "steps": [
        {
            "id": 54,
            "prompt": "Enter Badge Number",
            "matchFieldLength": false,
            "fieldDefinition": {
                "id": -12,
                "qualifier": "_Employee Badge"
            },
            "fieldType": {
                "id": 4,
                "qualifier": "Numeric"
            },
            "entryType": {
                "id": 1,
                "qualifier": "Required"
            },
            "validationType": {
                "id": 0,
                "qualifier": "None"
            },
            "inputSourceType": {
                "id": 1,
                "qualifier": "Keypad"
            },
            "initialResult": false,
            "multiSelect": false,
            "name": "Enter Badge Number"
        },
        {
            "id": 55,
            "prompt": "First Activity",
            "fieldLength": 50,
            "matchFieldLength": false,
            "fieldDefinition": {
                "id": -1,
                "qualifier": "_Activity Level 1"
            },
            "fieldType": {
                "id": 0,
                "qualifier": "Alpha numeric"
            },
            "entryType": {
                "id": 1,
                "qualifier": "Required"
            },
            "validationType": {
                "id": 0,
                "qualifier": "None"
            },
            "inputSourceType": {
                "id": 0,
                "qualifier": "Any"
            },
            "initialResult": false,
            "multiSelect": false,
            "name": "First Activity"
        }
    ],
    "timeOut": 15,
    "formType": {
        "id": 0,
        "qualifier": "Activity Start (Start-Stop)"
    },
    "verifyBiometric": false,
    "offline": false,
    "localePolicy": {
        "id": 1,
        "qualifier": "American English"
    },
    "clocksSearchConfiguration": {
        "direct": true,
        "query": false,
        "hierarchy": false
    },
    "name": "12345",
    "default": false
}

Note that the version is automatically incremented to 2. To successfully update this activity form again, you must pass version 2 in the next request body.

Delete the activity form

To delete this activity form, call the Delete Activity Form by ID DELETE /v1/work/forms/51 operation.

The system returns HTTP status 204 with an empty response body.