Custom Forms and Fields

Overview

A feature of several object types in the system, including Buildings, Organiza-ons, and Users, is the ability to extend the data model by including user-defined or custom fields. These fields have attributes such as a data type, a name, and can have values depending on different objects they are related to.

In this way if, for instance, a building has a special region and a certain kind of charge code, those can be represented as fields defined by the organization. These fields will appear in forms, API results, and should be selected in grids and in exports.

Also, futures for Custom Fields include types on tasks such as Work Orders and Equipment and allowing for fields for certain types of objects.

 

Types of Custom Fields

1. Saved Field
2. New Field

Types of New Custom Fields

1. Text Field
2. Text Area
3. Number Field
4. Currency Field
5. Date Picker
6. Phone
7. File
8. Dropdown Menu

Some validation is performed as well. For a text field, a maximum length will be enforced and specialized types, such as URLs, are validated for correctness.

Management of Custom Fields

Custom Fields are managed via the /custom_fields endpoints.

Creating Forms

How to Create Forms: UI Workflow

Steps to Create a Form

1. Login as PMO
2. Click on the Admin module
3. Click on Forms
4. Click on +Add a Form
5. Enter a Name
6. Click on + Add Custom Fields
7. Click on New Custom Field
8. Enter a Name for the Custom Field
9. Click on Add Custom Fields
10. Click on Save

 

How to Creation Forms: API

When a custom field exists, creating a value or updating one simply implies passing the custom_fields array as part of the body to a request. For instance, to set the field named “location_billing_code”, one must simply pass a JSON object in the custom_fields array with the field_name and value elements.

The type of the data object should be either string, numeric, or Boolean depending on the custom field type. Date values should be in ISO standard date strings with timezone information. An example of creating or updating a field follows:

{
“custom_fields”: [
“field_name”: “location_billing_code”,
“value”: “LBS-THX-1138” 
]
}

In the above example, this could be a POST to the /buildings endpoint. The example would obviously work as a PATCH given the partial data. A PATCH of custom fields can accompany updates to other fields in the object as well.

Create a Form

• Pre-Condition: User should have Admin access
• POST /custom_fields/pages
• Request body:
  • Note: For work order forms, content_type will be “work_orders.WorkOrder”)

 

Edit a Form

• PUT /custom_fields/pages
• Request body:
  • Note: For work order forms, content_type will be “work_orders.WorkOrder”):

 

New Custom Fields

• Pre-Condition: User should have these access permissions to create a tenant company
• POST /custom_fields/fields
  • Request body:

 

Saved Custom Fields

• Pre-Condition: User should have these access permissions to create a tenant company and should have some Custom Fields that are pre-created
• POST /custom_fields/pages
• Request body:
  • Note: For work order forms, content_type will be “work_orders.WorkOrder”):

 

How to GET Form Data (via API)

An object that includes custom fields, such as a Building, will return the fields as an array of JavaScript Object NotaDon (JSON) objects. The structure is:

• custom_fields (Array)
  • Object
    • id – GUID internal identifier of the value
    • field_id – GUID identifier of the field this object represents
    • field_name – API name of the custom field
    • value – Value of the object
    • field – Object
      • id – GUID of the field
      • name – API name for the field
      • display_name – Display name for the field
      • data_type – Data type for the field

An example of a complete record would appear as follows:

"custom_fields": [
{
"data_type": "text",
"id": "e92c70fb-1f19-4e7a-ae15-e4d2a24ce543", 
"field_id": "a30b59ca-7b29-4e1e-94f0-d496a0e797ab", 
"field_name": "location_billing_code",
"field": {
"id": "a30b59ca-7b29-4e1e-94f0-d496a0e797ab", 
"name": "location_billing_code", 
"display_name": "Location Billing Code", 
"data_type": "text"
},
"value": "BE-PROD/BOS/179"
}

This example shows reading a populated value of a text string named Location Billing Code that internally is referenced by the API field name of “location_billing_code”.

Integrating Forms with Prism Modules

How a Form is Integrated with Work Order module

1. Create an Issue Type with a Form having questions
2. Use the Same Issue Type while Creating the Work Order

How a Form is Integrated with Accounting module

1. Create a Form with Custom Field which is having Accounting Related toggle Turned On
2. Navigate to Accounting → Template and Check the Custom Fields

How Form is Integrated with Properties module

1. Create a Form with a new Custom Field
2. Navigate to My ProperDes and Open any existing property
3. Click on the Custom field and Edit
4. Click on “+ Add Custom Field“
5. Check the Newly added Custom field is reflected in My Properties

How Form is Integrated with My Users module

1. Create a Form with a new Custom Field
2. Navigate to My Users and Open any existing user
3. Click on the Custom field and Edit
4. Click on “+ Add Custom Field“
5. Check the Newly added Custom field is reflected in My Properties