Bespoke Fields & Screen Aliases: Overview

Custom field configuration and screen customization

Overview

Bespoke tabs and fields can be configured for you to store information that is particular to your business.

Bespoke fields can be added and edited in the patchQuote API.

Tabs

Three bespoke tabs are available:

Clients / Other
Quotes / Other
Contracts / Other

Each tab is named 'Other' by default and can be renamed to suit your needs.

Each tab can be enabled separately, so you can enable only the ones you want.

Each tab can be further configured by role to be hidden or display-only.

Fields

Within each tab, fields can be organised using headings in your desired sort order and can be presented with different characteristics: Text, Text Area, Numeric, Date, Checkbox, Label and Blank.

Each field can also be configured as hidden or display-only by role using role restriction settings.

Users can enter data as required in the bespoke fields. Like standard system fields, data entered or edited here are recorded using our standard Field Auditing feature.
There are some differences from the standard in how these records are managed and displayed in the Edit History screen.

The recorded data can be used in queries and scheduled jobs. By default, bespoke fields are not used in system calculations or any other system logic.

Set-up

Contact your Account Manager if you want to set-up bespoke tabs and fields. They will work with you to set-up the screens and fields you want.

Read through the following set-up details to understand how these screens and fields are set-up.

The original specification for this feature can be opened or downloaded here.

Tabs

Each tab is named 'Other' by default, but they can be renamed.

Clients / Other

The Clients / Other tab is hidden by default.

Internal roles can be given access by updating their Role Restriction bit-array entries.

No external roles are given access to this tab.

Quotes / Other

Set [gb_controls]quotes_bespoke_fields_screen_flag to 'yes' to give all internal roles access to Quotes / Other.

No external roles are given access to this tab.

Contracts / Other

Set [gb_controls]contracts_bespoke_fields_screen_flag to 'yes' to give all internal roles access to Contracts / Other. No external roles are given access to this tab.

Access to Bespoke Fields

Bespoke fields you have set-up are available to internal users by default. Visit Bespoke Role Restrictions for full details on how access to fields can be restricted.

Data Tables

[gb_bespoke_fields] - stores each bespoke field. The unique id is bespoke_field_id.
[gb_bespoke_listboxes] - if a [gb_bespoke_fields]input_type is 'listbox', this table stores each available option in the list.
1. [gb_bespoke_listboxes]bespoke_field_id joins each record to a [gb_bespoke_fields] record.
2. Visit Bespoke Listboxes to see sample data.
[gb_bespoke_field_values] stores the recorded value of each bespoke field for each client, quote or contract.
1. [gb_bespoke_field_values]bespoke_field_id joins this record to a [gb_bespoke_fields] record.
2. [gb_bespoke_field_values]record_id joins this record to an [fm_clients], [qt_quotes] or [fm_contracts] record.
3. If [gb_bespoke_fields]input_type is not 'listbox' then [gb_bespoke_field_values]value' is the recorded value for the field
4. If [gb_bespoke_fields]input_type is 'listbox' then [gb_bespoke_field_values]value' stores the selected [gb_bespoke_listboxes]bespoke_listbox_id of the chosen item in the list.

Data Review and Updates

Use Export Table Data to download and review the current bespoke field tables and records.

Use Import Table Data to upload any additions or revisions you want to make to the bespoke fields.

If you want to create and import a bulk update for client, quote or contract records where the field is a listbox
you will have to identify the required
and import this into the ' field of the records you are updating.

Field Names

The [gb_bespoke_fields]field_name field holds the field label as it will appear on screen unless it is further relabelled using Screen Aliases.

The preferred entry is in lower case with each word separated by an underscore.

Although other ways of entry will work, they can be difficult to work with in queries and scheduled reports and are not recommended and will not be able to be displayed on screen.

For a field_name to appear on screen it must meet these conditions:

All lowercase words
Words separated with an underscore
Numbers are acceptable

Below are examples of what will and won't work.

field_name	Screen display	Comments
insurance_per_year	Insurance Per Year	Only format that will display
insurance_per_Year		Will not display
sub-category		Will not display
Third Party Finance		Will not display
A mixture Of uppercase And Lowercase text		Will not display
An External contractenddate 04-2012		Will not display
m_l_a_date_04-2012		Will not display
m_l_a_date_04_2012	M L A Date 04 2012	Only format that will display

You may wish to hide certain fields from view on these screens. There are 2 ways of achieving this:

Use a non-compliant field_name
Use role restrictions. For assistance with this functionality contact your Catch-e Account Manager

Columns and Sort Order

Fields can be sorted in any order on the screens across 2 columns.

This is managed by entering the sort order required in the and fields.

