Introduction
This API request is used to create a new form or make changes to an existing form.
Implementation tip: use GetFormDefinition to pull down the existing form structure if you are building a similar form.
This request’s JSON format varies for different type of forms and several types of fields. Aggregate field types and repeated fields with non-unique shortnames are not supported.
Getting Started
All API requests require an authorization token – reference our Authentication page for more information
API Structure
POST api/integration/SaveFormDesign
Required Request Parameters – All Forms
| Name | Location | Value Options | Description |
|---|---|---|---|
| Authorization token | Header | See Login Authentication API documentation | |
| Operation | Body | "Insert","Update" | Indicate if the API request is to create or update an existing Form. |
| PartialSuccess | Body | "True", "False" | Flag used when updating an existing form |
| RequestNo | Body | Recommended unique for each request, visible within the UI for troubleshooting. | |
| FormID | Body | Leave blank on new form creation | GUID that can be used in other API requests. |
| FormName | Body | Required | Name of form that will be visible within the UI |
| Type | Body | Type : Form Type • 0 : Check • 1 : Audit • 2 : Questionnaire | See the Form Definition Page for information on when to use the different Form Types. Each Form Type corresponds to a numerical value - the numerical value is passed in the API request |
| Version | Body | New form: "0.1" Existing form: current value. | Version numbers are incremented automatically for existing forms, all new forms start at version 0.1 |
| Resource ID | Body | "" | GUID exposed in GetResources API response, value is optional. |
| Resource Name | Body | The name of the Resource within the UI. | |
| Field Information | Body | See Below Table – will vary by Form Type and Field type. |
Field Information Parameters – Check Type Form
The table below outlines the different role each value used within the different field types plays.
| Name | Required | Value Options | Description |
|---|---|---|---|
| Type | Required | Type : Field Type • 15 : Identifier • 5 : Text • 6 : Paragraph • 7 : Select One • 8 : Select Multiple • 9 : Numeric • 10 : Date • 11 : Time • 12 : Date & Time | Field types are used to format how the user will provide their answer to a field – a free text entry, picking one or more options from a drop down etc. Each field type corresponds to a numerical value - the numerical value is passed in the API request. |
| ShowMinMax | Conditionally Required | "True"," False" | Used only on Numeric fields, makes the ranges set for Min and Max visible to the user. |
| ShowTarget | Conditionally Required | "True"," False" | Used only on Numeric fields, makes the target value set visible to the user. |
| IsIntegrated | Conditionally Required | "True"," False" | Used only for Numeric fields enabled with BlueTherm hardware. |
| DependencyRule | Required | null | Covered in Advanced API Integration Technical Specification Document. |
| ExpressionRule | Required | null | Covered in Advanced API Integration Technical Specification Document. |
| FailsForm | Required | "True"," False" | Indicates if a non-compliant value should result in the entire form being marked as non-compliant. |
| AllowCorrection | Required | "True"," False" | Covered in Advanced Form Integration API Technical Specification Document. |
| PredefinedCorrections | Conditionally Required | null | Covered in Advanced Form Integration API Technical Specification Document. |
| ShowIsResolved | Conditionally Required | "True"," False" | Setting to enable a flag within the UI to show on non-compliant answers. |
| Configuration | Required | Null | Functionality not in use, must be set to null. |
| IsCompliant | Conditionally Required | null | Covered in Form Compliance API Integration Technical Specification Document. |
| DefaultCompliance | Conditionally Required | null | Covered in Form Compliance API Integration Technical Specification Document. |
| StepperTypeID | Conditionally Required | ID : StepperType • ebc1926c-17ad-4c96-bfd4-a1c0f4bb404b : Numeric • b476a878-10b7-45df-ad25-9272f19a0074 : Standard • 4f21287f-19cc-4399-a1fd-2544fa1f5ef9 : Tally Optimized | Used only on Numeric fields. |
| StepperTypeName | Conditionally Required | "Numeric", "Standard", "Tally Optimized" | Set to Numeric for only collecting number entries, other options are for tally +/- functionality. |
| ElementType | Required | 0 | Used for internal purpose, set to zero. |
| IsRequired | Required | "True"," False" | Flag to indicate if field is required to be completed by user before submission. |
| AllowComments | Conditionally Required | "True"," False" | Optional flag to allow user to enter additional comments. Default is False. |
| Comment | Conditionally Required | null | Value will be entered by user, always set to null. Must include if AllowComments is set to true. |
| AllowAttachments | Conditionally Required | "True"," False" | Flag to allow user to attach pictures or files to the field. Default is false. |
| Attachments | Conditionally Required | null | Value will be entered by user, always set to null. Must include if AllowAttchments is set to true. |
| ShowOnCOA | Optional | "True"," False" | Flag that can be used for your own purposes for flagging data. |
| ShowHint | Conditionally Required | "True"," False" | Flag to reveal additional instructions or reminders to the User for that specific field. Default is False. |
| Hint | Optional | "Sample text value" | Include text only if ShowHint is set to True. |
| Repeat | Conditionally Required | Only available with numeric fields. | |
| GroupID | Required | "00000000-0000-0000-0000-000000000000" | Suggested default GUID provided in Options column. |
| ShowField | Required | "True"," False" | Dictate per Resource if the field should be visible to the Resource. |
| FieldBankID | Optional | "00000000-0000-0000-0000-000000000000" | Suggested default GUID provided in Options column. Functionality not in use. |
| ParentID | Required | null | While designing form, value will always be null. |
| Value | Required | null | While designing form, value will always be null. |
| Default | Conditionally Required | Only include a value when selection should be predetermined for user, otherwise set to null. | |
| ID | Required | "00000000-0000-0000-0000-000000000000" | Suggested default GUID provided in Options column. |
| Name | Required | UI Name of field that will be visible to the user | |
| Shortname | Required | Internal UI Name that will be used in other parts of form building or API calls. Must be unique. | |
| ShowPointsPossible | Conditionally Required | null | Must be set to null on type Check Form. |
| ShowPointsEarned | Conditionally Required | null | Must be set to null on type Check Form. |
| QuestionWeight | Conditionally Required | null | Must be set to null on type Check Form. |
Field Information Parameters – Audit Form Type
| Name | Required | Value Options | Description |
|---|---|---|---|
| ShowPointsPossible | Required | "True"," False" | Show or hide the points possible that can be earned to the user |
| ShowPointsEarned | Required | "True"," False" | Show or hide the points earned to the user. |
| QuestionWeight | Required | Integer value | The overall points allowed for a question, must be whole numbers no decimals. |
Check Form Type Request JSON
{
"Operation": "Insert",
"PartialSuccess": "false",
"RequestNo": "Request Example 01",
"Data": [
{
"FormId": "",
"FormName": "Micro-Environmental Sanitation Check",
"Type": 0,
"Version": "0.1",
"Resources": [
{
"Id": "",
"Name": "Equipment > E1 > Metal Detector Line"
}
],
"Fields": [
{
"Type": 9,
"ShowMinMax": true,
"ShowTarget": false,
"IsIntegrated": false,
"DependencyRule": null,
"ExpressionRule": null,
"FailsForm": true,
"AllowCorrection": false,
"PredefinedCorrections": null,
"ShowIsResolved": false,
"Configuration": null,
"IsCompliant": null,
"DefaultCompliance": null,
"StepperTypeId": "ebc1926c-17ad-4c96-bfd4-a1c0f4bb404b",
"StepperTypeName": "Numeric",
"ElementType": 0,
"IsRequired": true,
"AllowComments": false,
"Comment": null,
"AllowAttachments": false,
"Attachments": null,
"ShowOnCOA": true,
"ShowHint": false,
"Hint": null,
"ShowPointsPossible": null,
"ShowPointsEarned": null,
"QuestionWeight": null,
"Order": 0,
"Repeat": null,
"GroupID": "00000000-0000-0000-0000-000000000000",
"ShowField": true,
"FieldBankId": "00000000-0000-0000-0000-000000000000",
"ParentId": null,
"Value": null,
"Default": null,
"Id": "00000000-0000-0000-0000-000000000000",
"Name": "ATP Reading",
"ShortName": "ATP Reading"
},
{
"Type": 8,
"ControlType": 0,
"Options": [
{
"Value": null,
"Id": "00000000-0000-0000-0000-000000000000",
"Name": "Metal Detector"
},
{
"Value": null,
"Id": "00000000-0000-0000-0000-000000000000",
"Name": "Conveyor Belt"
},
{
"Value": null,
"Id": "00000000-0000-0000-0000-000000000000",
"Name": "Conveyor Belt Buckets"
}
],
"DependencyRule": null,
"ExpressionRule": null,
"FailsForm": true,
"AllowCorrection": false,
"PredefinedCorrections": null,
"ShowIsResolved": false,
"Configuration": null,
"IsCompliant": null,
"DefaultCompliance": null,
"ElementType": 0,
"IsRequired": true,
"AllowComments": false,
"Comment": null,
"AllowAttachments": false,
"Attachments": null,
"ShowOnCOA": true,
"ShowHint": false,
"Hint": null,
"ShowPointsPossible": false,
"ShowPointsEarned": false,
"QuestionWeight": 0,
"Order": 0,
"Repeat": null,
"GroupID": "00000000-0000-0000-0000-000000000000",
"ShowField": true,
"FieldBankId": "00000000-0000-0000-0000-000000000000",
"ParentId": null,
"Value": null,
"Default": null,
"Id": "00000000-0000-0000-0000-000000000000",
"Name": "Surfaces Swabbed",
"ShortName": "Surfaces Swabbed"
}
]
}
]
}Response Parameters
| Name | Description |
|---|---|
| RequestID | Use this GUID within our GetBatchStatus API to request updates on when the request will be processed outside of the UI. See Request Status API documentation for more information on GetBatchStatus. |
| RequestStatus | If no syntax errors are present the default response is Pending until the request can be processed. |
| RequestError | Error object providing information if an error occurs |
| Status | Indicating the success of the API request |
Response JSON
{
"RequestId": "774c16bd-2e03-4f8a-97ab-004cb940b800",
"RequestStatus": "Inprocess",
"RequestError": [
{
"ErrorCode": 0,
"FieldName": null,
"FieldValues": null,
"ErrorMessage": "",
"Header": null
}
],
"Status": true,
"Errors": null,
"RefreshToken": false
}