How to add Custom Fields to Workflows, Companies, Contracts, Projects and User profiles

This article explains the following: 

• Custom fields overview 
• Custom field types 
• Custom field properties
• Setting up a custom field on user profiles or company, contracts or projects 
• Setting up a custom field on workflows
• Setting the order of custom fields 
• Editing and deleting custom fields 

Note: Some features listed in the article require a Professional or Enterprise licence (speak to our Customer Success Team for a plan comparison). If you wish to implement this feature please speak to  our customer success team and they will liaise with your account manager.

Custom fields overview 

The Custom Fields feature and API provides a simple way to manage your custom fields across different workflows and also profiles for users, companies, and projects and contracts. This feature is initially being rolled out to provide system owners an easy way to add custom fields into workflows, contracts (overview page), projects, companies and users. You need to be a System Owner [User Type] to create custom fields. 

Custom fields can be added separately for each Workflow, Contract, Project, Company and User. These are defined in the System settings page and then appear as additional fields that can be used on the relevant workflow or page. Custom fields are displayed at the bottom of the relevant forms/page. 

As a System Owner you can assign any number of custom fields to any single or multiple Workflows, Contracts, Companies, Projects or Users. This allows companies and projects to enrich their data set and capture additional information on projects, whilst still keeping our data sets clean for all customers. 

Custom fields must be defined via the System Settings page before they can be assigned and are then dynamically added to the relevant page within the Workflow or pages. 

Most custom field values are text strings, with the following exceptions: 

• Address values are nested objects, as defined in the Address documentation. 
• List values must match exactly the drop-down choice in Settings. Any other values will be ignored. 
• Multi Select values are arrays. Their elements must match exactly the drop-down choice in Settings. Any other values will be ignored. 

Managing Changes 

Any custom fields not defined in Settings (e.g. deleted) will be silently ignored, without an error response. If a custom field is added to settings and subsequently deleted, the record will be retained in the database and the association with the resources, but the user interface will hide the custom field when creating new notices/issues raised after the setting is removed. If a custom field has been populated on historic records already communicated it continues to be displayed after it is deleted. A custom field cannot be renamed once it has been used.

Custom field types 

The custom fields engine supports a number of different custom field types e.g. text box, multiple line text box, select box, multiple select box, check box, email, date, date and time and number, which has a corresponding value format and validation rules to help ensure data is kept clean.  

Custom field properties 

Furthermore, the properties on the custom fields can also be used to configure these fields through the System setting page. This allows the system owner to decide:-  

• What the fields name is and description i.e. its admin panel name, not the name displayed in the UI 
• Whether or not the field is active or not i.e. displayed or not in UI 
• Whether or not the field is filterable i.e. displayed in registers 
• Whether or not the field is mandatory i.e. the form can be saved or sent with or without this field populated
• Where the field is text box what the maximum character length is 
• Where the field is required in multiple languages, the text label in each language, is displayed in the UI. 

Please note:

• Field label and field name must be unique within a particular/page form
• The same field label and/or field name can be re-used on another form but please be mindful of the fact that if you use the same label on a form and its reply, you won't be able to differentiate between these in the register - e.g. if you were to add 'Closure Date' to a form and 'Closure Date' to the Reply then make them both filterable (i.e. displayed in register) then you would see two columns named 'Closure Date' and not be able to tell which is which).
• Special characters are not supported. 

Setting up a custom field on user profiles or company, contracts or projects 

To add a custom field for user profiles 

• Click the System Settings  icon then select  Custom fields. 

• Under Custom fields, select a Company. Custom fields are specific to a Company. This allows fields to be different across different companies. In the case of a Workflow or Contract the association to a particular company is based on the Project - i.e. each Workflow is associated with a Contract, each contract is associated with a Project and each Project is associated with a Company.  

• Select the Workflow, Contract profile, Company profile, Company User profile or Project profile resource type. In this walkthrough you select the Company User Profile 
• Add the new Field with add button. 

• Add the Field label, language, and additional language translation if multiple language support is required. 
• Set the properties for the custom field: 
  • Fields types – When selected, this defines field types e.g. text box, multiple line text box, select box, multiple select box, check box, email, date, date and time and number. This provides basic validation of the fields in the UI. 
  • Is Active - When selected, this field can be used on the user profiles. 
  • Name – This is name used in the admin panel for administration purposes and not the field label used in the UI. 
  • Description – This is a free text field used in the admin panel for administration purposes and not the field label used in the UI. 
  • Filterable - When selected, this field can be used as a filter in Registers to help manage users in the admin panel. 
  • Is Mandatory - When selected, this will force the user to populate these fields before the form or page can be saved. 
  • Max Length - When selected, this will limit the number of characters that can be added into text fields. 

• Where field type under the properties tab has been set to either select box, multiple select box, check box, under the Select options tab set the options for these dropdowns. Note that you can't change the order but dropdown options will always be displayed alphabetically on the page/form irrespective of the order you add them in.

• Click Save. The new custom field will be displayed on the Company User Profile page. This field is not shown on the user profile page or preference page. The user profile page with the new custom field can now be populate by admin who have the right to update user profile details. 

Setting up a custom field on workflows 

To add a custom field for workflows 

• Click the System Settings icon then select Custom fields. 

• Under Custom fields, select a Company. Custom fields are specific to a Company. This allows fields to be different across different companies. 

• Select the Workflow, Contract profile, Company profile, Company User profile or Project profile resource type. In this walkthrough you select the Early Warning Workflow, which presents each of the steps in this workflow
• Next add the new Field with add button to each of the workflow steps selected. 

• Add the Field label, language, and additional language translation if multiple language support is required. In this example we are adding a risk classification to the early warning 

Set the properties for the custom field: 

• • Fields types – When selected this defines field types e.g. text box, multiple line text box, select box, multiple select box, check box, email, date, date and time and number. This provides basic validation of the fields in the UI. 
  • Is Active - When selected, this field can be used on the user profiles. 
  • Name – This is the name used in the admin panel for administration purposes and not the field label used in the UI. 
  • Description – This is free text fields used in the admin panel for administration purposes and not the field label used in the UI. 
  • Filterable - When selected, this field can be used as a filter in Registers to help manage users in the admin panel. 
  • Is Mandatory - When selected, this will force the user to populate these fields before the form or page can be saved. 
  • Max Length - When selected, this will limit the number of characters that can be added into text fields. 

• Where field type under the properties tab has been set to either select box, multiple select box, check box, under the Select options tab set the options for these dropdowns. 

• Click  Save. The new custom field will be displayed on the Early Warning Workflows for all Built Intelligence contracts. This field is not shown on notices already communicated, only new early warnings. The user profile page with the new custom field can now be populated by contract users who have the right to draft and communicate early warnings. In this example we had added the custom field to both the PM Early Warning, Contractor Early Warning and Risk Reduction tab. 

Editing and deleting custom fields 

System Owner Admin users are able to edit custom fields. However, if a custom field has been used and populated with data, it cannot be changed to a different field type and its name cannot be changed. 

To edit a custom field 

1. Click the System Settings  icon then go to Custom Fields, then select the relevant Company, then click either Workflows, Contract, Company, Company User or Project. 

1. In your list of custom fields, click Edit for the fields you want to change. 

1. Update your custom field as needed, then click Save. 

You can also delete custom fields, but keep in mind that when you delete a custom field, you also delete all data that has been stored in that custom field. 

To delete a custom field 

1. In your list of custom fields, click the Trashcan icon for the fields you want to delete. 

1. You are prompted to confirm that you want to delete the field. Click Yes to delete the field.