The sort order of the screens is firstly by [gb_bespoke_fields]column_number, field_order, then bespoke_field_id.

Label Position

This determines the position of the label in context to the field itself. The label can be either to the 'left' of the field or 'above' it.

Default Values

A default value may be set using this field.

Data Entry Validation

A validation rule can be set for each bespoke field as required.

Enter the rule in , or leave blank if no validation is required.

Then enter a useful validation message for the field in [gb_bespoke_fields]validation_error_message. This will display in an alert box if the validation fails.

Note: Data validation will only occur when both ‘validation_regular_expression‘ and ‘validation_error_message‘ fields populated.

Warning: We suggest that your error message contains the Tab name and field name (as displayed on screen) in your error message. If you are editing another tab and the validation fails this will assist your users to identify which field requires attention. If you are editing fields on the 'Other' tab the cursor will be placed in the first field that needs attention.

Data validation rules are constructed using the Regular Expression data technique. Regular Expression can be described as a sequence of characters that form a search pattern.

The following table includes some of the most common regular expression patterns you are likely to use.

	Description
^[(A-Z)(a-z)]{0,77}$	Allows an empty field, Upper Case A-Z, Lower Case a-z, up to a maximum of 77 characters
^[(A-Z)(a-z)(0-9)]{0,88}$	Allows an empty field, Upper Case A-Z, Lower Case a-z, space and numeric 0-9, up to a maximum of 88 characters
^.{1,255}$	Allows any character, minimum 1 character, maximum 255 characters
^-?[0-9]\d*(.\d+)?$	Any positive or negative number (including decimals)
^[0-9]\d*(.\d+)?$	Any positive number (including decimals)
^[1-9][0-9]*$	Any positive whole number

Input Type

Nominate the required for each field. There are 8 options for input_type as described below.

input_type	Description
text	Will allow alpha, numeric and character text content
textarea	Will allow alpha, numeric and character text content
date	Will allow date content and will pop a date selector
checkbox	Checked = yes, unchecked = no
listbox	Will allow selection from a list of pre-populated content from [gb_bespoke_listboxes] for that bespoke_field_id
blank	Will insert a blank row on screen (used for aesthetics only)
number	Right justified numeric character entry
label	Used to contain the section heading label

Input Size

Determines the width of the text box in edit mode. Can be used only where Input Type = 'text'

Input Length

Determines the maximum number of characters of a text or number field in edit mode. This field is mandatory where Input Type = 'text' or 'number'.

Note: All bespoke fields are limited to a maximum size of 64kb

Input Rows

Determines the number of rows of the textarea box in display and edit mode. This is only used where Input Type = 'textarea'

Location

If a field_name is formatted correctly as outlined above it will be displayed on the 'Other' tab on either the Clients, Quotes or Contracts area depending on the data value of 'table_name' field.

Use in Quote Placeholders

Bespoke fields for Quotes and Clients are automatically created as quote placeholders if particular settings are in place.

Screen Aliases

Create a Screen Aliases record to rename a bespoke tab or field.

Add an entry into the table for your preferred field name.

The sample data below shows the three bespoke tabs and one field being renamed.

Sample Data

					screenaliasidmodulepagesub_pagefieldalias
Clients / Other
100002	fm	clients	Other		Aliasforclients
100003	fm	clients	Other	mladate04_2012	m.l.a. date 04-2012
Quotes / Other
100000	qt	quotes	Other		Aliasforquotes
Contracts / Other
100001	fm	contracts	Other		Aliasforcontracts

The alias field will allow up to 40 characters, but only a maximum of 14 characters will display. Longer names would disrupt screens at smaller resolutions.
A fieldname formatted correctly to allow it to appear on screen can be renamed using this table to appear on screen with an alternative label.E.g., The bespoke fieldname ‘mladate04_2012’ will appear on screen as ‘M L A Date 04 2012’ but could be renamed using as ‘m.l.a. date 04-2012’ as shown above.

Note: The Edit History screen displays as "Field".
We recommend that you use aliases for field names only when necessary and keep them similar to the field name so users can understand the Edit History better.

Edit History

When any fields in the bespoke tabs are edited an audit history record is written to the table.

stores the bespokefieldid rather than the actual character driven field name.

This accommodates future changes to the data. These changes would break in the link to fields.

The View Edit History screen will display the and and the respective field's Before and After values.

Encrypted Fields

Encrypted fields can be accessed using special syntax.

Example

To decrypt and report on the field you can use this:

SELECT AES_DECRYPT(income_gross, 'AES_CRYPT_CIPHER_KEY') AS income_grossFROM fm_driversWHERE driver_id = '100000';

This will only work when the query is run by the Scheduler or via a Web Service call. If you try and run this in Query Browser / Workbench it will return a 'null' value.