Create or edit View Definition

Create View Definition

To create a View Definition, go to, Dashboard > Views > Add new 

Edit View Definition

To edit a view definition, go to, Dashboard > Views > select View Definition > click Edit View Definition in the top right corner

View Definition details


View Details

These fields are displayed when the user creates a record.  

IDRequired. A unique ID for the view definition used in the API. Once created this field cannot be modified.
Base recordRequired. Select the base record.

Enter a tooltip that is displayed when viewing the details of the record.


Required. Joins enable you to join the "from/base" record to the "to" (base) record. It connects one or more records in order to provide a collated view of data. 

To relate between two tables requires you to determine the join condition. Click the  option to create a join condition. The following options display:

  • Join Field: Select the "from" field that exists in the parent record. The value defined in this field is used as the "from" record.
  • To: Select the "to" record 
  • Field: Select the field from the record, to which the values are mapped.
  • As: Enter a name to represent the new collated view of the data
  • Relation type: 
    • oneToOne: One-to-one relationships occur when there is exactly one record in the "from" record that corresponds to one record in the "to" record. 
    • oneToMany: A one-to-many relationship in a database occurs when each record in the "from" table may have many linked records in "to" table, but each record in "to" table may have only one corresponding record in "from" table. 
      • Include record when no match is found?: Displayed only when oneToMany join is created. When selected, it returns all records from the base record definition and the matching records from the joined record definition. If no matching records are found in the base table, NULL value is used.

Click Save to save your input.


Setting permissions for a view definition allows you to view or edit permissions after the initial save. If no permissions are set, a warning is displayed. For more information on permissions, see Permissions.

Ensure that you set the required permissions for a view definition before you save it. If you fail to do so, users (including the creator of the view definition) are not allowed to view or edit it configuration of the definition.

Adding permission

To add permissions click the button. The Add permissions box displays. Enter the name of the group and select the required permission settings:

Read permissions

Adding read permission for a group allows you to:

  • view the definitions of all of the fields in the view definition
  • view the permissions associated with those fields for auditing or editing purposes

Write permissions

The write permission for a group allows users of that group to alter the definition of the view type. 

  • In Gospel v5.0 it will be possible to require multiple approvals before a schema can be altered
  • From the API, it is also possible to specify a particular user rather than a group of users but this is not recommended.

Clickto delete permission settings.


Allows you to set listing permissions for the record. The following options are available:

  • by anyone who can read the records: Users who can have view permissions for the "from" and "to" record, can view the record definition.
  • by nobody: Removes all listing permissions
  • only when the context matches the current user: Users who match the context set for the record definition. For example, email.
  • only by users in the specified group: Click. The Add listing permissions box displays. Enter the name of the group in Group name field, and click Save to save your changes. 

Audit Logging

This allows you to set when logs for users actions like reading/listing a view definition should be generated. 

Log reads can now be set on the view definition pages by any user who has permission to write/edit the selected view definition type. By clicking on the Audit logging switch you can set when logs should be made for this view definition. To create the logging permissions select the table you would like to record, who made the read (Log actor to) and what fields they accessed. You can choose to monitor log reads by a specific user or all users. Please note that this is separate to the inherent logging as part of the blockchain and is designed to facilitate the use of history as part of access control or triggers.

  • Log table: The table (record definition) where you want the log to be saved.
  • Log actor to: The field where information about the user viewing and listing the record is saved.
  • Log fields accessed to: The field where information about changes to the fields is saved.  
  • Log when: Select what actions require logging of information. 
    • reading a record: Select if information should be saved only when a record is viewed.
    • reading or listing recordsSelect if information should be saved both when a record is viewed and listed.
  • Log reads for: Add additional setting for which users the log should be saved

The following options are available:
  • by all users who can see the recordAllows users who have read-permission on the record to view the details of the record.
  • when the user is a member of the groupEnter the name of the group in Group name field, to allow users in that group to view the details of the record.
  • when the user is the specific user: Allows access only to the user (email address) specified in the User name field.
  • when the username of the current user matches the field: Allows view access only if the username of the current user matches the value specified in the field name. The Field name drop-down displays only fields of type string. 
  • when the boolean field is trueAllows view access to users that belong to the group mentioned in the Group name and have the boolean set to true. The Field name drop-down displays only fields of type boolean.

You must create fields for the view definition to be able to save it. An error is displayed if you click Save before defining fields for the view definition. 

Defining fields 

Once you have created a record definition, make sure that you create fields.  To add a field, click on the Click to add a field option in the right-pane. 


Field details

Field Name

Required. The name for the field.
Display Column

Select the column in which the field should be displayed. The options are Left and Right.

In the Display Order field, you can also set the order in which the fields must be displayed. Select Display in tables if you want this field to be displayed when the records are listed.

TooltipThe tooltip is displayed when viewing the details of the field.
Display NameEnter an alternate display name

Field Type

Mapped field: This displays the information from a field within one of the record definitions making up the view.

Switch case: A switch field works down a series of matching expressions and returns a value specified, or if none is matched, a default value. For instance, we might set switch cases of record.fields.driversLicenceNumber ne "" → true, default → false for the field hasDriversLicence

Calculated field: A calculated field performs mathematical or string operations on one or more fields aggregated or unaggregated from the underlying data. For instance, we might sum orderLines.fields.amount and add it to record.fields.postage to derive the totalOrderValue field.

Map to

Record type: The drop-down displays the "base" and "where" record in the list.

Field: From the drop-down select a field either from the "from/base" table or from the "where" table to display its contents when the view is generated.

Tokenise values: The drop-down displays different hash functions. Select an option from the list or select Don't tokenise value if you do not want to encrypt the field value.

Security Context

Set an override minimum security score to view this data when it contextually matches one of the following:

  • Current user threshold: contextually match the current user
  • Base threshold score: does not contextually match the current user

Read Permissions

Separate permissions are required to read and write data. There are situations, especially in BPM workflows, where users may require only write access and no read access. 

Click thebutton. The Add permissions box displays.

On this screen, you have to first select to "who" the permission is applied, and then, select "what" permission should be applied:

  • Allow a group of users to: Allows access to users that are a member of the Group name field
  • Allow the logged in user to: Allows access only when the logged in user's username equals the value of the Field name 
  • Allow the contextual owner to: Allows access only when the user context matches the owner of the definition.
  • Allow a group of users conditionally to: Allows access to users that are a member of the Group name and the set Field name matches the criteria.
    • From: Select a field name from the drop-down. The list may display fields that are set to not be displayed in the record.

    • Predicate: You can use predicates like contains, is equal to, is not equal to, contains, does not contain, etc. to generate search results when the set conditions are met. 
    • Value:  Enter a value to match the predicate settings. Apply matcherA matching condition, for instance, "When the City (Field name) is equal to (predicate) London (Value)" can be set here. 

  • read this field: Allows users to only view the field
  • when the user is a member of the groupEnter the name of the group in Group name field, to allow users in that group to view the details of the record.

Click Save to save and apply the settings.

Copying and pasting permissions

Creating and applying complex permission can be time-consuming and therefore to simplify this, you can use the Copy/Paste option.

Once you have applied the required permission settings to a field, you can Copy the settings and apply to all other required field using the Paste option. 

Click Save to save your changes. Click Revert changes to undo the current changes and revert to the last saved version.