Create or edit a Record Definition

In this section:

Create a Record Definition

To create a record definition, and to define the fields go to, Dashboard > Records > Add new 

Edit a Record Definition

To edit a record definition, go to, Dashboard > Records > Select Record > click Edit Record Definition in the top right corner.  

OptionDescription

The left-hand side of the screen contains the information about the record definition itself and the right-hand side has details of the fields/schema.

Record Definition details

Record name

Required. Name for the record definition. 

IDRequired. A unique ID for the record definition used in the API. Once created this field cannot be modified.
Title field

When viewing the details of a record, the record definition ID is displayed by default.

To view the details of a record, go to Dashboard > Records > select from the list > select record.

You can customise this (view record details page) to display the contents of the title, subtitle or the tooltip field.

  • Title field and Subtitle field: The drop-down displays the fields created for the record definition. Select an option from the drop-down. 
  • Tooltip: Enter text in this field 
  • You must first add fields to your record definition to configure these fields 
  • You can either set the title field, subtitle field or the tooltip field
Subtitle field
Tooltip

Context

Context is useful both for setting permissions and for relating data generally. If you wish to display other relations between records directly, use a contextual view. 

  • Parent: Contextual parent of a record definition can be either:
    • A record definition: For instance, a record definition representing an electricity meter might have a parent of a house or a billing account
    • A user: For instance, a record definition representing an account could be contextually linked to the current user by email address
    • None: Some records represent the base of a graph or are not part of one
  • From Field: Displays a drop-down list of fields that exist for the current record. 
  • To Field: Displayed only when you select a record as a parent field. A context is created from the To field (of the current record) to the From field (of the selected parent record).

You must add fields to your record definition before configuring the source of context.

For example, you can set the Parent to Current User and the From Field to a field in your record that contains information that can identify the user (for example, email).


Permissions

Setting permissions for a record definition allows you to view or edit permissions after the initial save. If no permissions are set, a warning is displayed. We appreciate there are circumstances where it may be required to create a totally immutable record definition. For more information on permissions, see Permissions.

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

Adding permission

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

Read permissions

Edit/Write permissions

Adding read permission for a group allows you to:

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

Users who can view one or more fields within the record definition can load an expurgated version containing only whether they can write the field and its type and not what permissions other users have.

The edit permission for a group allows users of that group to alter the definition of the record definition type. 

  • 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.

Delete permission

If enabled, users with required permissions can delete records. 

Users must have permission to edit the record and fields, to be able to delete a record. For more information see Records.



