How To Use The Rest API End Point - User Interface Forms
Use this end-point to request information about a Form in the User Interface.
The data could be used to render a form to the end-user. The form data takes in to consideration
the requesting user's Access Rights, so only the applicable fields will be displayed.
Form data is required if you are using Web Sockets. Web Sockets that use form prompts require values
from Buttons in order to proceed.
GET Type End-Point
/api/v1/collect/ui/forms/{formid}
For a Web Socket prompt, the formid is part of the message.
For a general form display, the formid needs to be known by the application making the API request.
For a list of formid's, you can use the READ RECORDS end-point above on the Application Form
table. The formid's are stored in the af_form_fieldname field.
/api/v1/collect/data/application_form?filter=af_form_name__nlike='%25:%25',af_form_name__nlike='%23%25'&fields=af_form_name,af_form_fieldname&sort=af_form_name
Example
The below code will obtain the Schedule Next Contact form. This is a common form used in Prompt
to Confirm Details for Contact Plans.
/api/v1/collect/ui/forms/35d01ff2-775d-ccb4-8f53-25d36f517384
Response Body
The response will contain basic information about the form and detailed information about each
available field.
Form Attrubutes
| Attribute |
Description |
| name |
This is the hard-coded internal name for a form. Example: Debtor |
| alias |
If the form has an Alias set, then this attribute will be present. It is meant to override
the Name attribute. Example: Consumer |
| id |
This is a unique UUID value associated with each Access Right in the database to identify
forms and fields. |
| width |
This is the width of the form. It's meant to be used with VW in CSS. For example, a value
of 86 would be the lower value of 87vh (86 + 1) or 95vh. |
| height |
This is the height of the form. It's meant to be used with PX in CSS. For example, a value
of 17 would be 462.50px ((17 + 1.5) * 25). |
| rights |
This is the permissions for the form:
- 0: Full Access
- 1: No Delete
- 2: Read Only
- 3: No Access - Forms and Fields that are No Access are typically not returned by
the API.
|
| recId |
This is the database table name. |
| recType |
This is an internal, numerical identifier for the database table. |
| controlFile |
If a form has a Control File attached to it, the contents of the control file will be output
in plain text. |
| fields |
This is an array of the fields on the form that are accessible. Each element of the array
is just the FieldID UUID value. Each value contains a sub-array of attributes for the
field. |
Field Attrubutes
| Attribute |
Description |
| name |
This is the hard-coded internal name for a field. Example: State |
| alias |
If the field has an Alias set, then this attribute will be present. It is meant to override
the Name attribute. Example: Province |
| recId |
This is the database table name. |
| id |
This is a unique UUID value associated with each Access Right in the database to identify
forms and fields. |
| x |
This is the number of characters from the left edge of the form. |
| y |
This is the number of rows from the top edge of the form. |
| width |
This is the width of the field. It's meant to be used as a percentage of the VW in CSS. For
example, a value of 10 would be 11.60% (10 * (100 / 86)) on a form with a width of 86. |
| height |
This is the height of the field in rows. The Collect! User Interface uses 22px for the field
height. If this has a value greater than 1, it is treated as a text area with this value
used for the number of rows. |
| listSize |
This is the width of the field in number of characters, when displayed in a list. No padding
is added for image icons. |
| listOrder |
Lists are ordered from left to right based on the fields where the value is greater than
zero. All fields will a value of 0 are placed at the end of the list. Any fields that have
the same value should then be ordered in the same order that they appear in the JSON result
body. Only fields that have attList as TRUE below will be included in list view. |
| color |
This is a hex color value, prefixed with the # symbol. It sets the background color of fields.
Colors do not work on fields that have a Pick List. Background Colors for Pick List fields
are set by the Pick List Entry's RGB values. |
| dataType |
This is the Data Type for the field:
- char: Typically, char fields are single character integers
- int: Whole Numbers
- float: Numbers with up to 4 decimals
- string: Alphanumeric text
- bool: checkbox
- radio: radio selector
- button: button that only appears on a form
- listButton: button that only appears in a list
- label: text only with no field input
- line: draws a line, no field input
- box: draws a box, no field input
- key: pick list field linked to another record list. For example: Debtor Status on the
Debtor form is a Foreign Key field
- owner: pick list field linked to an Owner record list. For example: Client Name or Number
on the Debtor form is an Owner field
- listTab: tab with member list. For example, the Contacts tab on the Debtor form. If this
field has this data type, then the subForm value will be set below to identify the
applicable form data. The list on will have a foreign key relationship with the
current record.
- formTab: tab with a form. For example, the Misc tab on the Debtor form. If this
field has this data type, then the subForm value will be set below to identify the
applicable form data.
- infoTab: tab with list data that does not have a relationship to this form. For example:
the Application Log list on the Collect! Application Log form.
- tab: tab with form or list data. This is an alternative to listTab and formTab.
|
| format |
This is the maximum number of characters that the field can store. |
| subForm |
This will contain the FormID UUID to the list/form that should be displayed. This attribute
is only populated with the listTab, formTab, infoTab, and tab Data Types; otherwise, it is
null. |
| maxValue |
For text fields, it is the maximum number of characters the field can store. For numeric
fields, it is the maximum number the field can store. |
| minValue |
For text fields, it is the minimum number of characters the field can store. For numeric
fields, it is the minimum number the field can store. |
| cmd |
This value is only populated with button or listButton Data Types. If there is a process
that uses this form for a prompt, then you will receive a prompt request on a Web Socket.
The message that goes back to Collect! on that Web Socket will need a button attribute
with this value. |
| tabOrder |
This is the tab order for this field on the form. It is typically numerical, starting from 1. |
| subRec |
This attribute is only visible if the Data Type is key. It will contain the FormID UUID
for the Foreign Key form. For example, the Debtor Status field on the Debtor form would
have the FormID for the "Debtor Status" record. |
| subFld |
This attribute is only visible if the Data Type is key or owner. It will contain the
FieldID UUID for the Foreign Key field. For example, the Debtor Status field on the Debtor
form would have the FieldID for the "Status Code" field on the Debtor Status record. |
| rights |
This is the permissions for the field:
- 0: Full Access
- 1: No Delete
- 2: Read Only
- 3: No Access - Forms and Fields that are No Access are typically not returned by
the API.
|
| dataField |
This is the database field name for this field. This is only populated for fields that
belong to the recId. For any fields, like Foreign Keys or Owners, it will be null. |
| attHidden |
TRUE/FALSE: if true, hide the field |
| attHideLabel |
TRUE/FALSE: if true, hide the field label (Name/Alias) |
| attJust |
Text justification for the field. Values are:
|
| attRequired |
TRUE/FALSE: if true, the field must be populated. The field can also be set to be required
in the verifyFlags below. |
| attShowZero |
TRUE/FALSE: if true, int and float fields should display a 0 for zero values; otherwise,
display a blank |
| attReadOnly |
TRUE/FALSE: if true, set the field to read only. This overrides the rights attribute above. |
| attFileName |
TRUE/FALSE: if true, the data in this field is a file name or HTTP url and should invoke
either a download or opening of a web page. File fields typically have image icons for
opening, printing, deleting, and attaching files. |
| attPassword |
TRUE/FALSE: if true, display asterisks in the field instead of the data |
| attPercent |
TRUE/FALSE: if true for float fields, the number will display to 3 decimal places |
| attCurrency |
TRUE/FALSE: if true for float fields, the number will display to 2 decimal places, with the
applicable currency formatting |
| attDate |
TRUE/FALSE: if true, the field is a date field |
| attTime |
TRUE/FALSE: if true, the field is a time field |
| attPhone |
TRUE/FALSE: if true, the data is a phone number. Phone fields typically have an image icon
for dialing the number with the Dialer module |
| attEmail |
TRUE/FALSE: if true, the data is an email address. Email fields typically have an image icon
for composing a new email |
| attCase |
Text capitalization for the field. Typically, this is only set for string fields. Values are:
- null: do not modify the text
- upper: capitalize all letters of each word
- lower: lower case all letters of each word
- auto: capitalize the first letter of each word
|
| attList |
TRUE/FALSE: if true, this field should be included if viewing in a list instead of a form.
See listOrder above. |
| attBlob |
TRUE/FALSE: if true, this field will be linked to a text editor window that will open
the applicable "blob" record. Typically, fields with this true will have 2 image icons
for opening (or creating) the blob record and for deleting the blob record. In the schema,
there will be a field on the table that ends with "_ attachment_blob" that contains the
rowid of the record in the blobs table. |
| owner |
TRUE/FALSE: if true, this field is an owner field. See dataType above. |
| helpAlias |
On some forms, there is a text area at the top that contains a summary of the Help information
from the documentation. The text here is the text to display in that area. Typically, this is
only populated with the dataType of label. |
| verifyFlags |
This value is derived from the af_log_changes field in the database. The applicable bit
values for the verifyFlags are:
- 1: Verify on exit - if the data in the field changes, then prompt the user to confirm
the data that was changed when the form is submitted.
- 2: Log verification - after the user clicks YES to the above verification, write a
log entry to the notes.
- 8: Required - attRequired above is set when the a field is required by the system.
This option is a user-defined value that can be set in the application.
|
| writeToNotesFlag |
This value is derived from the af_log_changes field in the database. The applicable bit
values is 4, but writeToNotesFlag will be either TRUE or FALSE. |
| pickList |
This attribute is included if the field has a Pick List. A Pick List is a Select box in
HTML terms. This attribute will contain an array of options for the Select box. The array
will have up to 3 elements:
- key: the value part of the Option. This is the value that is stored in the database.
- value: the description or text to display to the end-user
- rgb: if the Pick List Entry has the R, G, and B values populated, then this attrubute
will contain the HEX value, prefixed with the # symbol.
|
| controlFile |
This attribute is included if the field has a Control File. This value will contain the plain
text contents of the Control File. |
Example
{
"name": "Schedule Next Contact",
"id": "35d01ff2-775d-ccb4-8f53-25d36f517384",
"width": 69,
"height": 17,
"rights": 0,
"recId": "contact",
"recType": 64,
"fields": {
"5abdcec0-6ceb-20c2-1a39-7874d3baffee": {
"name": "Date",
"recId": "contact",
"id": "5abdcec0-6ceb-20c2-1a39-7874d3baffee",
"x": 10,
"y": 8,
"width": 10,
"height": 1,
"listSize": 8,
"listOrder": 0,
"color": 0,
"dataType": "int",
"format": 10,
"subForm": null,
"maxValue": 2147483647,
"minValue": -2147483648,
"cmd": 0,
"tabOrder": 1,
"rights": 0,
"dataField": "co_date",
"attHidden": false,
"attHideLabel": false,
"attJust": "left",
"attRequired": false,
"attShowZero": false,
"attReadOnly": false,
"attFileName": false,
"attPassword": false,
"attPercent": false,
"attCurrency": false,
"attDate": true,
"attTime": false,
"attPhone": false,
"attEmail": false,
"attCase": null,
"attList": false,
"attBlob": false,
"owner": false
},
"c3653428-ef04-16f0-2487-a57cdae3cc62": {
"name": "Type",
"recId": "contact",
"id": "c3653428-ef04-16f0-2487-a57cdae3cc62",
"x": 10,
"y": 6,
"width": 16,
"height": 1,
"listSize": 8,
"listOrder": 0,
"color": 0,
"dataType": "int",
"format": 4,
"subForm": null,
"maxValue": 32767,
"minValue": -32768,
"cmd": 0,
"tabOrder": 3,
"rights": 0,
"dataField": "co_type",
"attHidden": false,
"attHideLabel": false,
"attJust": "left",
"attRequired": false,
"attShowZero": false,
"attReadOnly": false,
"attFileName": false,
"attPassword": false,
"attPercent": false,
"attCurrency": false,
"attDate": false,
"attTime": false,
"attPhone": false,
"attEmail": false,
"attCase": null,
"attList": false,
"attBlob": false,
"owner": false,
"pickList": [
{
"key": "12",
"value": "Activate "
},
{
"key": "8",
"value": "Close "
},
{
"key": "18",
"value": "Export "
},
{
"key": "11",
"value": "Edit "
},
{
"key": "0",
"value": "Letter "
},
{
"key": "26",
"value": "Letter In "
},
{
"key": "10",
"value": "Metro "
},
{
"key": "7",
"value": "Note "
},
{
"key": "6",
"value": "Other "
},
{
"key": "13",
"value": "Operator "
},
{
"key": "23",
"value": "Operator Viewed"
},
{
"key": "1",
"value": "Phone "
},
{
"key": "25",
"value": "Phone In "
},
{
"key": "4",
"value": "Plan "
},
{
"key": "3",
"value": "Promise "
},
{
"key": "16",
"value": "Commission "
},
{
"key": "17",
"value": "Rate Plan "
},
{
"key": "5",
"value": "Review "
},
{
"key": "14",
"value": "Sales "
},
{
"key": "22",
"value": "Text/SMS "
},
{
"key": "24",
"value": "Text/SMS In "
},
{
"key": "2",
"value": "Status "
},
{
"key": "15",
"value": "Transaction "
},
{
"key": "19",
"value": "Email "
},
{
"key": "27",
"value": "Email In "
},
{
"key": "20",
"value": "Client "
},
{
"key": "21",
"value": "ODBC "
}
]
},
"a09f989a-48e0-aca1-a294-078e8e914d86": {
"name": "Amount",
"recId": "contact",
"id": "a09f989a-48e0-aca1-a294-078e8e914d86",
"x": 33,
"y": 9,
"width": 9,
"height": 1,
"listSize": 9,
"listOrder": 0,
"color": 0,
"dataType": "float",
"format": 9,
"subForm": null,
"maxValue": 2,
"minValue": 0,
"cmd": 0,
"tabOrder": 4,
"rights": 0,
"dataField": "co_amount",
"attHidden": false,
"attHideLabel": false,
"attJust": "left",
"attRequired": false,
"attShowZero": false,
"attReadOnly": false,
"attFileName": false,
"attPassword": false,
"attPercent": false,
"attCurrency": true,
"attDate": false,
"attTime": false,
"attPhone": false,
"attEmail": false,
"attCase": null,
"attList": false,
"attBlob": false,
"owner": false
},
"2ba67043-f032-614a-7b73-c0c815df524b": {
"name": "Description",
"recId": "contact",
"id": "2ba67043-f032-614a-7b73-c0c815df524b",
"x": 10,
"y": 12,
"width": 37,
"height": 1,
"listSize": 30,
"listOrder": 0,
"color": 0,
"dataType": "string",
"format": 79,
"subForm": null,
"maxValue": 79,
"minValue": 0,
"cmd": 0,
"tabOrder": 6,
"rights": 0,
"dataField": "co_description",
"attHidden": false,
"attHideLabel": false,
"attJust": "left",
"attRequired": false,
"attShowZero": false,
"attReadOnly": false,
"attFileName": false,
"attPassword": false,
"attPercent": false,
"attCurrency": false,
"attDate": false,
"attTime": false,
"attPhone": false,
"attEmail": false,
"attCase": null,
"attList": false,
"attBlob": false,
"owner": false
},
"3ea76176-2319-b6ec-256e-9c16e06e16de": {
"name": "Operator",
"recId": "contact",
"id": "3ea76176-2319-b6ec-256e-9c16e06e16de",
"x": 10,
"y": 16,
"width": 9,
"height": 1,
"listSize": 3,
"listOrder": 0,
"color": 0,
"dataType": "key",
"format": 7,
"subForm": "536b839e-6753-d46e-b695-ab6c67ec2fd7",
"maxValue": 0,
"minValue": 0,
"cmd": 0,
"tabOrder": 7,
"subRec": "nx_operator",
"subFld": "op_id",
"rights": 0,
"dataField": "co_who",
"attHidden": false,
"attHideLabel": false,
"attJust": "left",
"attRequired": false,
"attShowZero": false,
"attReadOnly": false,
"attFileName": false,
"attPassword": false,
"attPercent": false,
"attCurrency": false,
"attDate": false,
"attTime": false,
"attPhone": false,
"attEmail": false,
"attCase": "upper",
"attList": false,
"attBlob": false,
"owner": false
},
"a08631b1-561c-1c73-fef2-115647fb907f": {
"name": "{ ~Next >> }",
"recId": "contact",
"id": "a08631b1-561c-1c73-fef2-115647fb907f",
"x": 54,
"y": 14,
"width": 0,
"height": 0,
"listSize": 0,
"listOrder": 0,
"color": 0,
"dataType": "button",
"format": 0,
"subForm": null,
"maxValue": 0,
"minValue": 0,
"cmd": 4631,
"tabOrder": 11,
"rights": 0,
"dataField": null,
"attHidden": false,
"attHideLabel": false,
"attJust": "left",
"attRequired": false,
"attShowZero": false,
"attReadOnly": false,
"attFileName": false,
"attPassword": false,
"attPercent": false,
"attCurrency": false,
"attDate": false,
"attTime": false,
"attPhone": false,
"attEmail": false,
"attCase": null,
"attList": false,
"attBlob": false,
"owner": false
},
"3ddc23e1-7575-a07f-d0a1-3f04a500c669": {
"name": "Please schedule the next contact",
"recId": "contact",
"id": "3ddc23e1-7575-a07f-d0a1-3f04a500c669",
"x": 0,
"y": 1,
"width": 70,
"height": 4,
"listSize": 0,
"listOrder": 0,
"color": 0,
"dataType": "label",
"format": 0,
"subForm": null,
"maxValue": 0,
"minValue": 0,
"cmd": 0,
"tabOrder": 17,
"rights": 0,
"dataField": null,
"attHidden": false,
"attHideLabel": false,
"attJust": "left",
"attRequired": false,
"attShowZero": false,
"attReadOnly": false,
"attFileName": false,
"attPassword": false,
"attPercent": false,
"attCurrency": false,
"attDate": false,
"attTime": false,
"attPhone": false,
"attEmail": false,
"attCase": null,
"attList": false,
"attBlob": false,
"owner": false,
"helpAlias": "The Schedule Next Contact form is displayed in several situations where Collect! expects you to confirm details."
},
...
}
}
|
Was this page helpful? Do you have any comments on this document? Can we make it better? If so how may we improve this page.
Please click this link to send us your comments: helpinfo@collect.org