Listing

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

  • by anyone who can read the records: Allow users who have write-permission on the record or record definition to control who can view the list of all records that exist in a record definition.
  • by nobody: Removes all listing permissions
  • only when the context matches the current user: Context is set using the field that identifies the user. Set the Parent to Current User and the From Field to a field in your record that contains information that can identify the user (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. 

History

Allows you to configure who can view the history of changes made to the record.

The following options are available:

  • by all users who can see the record: Allows users who have read-permission for the record to view the history of the record
  • when the user is a member of the group: Enter the name of the group in Group name field, to allow users in that group to view the history of the record
  • when the user is the specific user: Allows access only to the users (email address) specified in the User name field
  • when the username of the current user matches the field: Allows 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 true: Allows 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 on fields of type boolean. 

Click Save to save and apply the settings.

Audit Logging

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

Log reads can now be set on the Record and View definition pages by any user who has permission to write/edit the selected record type. By clicking on the Audit logging switch you can set when logs should be made for this record type (i.e when a user is reading a record or when a user is reading and listing records). 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 records: Select 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 record definition to be able to save it. An error is displayed if you click Save before defining fields for the record definition. 

Adding Fields 

Data is stored in the record in fields. Fields are a part of a record which contains a single piece of data for the record. You can create new fields or edit attributes of existing fields. 

The left-hand side of the screen contains information about the record definition itself, and the right-hand side contains information about the fields in the record. 

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. 

OptionDescription

Field details


Field Name

Required. Enter a name for the field.
Type

Required.

  • String: A set of characters that can contain plain text, numbers or characters. The maximum value is set to 32767 bytes.
  • File: Enables you to upload a file or other data blob. For example, .png or .pdf files. The maximum size for file upload is 5MB.
  • Integer: A whole number with no decimal points
  • Number: A whole number or a floating point number. Floating point numbers are numbers that contain floating decimal points. For example, 2.8, 0.026
  • Date: Date field which can be selected using a calendar widget. The value is stored internally as a UNIX timestamp.
  • Boolean: Displayed as a toggle button which allows users to set True or False value for the field. This option can be used for consent applications.
  • Reference:  A reference field stores a reference to the ID field of a record in another/same record definition. For example, when creating a record for an employee John Smith in record definition Employees, you can create a reference to a record ID John Smith in the record definition Benefits. The reference creates a link that allows the user to view all the data available for the record in Benefits. 

  • Select one: A pre-defined list of items from which the user can select one item. The Values option is displayed. Click Add to add a value in the New option field. You can add multiple values and click Save to save your changes. Click Delete to delete a value. 

  • Select multiple: Create a pre-defined list of items from which the user can select multiple items. The Values option is displayed. Click Add to add a value in the New option field. You can add multiple values and click Save to save your changes. Click Delete to delete a value.
  • Ensure that the user has the required permissions to both, the records and fields, else an error is reported when the user clicks on the link to the referenced field.
  • Fields of type Select one are mandatory. You must select one of the options, else an error is displayed when you save the record.
RequiredEnable the option to set the field as mandatory
Display in tables

Enable the option if you want to display the field when viewing record details in the table

Display column

Select the column in which the field should be displayed when creating/updating the record. The options are Left, Right, Bottom and None

Display orderSet the order in which the fields must be displayed in the column
Field encryption type

Select the encryption type to be applied to the field. All data is encrypted at rest using modern, secure AES technology. Sometimes, however, it is desirable to provide a further layer of security that cannot be decrypted without a fully validated transaction (that is, without the consent of the network as a whole) or to mark data as externally encrypted so it is not displayed in the UI. Restrictions apply to how granularly encrypted fields can be used for other purposes as the Gospel engine cannot understand the data contained therein so this is generally best kept for the most sensitive data such as PII.

The available options are:

  • Block: The field is encrypted at block level using AES.
    Restriction level: None
  • Externally: An external system has encrypted this field.
    Restriction level: Cannot display in UI. Cannot be used for relation.
  • Externally with hash: An external system has encrypted this field and a hash of the underlying data (potentially consistently salted) has been stored with it.
    Restriction level: Only exact match search possible. Cannot display in UI. Cannot be used for relation.
  • Field: A field key has been used to encrypt the data, managed by Gospel.
    Restriction level: Cannot be used for relation.
  • Field with hash: A field key has been used to encrypt the data, managed by Gospel and a salted consistently hash of the underlying data has been stored with it.
    Restriction level: Only exact match search possible.
  • One time: A unique key has been used to encrypt the data, managed by Gospel. This key can be deleted rendering the data irretrievable as it is only used once. 
    Restriction level: Cannot be used for relation.
Use index

Index Type: Indexing enables efficient retrieval of data in the database. Indexing enables you to store a small portion of the data in special data structures, which supports efficient and quick search results. For more information, see Indexing.

It is recommended that you enable indexing for:

  • Fields that are going to be searched
  • Fields that are used for contextual permissions
  • Fields that require field links and foreign key enabled

Indexing can be enabled for the following data types:

  • String, Select one
    • Basic: All values of the field are indexed. This enables you to perform a search for the complete string in the record. For example, if the value "England" is provided in a record, the complete string "England" is indexed.
    • Stemmed: A stem length for the string must be provided, and an index is created based on the stem of that word. Stem length is set in the Stemmed length (bytes*) field. For example, the stem for words "collaboration", "collaborated" and "collaborating" is collab. 
    • Unique: Unique indexing rejects duplicate values, thus preventing users from inserting the same value for more than one field in the record. For example, if the value "johnsmith@email.com" is used in the email field, if you create another field with the value "johnsmith@email.com", a duplicate value error is displayed when saving the record and the record is not saved.
    • Unique Stemmed:  Users are prevented from inserting the same stemmed value for more than one field in the record. Stem length is set in the Stemmed length (bytes*) field. For example, if the value "345-ACCNT-09" is used in a field Employee ID, if you create another field with the value "345", a duplicate value error is displayed when saving the record and the save action is rejected.
  • Date, Number and Integer: For numbers and integer field type, the data is saved in buckets and the constraint is applied based on the order of magnitude which is written as 10 to the nth power. For example, if you set the value of the field to 30, the data is saved in 3 buckets. 
    Date fields are converted to Unix timestamp in seconds.
Field Link 

This option is available only if indexing is enabled.

This field allows you to create a relationship between a field in the current (child) record to a field in another record (parent). When creating a record, the child record inherits the values from the parent record. For more information, see Field Link and Foreign Keys.

Record Name: The drop-down list displays the list of records. Select the parent record that contains the field.  

To Field: The drop-down displays the list of fields that exist for the record. Select the field name from the drop-down list.


Performance may be affected if the fields in both the parent and child records are not indexed.

Enforce Foreign Key

If enabled, before saving the record it verifies that the field exists in the parent table. Thus, ensuring foreign key integrity.

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

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 "identify users" to whom the permission is applied, and then, select "what" permission should be applied:

Identify users:

  • Allow a group of users to: Allows access to users that are a member of the group (Group name field)
  • Allow the logged in user to: Allows access only when the logged in user's username equals the value in the Field name 
  • Allow the contextual owner to: Context is set using the field that identifies the user. This property is set in the Context option, available in the left pane. 

    Using this option may be slower (sometimes substantially) than the other permission settings. Ensure that you use this setting only when required.

  • Allow a group of users conditionally to: Allows access to users that are a member of the Group name and when the set Field name matches the criteria. For example, users of group Finance can have access to the record if the value for field travel is set to true. Only boolean fields are displayed in the drop-down.
  • Apply matcher: Allows access only when all the matcher conditions are met.  A matching condition, for instance, "When the City (Field name) is equal to (predicate) London (Value)" can be set here. 
    • 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. 

What permissions:

  • read this field: Allows users to only view the field
  • write to this field: Allows users to write to the field
  • both read from and write to this field: Allows users to view and write to the field

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.