Elyse APPLICATION DOCUMENTATION

Introduction

What is Elyse

Elyse® is a high-integrity controlled document management system.

Key Concepts

Structure

A 'document' within a controlled document management system is an abstract entity to which files are related. For example, a given document will have multiple releases (versions or revisions). Each release will comprise one or more files, sometimes referred to as renditions. For example, there will typically be a source file (.docx, .dwg) and a published file (.pdf). Files are related to documents. The document identifier is not merely an item of metadata of the file, it is an entity which has an existence separate from the file. Documents can be thought of as the parent entity. Files can be stored within Elyse without being related to a document, however for controlled document management purposes documents are the primary point of reference.

Document Identifiers

An essential rule of controlled document management systems is that all documents must be uniquely identified. In Elyse this rule is rigorously enforced. An Elyse database has a single document ID register. It is not possible to create duplicate document identifiers within the same Elyse database.

Document identifiers in Elyse are stored exactly the same as what the user sees. There is no proxy or parallel document ID system. Any string of up to 50 characters, of any type, can be used as a document identifier. Hence legacy systems can be migrated to Elyse with the only constraint that each document ID must be unique.

Files

Elyse is designed with data fidelity, auditability and tamper resistance as primary criteria. These requirements are prioritized over other competing considerations. Once a file has been loaded into an Elyse database it cannot be modified. This provides a very high level of assurance in the integrity of file contents within the database. It also means that all collaborative editing of files must occur prior to the file being loaded into Elyse. If recording of fine grained editing history is required then the editing must be complete before the file with the embedded change tracking is loaded into Elyse.

Files are stored within an SQL Server FILESTREAM container. The database is configured such that the files are only accessible via the database.

Filtering

Elyse applies two methods to automatically filter lists of documents and files: permission filtering and filter group filtering.

Permission filtering ensures that restricted documents and associated files are only visible to appropriately authorized users.

Filter groups automatically filter documents and files according to pre-configured metadata criteria. For example, filter group filtering is used to ensure that users without any additional privileges can only view the current latest release of documents and not superseded releases.

If you are searching for a document or file which you know is in the database but which you cannot find then it is likely that it is being filtered out of search results by permission filtering or filter group filtering. If a search is made by an exact identifier then the response will not distinguish between whether it does not exist or it does exist but is filtered out by filtering. This ambiguity is intentional for security reasons.

User Interface Basics

Navigation Bar Menus

The navigation bar is the grey bar at the top of the window. Text with a ▼ symbol after it is a menu. Click on the ▼ symbol to open the menu. A ▶ symbol indicates a submenu.

Multi-Selecting Table Rows

A single row may be selected by left clicking on the row. A contiguous set of rows can be selected by left clicking the first row and then holding a Shift key down while left clicking the second row. A non-contiguous set of rows can be selected by left clicking the first row and then holding a Ctrl key down while left clicking other rows.

Context Menus

Most tables are configured with context menus. Context menus apply to table rows. Right clicking after selecting one or more rows on a table will open a context menu if it is available. The visibility of a context menu is determined by: the number of rows selected (one or more than one), the user roles which have been selected, and the table which has been displayed.

Popup Forms

Many commands load a popup form. Popup forms contain one or more data fields. If a field has a ▶ symbol next to it then this will open a menu. For example, often there will be various ways of progressively finding the required data to populate a field.

Command Palette

The ⌘ symbol is the Command Palette.

Downloading Table Data

When a table is displayed, the table data can be downloaded to an Excel file by selecting the ⤓ symbol near the right hand end of the navigation menu.

User Interface Customization

A system administrator can customize the navigation bar menus, context menus, popup forms, Command Palette and this help file by editing the configuration files in the deployed frontend / assets folder, following the instructions under the frontend / specs folder.

Onboarding

Elyse Access Control System

Elyse has a multi-layered and fine-grained privilege system. All privileges beyond connecting to the database are managed within the Elyse database. There are essentially two types of privileges.

Role based privileges grant a user rights to execute specific commands (stored procedures within the database). If a user attempts to execute a command but does not have the appropriate role privilege mapped within the database then the command will exit without executing.

Data-level privileges grant access to privileged data, or performing actions on privileged data. These privileges must be granted separately from role-based privileges. For example, a user may have Editor level privileges but only for a particular group of documents. When a command is executed to perform a particular task the database will first check if that user has the required privileges for that specific data.

The Security Identifier

Elyse leverages Windows Integrated Security. All authentication checks are made against the Windows security identifier (SID) of the connected user. When Elyse carries out an authentication the database will directly query the security context to establish the identity of the user, which is the Windows account which the user is logged in to. This is checked against a copy of the user's SID stored in access control lists within the database. Hence before any privileges can be granted, your SID must first be registered in the database. This is via a process called self-onboarding described below.

Note that if your Windows account is deleted and you are later given a new account then the SID will be different, even if the new account name is exactly the same.

Self-Onboarding

If you need to request privileges beyond unprivileged access then you must first register your SID in the database. This can only be done from your Windows account via Elyse. It cannot be performed by anyone else from a different account.

On the grey navigation bar at the top of the window, select Connected User > Self Onboard. A message dialog will indicate either that the command was successful or that the user is already registered. The command Connected User > Who Is This? can also be used to confirm the security context account which the database sees. The username is at the right of the message label box returned.

Note that self-onboarding merely adds your SID to a list in the database. It does not have any functional impact until specific privileges are granted. Also, privileges cannot be granted to you until your SID has been onboarded.

Privilege Requests

After self-onboarding you must contact a user with Authorizer level privileges to request the required role-based privilege. Further data-level privileges can then be granted either by an Authorizer or Controller depending on the particular privilege type. For example, viewing access to a restricted group of documents may be granted by an Authorizer by adding you to the associated document group, or metadata editing rights for a group of files may be granted by a Controller by adding you to a file edit group.

Role Selection

The visibility of Command Palette results, navigation bar menus and context menus are controlled according to active user roles. Clicking the Select Roles button on the left of the navigation bar at the top of the window will open a dialog listing Elyse roles for which you have been authorised. Select or deselect roles according to how you want the interface to appear. For example, if you have Controller level role privileges but for the current session you want to simplify the interface for carrying out read-only tasks then deselecting the Controller role will automatically hide all Controller level menus and commands.

Note that this role selection only affects the user interface and has no impact on actual database privileges. For example, if a URL for a particular command is saved and later retrieved then it will still function regardless of the role selection.

Basic Searching

Basic Search Menu

The navigation bar is the grey bar at the top of the window. Near the left is a menu Basic Search. Click on that menu to reveal basic search options.

Doc ID Equals

Search for an exact match of the document ID. Document IDs are not case sensitive.

Doc ID Contains

List documents IDs which contain the given string.

Doc Title Contains

List documents where the title contains the given string.

Docs by List Attribute

List documents according to an attribute selected from a single-select (radio button) list.

Docs by Tag

List documents which are linked to a given tag. See Introduction to Tags below.

Filename Contains

List files where the filename contains the given string.

File Content Search

List files which contain the given string.

Note that file content searching is dependent on file content indexing configuration. If Store Plain Text Content was not enabled at the time when a file was loaded then file content searching will not be possible. See Information > Global Settings to check if this feature is enabled. The feature can only be enabled by a Database Administrator.

File By File ID

Each file is assigned a unique integer file ID. If you know the ID of a file then enter the number directly. The complete number must be entered.

Files by List Attribute

List files according to an attribute selected from a single-select (radio button) list.

Filtering

If you are searching for a document or file which you know is in the database but which you cannot find then it is likely that it is being filtered out of search results by permission filtering or filter group filtering. If a search is made by an exact identifier then the response will not distinguish between whether it does not exist or it does exist but is filtered out by filtering. This ambiguity is intentional for security reasons.

Files Linked to Documents

Document IDs are displayed with a hyperlink. Clicking on the hyperlink will list any files linked to that document which pass the default filter, that is they are current latest release and in the published format.

Result Tables

Tables displaying lists of documents or files have column tooltips. Hover over a column heading to see a longer description of the column. For example, the column DBS has a tooltip of Document Booking Status.

Clicking on a column heading will sort the table according to that column.

Tables can be exported to Excel by selecting the download icon (green down arrow) near the right hand end of the navigation bar.

The columns that are presented in a document or file results table are determined by the form. If no form is specified then the default form registered in the Global Settings table will be used. A user with Controller privileges can create any number of different forms for different purposes.

Command Palette

For more advanced search commands use the Command Palette.

Advanced Searching

Introduction

This section covers searching for documents and files at access levels other than the unprivileged user.

Note that documents are not the same as files. Documents are an abstract entity that is used to relate files together, such as different releases or different renditions or format. Documents have a parent-child relationship with files. A search for documents is distinct from a search for files.

There are many different commands which return a list of documents or files. Below is a description of the overall structure of the system.

Search Structure

A document or file search comprises three elements:

A single search criterion consists of a metadata field, an operator, and one or more values. For example: Release date between date x and date y.

Permission filtering is automatically applied to filter out documents which the connected user does not have viewing rights to.

Filter group filtering applies a customizable filter.

This structure allows a high degree of flexibility in how searches return data. However it is important that the underlying search structure be kept in mind when performing searches. For example, with the default configuration, if a document ID has been newly created and has been assigned a publication status of Reserved, or no publication status has been assigned, then it will appear in a search of Recently Created Documents but it will be filtered out in a search of Document ID Contains because the Document ID Contains command will only display documents which have a publication status of Current.

Filter Group Filtering

Some document and file search functions apply a mandatory filter group and some do not. Whether or not a command applies a filter group will be indicated in the description of the command. All search functions which are accessible to unprivileged users apply a mandatory filter group. If no filter group is selected then a default filter group will be used. Elyse ships with a default filter group configured which lists only documents which are currently published (as opposed to superseded or cancelled for example) and only files which are the current latest release and in the published format.

Filter groups are configurable at Configurator role level. Any number of filter groups can be created.

Permission Filtering

The visibility of documents and files are determined by document groups. Permission filtering is flat and exclusive. Permissions are not inherited by a hierarchical folder type structure. This reduces the risk of sensitive documents being inadvertently exposed to unauthorized users. Users who are members of a given document group can view documents, and files linked to those documents, within the document group. Users who are not members of the group cannot view listings of those documents or files.

Permissions are unrelated to access roles. For example, a user with Authorizer privileges can grant a user membership of a document group but they cannot self-authorize membership of the group and will not be able to view documents or files within a group unless another Authorizer has granted them membership.

Permission filtering is applied to every document or file search.

Search Criteria

To view a list of all of the search functions, open the Command Palette and type Select into the Actions field. To refine the list for document-related searches for example, enter Documents into the Objects field.

The following data types are available for document and file metadata:

Radio buttons are lists where the members of the list are mutually exclusive and only one item can be selected from the list at a time.

Multi-select lists are non-exclusive lists where more than one item can be selected at a time.

Common object type metadata can be either radio button lists or multi-select lists. An example of a common object list name might be Contributing Organizations. The common object might be XYZ Co. Common objects can also be linked to attributes, such as Organization Name. XYZ Co could be linked to either a document or a file through a multi-select list.

Cross references allow cross referencing between documents. Cross references are grouped by cross reference type.

For each of the above metadata types, any number of custom fields can be created via the Configurator level role.

A document or file can be linked to any number of the above types of metadata attributes. For example, a document can be linked to more than one radio button attribute, providing each is from a different list.

Document IDs and also files each have a number of one-to-one metadata fields. Each document ID has an associated lock status (explained below). Each document ID record also includes a record of when it was created and by whom. Each file record has an associated filename, file size, an optional retention date and also a content hash. The content hash is an SHA-256 hash of the content which is used for detecting duplicate files. Each file record also includes a record of when it was created and by whom.

The intent of the document ID lock status is to permit a document ID to be locked against change. A document ID can be locked by a Controller but can only be unlocked by a Configurator. For example, once a document has been published and many other documents contain cross references to it via its document ID, the document ID should not be able to be changed.

Both documents and files can also be linked to a Transaction Group table. This allows an otherwise random unrelated group of files for example to be grouped by a single identifier. For example, if a batch of files are uploaded as a single group there may be a need to retrieve the group as a set later. One document can only be linked to a single transaction group and one file can only be linked to a single transaction group.

The Command Palette

Across all the user roles Elyse has around 900 different commands. Many of these commands can be further divided into different customized forms to suit user interface needs. Rather than drilling down through hierarchical dropdown menus, the Command Palette allows commands to be easily found directly.

Open the Command Palette by clicking the ⌘ symbol near the right hand end of the grey navigation bar.

Start typing an action into the Actions field, e.g. sel. When the desired word, i.e. Select, is at the top of the popup list press Enter. To move to the Objects field press Tab. Select an object, such as document or file. The Fields field is used to select a field, e.g. Title. Then tab down or click on the desired command. The Fields field automatically maps field names (e.g. Title) to field types (e.g. Document Free Text) and then maps the field type to the related commands.

The Command Palette will display a list which is ordered according to scoring against the words entered. For example, if Select, Document and Title are entered then commands which match all three will be at the top of the list. These will be followed by commands which match two or one of the words.

To add a command to your favorites list select the star at the left.

Select the Name/Description Search button to search directly by command name and description.

Commands will only be displayed which are applicable according to the roles available and selected for the connected user.

Creating Document IDs

Document IDs can be created in one of three ways.

If a document ID is entered then that is the document ID that will be created, providing that a duplicate does not already exist.

The User Auto-Gen Doc ID On Null setting in Global Settings switches the creation process to automatically generate a document ID if a document ID has not been entered. The Doc ID Format setting in Global Settings determines if the automatically generated ID is either an alpha string or an integer. The column can contain Alpha, Integer or NULL. If the auto-generate format is integer then the procedure will read the value from Doc ID Last Integer value in Global Settings, add 1 to it, and assign the value to the document ID. If the format is not Integer then the procedure will generate a document ID as a random string of letters of length determined by the Auto-Gen Doc ID Length setting in Global Settings.

A register code prefix can be automatically applied to an auto-generated document ID. The purpose of the register code is to distinguish between different registers that might otherwise have overlapping document IDs. Globally Unique Identifiers (GUIDs) are too long to be useful for human use. A company could use its stock ticker as the register code for example, or a short random string of letters. Then if two companies merge, the registers can be combined without clashing document IDs. A register code could also be used by a large organisation that wants to allow different sections of the same organisation to independently manage separate registers but without the document IDs clashing. The register code is enabled by the Is Register Code Applied setting in Global Settings. When a document ID is auto-generated the register code contained in the Register Code field will be pre-pended to the document ID, separated by a dash.

With the exception of Date Style, Global Settings can only be altered by a Database Administrator.

Loading Files

Overview

Files can be loaded into Elyse by users with Reviewer, Editor or Controller role privileges.

In the Command Palette, enter Upload into the Actions field to display a list of commands for loading files.

Upload Files With Data

The Upload Files With Data command allows multiple files to be loaded into Elyse and linked to a basic set of metadata.

Click the arrow next to the Document ID field to open a menu. Select Docs With Edit Permission. From the list that appears, select the document ID that you want to link the file to. This field is optional. If the file must have viewing restrictions applied then it must be linked to a document ID with viewing restrictions. Otherwise the file will be visible to all users other than unprivileged users. Selecting a document ID which has viewing restrictions will ensure that the file is immediately restricted and can only be viewed by authorized users.

The next field is Editing Rights Document Groups. This is optional. A selection from this list will link the document ID to the selected document edit group. Document group edit permission grants an Editor role user permission to edit metadata associated with a document which is a member of a document edit group. This action will not grant metadata edit permission which does not already exist, but will add the document to another group that the user has rights to.

Selecting an option from the File Group dropdown will link the file to a file group. File group edit permission grants an Editor role permission to edit metadata associated with a file which is within a file group which the user is linked to. If an Editor uploads a file but does not assign a File Group then only a Controller will be able to edit metadata for the file.

If Enforced Retention in Global Settings is On and a retention date has been set against a file then the file will not be able to be deleted until the retention date has passed. If Enforced Retention is Off then the retention date will be stored but will not be enforced. Selecting a fixed retention period will set a retention date. Note that once a file retention date has been set there is no user facility to change the date. Also, a retention period can only be set when a file is uploaded. When Enforced Retention is on, a restricted file can only be deleted by a Database Administrator. Alternatively, a new copy of the file can be re-loaded with a new retention date and the metadata re-linked to the new file. Note that Elyse is shipped with Enforced Retention set to Off. If Enforced Retention is required then the setting must be changed by a Database Administrator.

If Duplicate Check is set to On then Elyse will check each file to see if there is a matching file already in the database and reject it if there is. The check is performed against the binary file content, not the filename. If Duplicate Check in the form is not set then the Duplicate Management setting in Global Settings will be applied. Otherwise the Duplicate Check field in the form will take precedence. If a duplicate check is performed, a document ID has been supplied, and a single existing matching file is found, then the additional file will not be loaded but the file to document ID link will be created using the existing matching file and the file to file group link will be created. In all other cases if there is at least one matching file found then the transaction will be rejected.

Select one or more files. A table will be displayed with the file upload results.

Upload Files

Files can be uploaded without metadata, using the Upload Files function. However the metadata of the files will then not be editable by the Editor role level user. Attempts to edit metadata by an Editor role level user will result in an error message being returned from the database.

Upload File and Edit

The Upload File and Edit command can be used to select a single file and then immediately edit the associated metadata via an edit form.

Size Limits

The maximum permissible file size is 2GB.

Indexing of text content will be truncated to 1 million characters.

Document Release Management

A document can comprise a series of releases. A release has an associated Release Type, e.g. Revision, or Version, and a Release Identifier. Elyse allows for releases to be identified by any text string. For example, a release series might be: A, B, C, 0, 1, 2, 3. Or it might be 1, 1A, 1B, 2, 2A, 3. For a given document ID a release identifier must be unique.

A release identifier creates a link between files and a document. Each release can have any number of files linked to that release, for example a source file and a published rendition file. The source may also comprise a set of files of different formats for example. One file can be linked to only one release identifier, which in turn can be linked to only one document. A release identifier must be created and linked to a document before it can be linked to a file.

Separately from a release identifier link, a file may be directly linked to more than one document. However the document that is linked via a release identifier is given special treatment. This is the document that is displayed in file lists. When a file is linked to a release identifier, if the document linked to the release identifier is not already linked to the file then a direct link will be automatically created at the same time. Similarly, the direct link between a document and a file cannot be deleted if the file and document are also linked via a release identifier.

Note that the visibility of files and documents is controlled via customizable filter group filters linked to metadata list fields such as File Status. Release identifiers do not control visibility or metadata edit permissions. The Elyse database layer does not, for example, control which release is the current release. This means that a document release can be rolled back by changing the status metadata of files without interfering with the list of document release identifiers or copying any files. The design also allows for a release to comprise more than just a source file and a corresponding published rendition file. As a general operational rule there should only be a single file which is both the current latest release and also the published format rendition, as the master file. All other linked files are support files. However Elyse does not enforce this rule because the published document may comprise a PDF plus an associated data spreadsheet for example.

For a list of all release-related commands, enter Release into the Fields field of the Command Palette.

To create a document release, perform the following.

  1. Locate the document ID.
  2. Create a new release identifier for the document ID.
  3. Link the file to the release identifier.
  4. If the file is to be released as the current latest release, then change the File Status to Current and, if it is the published format file, change the Format to Distribution File. Change the status of the superseded files to Superseded.

If the Release Lock setting in global settings is set to On then updating and deleting of release-related records will be blocked. This setting can only be changed by a database administrator. Release Lock should only be set to On when these records are automatically created by the application layer rather than manually by the user.

File Viewing Rights

A user has permission to view a file if one of the following conditions are met:

  1. The file is not linked to any document, or
  2. The file is linked to a document and the document is not linked to any document viewer group, or
  3. The file is linked to a document and the document is linked to one or more document viewer groups but no group is linked to a SID, or
  4. The file is linked to a document and the document is linked to one or more document viewer groups linked to a SID which is linked to the user.

Hence a file can only have restricted viewing applied if it has been linked to a document ID.

A given document can be linked to multiple files. One file can be linked to multiple documents.

If a file is linked to a document which is restricted and is also linked to another document which is not restricted, then listing the files for the unrestricted document will not list the file unless the user has viewing permission for it.

Forms

Overview

All metadata for documents and files can only be presented via a form definition, with the exception of document details and file details tables which list all the metadata for a single document or file respectively. Document and file metadata editing pages also use forms to determine what fields will be displayed. Hence the set of metadata which is presented for editing will depend on which form has been selected. Form fields are user configurable by creating a link between a form ID and a metadata field.

How Forms Work

Forms can only be created by Controllers and Configurators. Any number of forms can be created. One form can contain a mixture of both document links and file links.

The Default Form ID listed in Global Settings will be applied if no form is specified when listing documents or files or opening a metadata editing form.

The following field types can be linked to documents.

The following field types can be linked to files.

Form Groups

A form can be linked to a form group. A Configurator can create or modify any form, including forms which are not linked to any form group. Controllers are granted permission to be form group owners by an Authorizer. A user who is a Controller and also a form group owner will be able to create and modify forms which are linked to a form group which they are an owner of. A user can be granted permission as a form owner but if they are not also a Controller then they will not be able to modify a form belonging to that form group. A Controller can also create and modify forms which are not linked to any form group. If a Configurator creates a form which is linked to a form group which in turn is not linked to any Controllers then only a Configurator will be able to modify a form linked to that form group.

Elyse Metadata Basics

Metadata Fields

Elyse uses an extensible attribute system. Any number of additional fields can be created by users with Configurator-level role privileges.

Metadata fields comprise either Open-Input Fields or Entity-Reference Fields.

Open-input fields allow users to manually enter a literal value. Each open-input field must have a field name, e.g. Title. Open-input fields are related to either documents or files, and when linked to the document or file object they are bound directly as a value-based link. Open-input fields may be created from one of the following data types.

The name of a field for a given data type and object type must be unique.

Integer and real number metadata fields can also be linked to a Units of Measure field.

Entity-reference fields present a predefined list of options. Instead of storing a value, these fields link directly to the unique ID of the list member, creating a relational link. The name of the list member will only ever exist in one place. So if the list member name is changed then the change will appear universally.

Entity-reference fields comprise the following types.

Radio button lists are lists from which only one member can be selected at a time. For example, a document cannot be both current and cancelled at the same time. Multi-select lists allow more than one member to be selected from the list. For example, a document may be both a form and also a guide.

Entity-reference fields fall into the following categories.

Document-related entity-reference fields can only be linked to documents, and file-related only related to files, whereas common object type entity-reference fields may be linked to either documents or files.

Pre-Configured Fields

Elyse is pre-configured with a number of metadata fields.

Document Free Text Fields

Document Integer

Document Date

Document Radio Button Lists

File Radio Button Lists

File Date

File Free Text

Special Metadata Fields

Some metadata fields have specific special purposes.

Other metadata fields are related to fixed attributes of objects.

Transaction groups are used to group any arbitrary group of documents or files so that the same list can be retrieved later. For example if a group of files is loaded into Elyse then every file in the group can be assigned the same transaction group.

Booking management data is used to control booking documents out and in.

Document ID lock status indicates if a document ID has been locked so that it cannot be altered without elevated privileges.

Audit data is automatically stored against various records. This includes when the record was created and by whom.

File content hash is an SHA256 hash of the content of a file. This is used for duplicate management. If duplicate management is enabled then Elyse will prevent loading of duplicate files.

Documents can also be grouped into document groups and files grouped into file groups. Document groups are used as part of permission filtering to restrict access to documents and associated files to authorized users. File groups are used for managing rights to edit the metadata of files.

How Metadata is Used

Metadata is generally used for sorting, grouping and controlling objects. This is distinct from tags which are generally used to describe and locate objects. An analogy is that metadata is like the table of contents at the front of a book while tags are like an index at the back of the book.

Introduction to Elyse Tags

Fundamentals

In Elyse, the primary objects are documents. Tags can be used for finding documents.

In the Command Palette, enter Tags into the Fields field to display a list of all the available commands relating to tags. Select All Tags for example to display a list of all available tags. Select a row, then right click and select Documents By Tag. This will display any documents which are linked to that tag.

Tag Relationship Trees

Elyse uses a system called Tag Relationship Trees to define hierarchical relationships between tags. For example, nuts and bolts are both fasteners. A tag relationship tree can be used to create parent-child relationships to reflect this. Hence if a document has the tag 'bolts' linked to it and a search is made using the tag 'fasteners' then the document with the tag 'bolts' will be returned, even though it does not have the tag 'fasteners' linked to it. The database knows that bolts are fasteners.

In the Command Palette find the command Tag Relationship Tree Names to display a list of tag relationship trees. Select a row, then right click and select Tag Tree Details to display a table representing the tree.

Tag Browsing Trees

Tag Browsing Trees are a type of cascading saved searches. Each node on the browsing tree represents a logical AND of the tag at that node and all of the ancestors above the node. Unlike relationship trees, browsing trees don't impact the function of a tag.

In the Command Palette find the command Tag Browsing Tree Names to display a list of tag browsing trees. Select a row, then right click and select Browsing Tree Details. This will display a table representing the browsing tree. Select a row, then right click and select Documents By Browsing Tree Node.

Tag Management

Purpose of Tags

Document tags are used primarily for sorting, grouping and finding documents. They are used like an index usually found at the back of a book, as opposed to a table of contents and publication details found at the front of a book. Tags differ from other types of metadata fields in that they are intended to be flexible as opposed to rigidly fixed, and are potentially large in number. Tags are also useful for categorizing attributes which may not be contained within the document itself, such as for non-text-based documents such as drawings and images. An Elyse database contains a central register of tag names.

Tag Relationship Trees

Tags can be arranged in a taxonomical hierarchical tree, referred to as a Tag Relationship Structure (TRS), or tag tree. In the TRS a reference to a tag automatically refers to any descendant tags in the way that reference to 'fasteners' inherently includes reference to both bolts and nuts for example. This means that a document tagged only with the tag 'bolts' can be retrieved with a search of the tag 'fasteners' if the TRS includes the parent-child relationship between fasteners and bolts to indicate that bolts are fasteners. The TRS represents a Boolean logic OR combination of a given tag and all of its descendants.

Tag Browsing Trees

A type of tree separate from the TRS, referred to as a browsing tree, represents a logical AND of the tag at that node and all of the ancestors above the node. This allows a user to construct a structure through which a progressively narrower search is conducted by progressing down the tree. Unlike a TRS, browsing trees don't impact the function of a tag. They comprise what may be considered a structure of saved searches. Each node on the tree is like a saved search. A node in a browsing tree can also be inverted such that documents with the tag at that node, and any of its descendants in the TRS, will be excluded. This is a logical NOT. Hence when used in combination with tags arranged in a TRS, a browsing tree node can construct any Boolean logic combination of tags.

Searching Using Tags

Tags are only linked to documents, not files. When conducting a search of documents by tag, a single TRS may be specified. If a TRS is not supplied then the default from the Global Settings table will be used. Use of TRS can be turned off by setting the Tag Descendants field to OFF. In the Command Palette enter Select into the Actions field and Tags into the Fields field to display a list of applicable commands.

The following are the types of tag-related permissions:

With one exception, tag-related permissions are managed via Duty Function Lists. Hence, for each permission type there is a table linking to function lists. Authentication of a permission is established if there is a path through to the connected user. The exception to the function list is a personal browsing tree that can only be linked to one Reader user.

Permissions to link tags to tag groups, edit tag trees and edit tag browsing trees can be created or modified by any Controller. Permissions to link tags to documents can be created or modified by any Controller who has viewing rights for the given document group.

Permission to link a tag to a document is determined by the metadata editing restrictions of the document.

Document editing is restricted by default. There are two ways in which an Editor role can gain editing permission for a document. If a Controller adds a user with Editor role permissions to the membership of a duty function list which is linked through to a document group then the user will have editing permission for any document within that group. A user with editing role permission can also create a document ID and specify a document editing group for which they already have editing permission. When the document ID is created it will be automatically linked to that document group. The user can therefore be given a sandbox within which they can create documents and then edit the metadata for the document they have created.

Creating and Editing Tags

Tags can be created by any user who has either Controller or Editor role.

A user has permission to edit a tag if either there is no chain from a tag through a tag group through to any user, or if the tag is linked to a tag group that the user has rights to. Controllers have rights to edit any tag by default.

Hence, if an Editor creates a tag then at that point the tag can be edited or deleted by any other Editor. The Editor can then link the tag to a tag group that they have rights to. From that point on only Editors who have rights to the given tag group can edit the tag. Any Controller can link the tag to any other tag group and hence grant editing rights for the tag to a different Editor who does not have rights to the first tag group. A tag may only be linked to a tag group if the connected user has both edit rights to the tag and also rights to the tag group.

Tag Groups

Tag groups are used to segment the management of tags. For example, a business section may have their own tag group that they manage. Tag groups can only be created by Controllers. A user has permission for a tag group if there is a chain from the tag group through either a function list or a people list to a user ID. Controllers have rights to any tag group by default.

Permission to Edit a Tag Relationship Tree or Tag Browsing Tree

Tag trees can be linked to duty function lists and people lists. Only members of the associated lists can edit a tag tree.

A user has permission for a tag tree if there is a chain from the tag tree ID through either a function list or a people list to a user ID. Controllers have rights to edit any tag tree by default.

Only a Controller may create a new TRS. But once created, the TRS nodes can be edited by anyone who has been granted edit permission for that tag tree. To add a tag to a tag tree the user must also have edit rights for the given tag. This is because even though the tag itself isn't being changed, the function of the tag is being changed.

Tag browsing tree permissions grant a user permission to modify a given tag browsing tree. The editing permissions for browsing trees are managed in the same way as for tag trees by linking through to duty function lists and people lists, with the following additional permissions. All Controllers may edit any tag browsing tree. If a user is linked directly to a tag browsing tree then they may edit the tag browsing tree.

A user with Reader role privileges can have one or more tag browsing trees that are linked directly to the user. The user can create and edit a personal tag browsing tree. A Controller can edit and delete another user's personal tag browsing tree.

Filter Groups

Filter groups are groups of metadata fields that are used to automatically filter results. For example, when retrieving a list of documents the application may need to display data according to the following rules.

  1. Only list document IDs which have a Document Status of Published, as opposed to Reserved or Superseded for example.
  2. Only list files linked to a given document ID which have a File Status of Current Latest Release, as opposed to Superseded for example, and also have a File Format of Distribution Format, as opposed to Source File for example.

By creating a filter group with Document Status equals Published, File Status equals Current Latest Revision and File Format equals Distribution Format, results can be retrieved which comply with the above rules. When a new release of a document is issued the file status of the old release must be changed to Superseded and the File Status of the new file must be set to Current Latest Release. The filter group then automatically ensures that users are only presented with the current latest release. Source files can be stored in the same database but retrievable via a channel which is separate from that which returns the distribution format files. Superseded files also remain in the same database and are also retrievable only via a channel which is separate from that which returns the current latest release. A Controller must ensure that the metadata is correct and consistent, but the filter group will take care of how the data is presented.

Filter groups can also be used for other purposes such as providing easy access to pre-filtered lists, such as a list of department-specific documents.

Of the various commands which retrieve document and file data, some apply a filter group and some do not, depending on the context. Whether or not a command applies a filter group will be indicated in the description of the command.

The Global Settings has a default filter group. This is used for the filter group which will filter documents and files to only present those which are current. Hence the application is configured such that search forms for unprivileged users do not have an option to select an alternative filter group. To select alternative filters, or execute commands that provide unfiltered lists, requires explicit role privileges to be granted.

Pre-Configured Default Filter Group

Elyse is shipped with one pre-configured filter group: Published. This filter group has three rules:

This filter group is registered as the default filter group. Hence any search for documents or files which is not an unfiltered list and which does not have a different filter group specified will default to filtering the results according to these rules.

Booking Management

An Editor or Controller can book out any document which they have edit permission for and which has not already been booked out.

An Editor can book in any document they have booked out and still have edit permission rights to. A Controller can book in any document for which they have edit permission rights and which is currently booked out.

When a document is booked in, a single file can be linked to the book in record in the same transaction. Additional files can be linked to the same booking transaction record, providing it is still the most recent record for that document. Adding additional files to a book-in record must be completed within the time from when the document was booked in, as set by the Booking In Time Box setting in Global Settings. (The default is 3 days.)

A booked-in transaction can be deleted by the person who created it, providing that it is within the booking in time box set in Global Settings, plus the following constraints. The booking transaction must be the most recent booking ID for that user for that document and it must be a booked-in record. If the booking transaction ID is still that which is against the document ID then the booking status is reverted to the previous booked-out ID. Otherwise, if the booking transaction ID against the document ID does not match the one being deleted then the document ID booking record field remains unchanged.

When a document is booked out, a comment can be added to the transaction.

When a document is booked in, a comment can be added, plus also a release number. The database is designed on the premise that a document Controller must manually carry out QA checks to ensure a document file is in order and has been properly authorized before being released as a published document. The database does not automatically process and release files to published document status. Note also that files within the database cannot be edited. A file must be downloaded, edited and then uploaded as a new file.

Release numbers are intended to be entirely free format, allowing organizations to use any desired format, migrate legacy release numbers, and even change the format from one release to the next if necessary (e.g. Revision 6 being superseded by Revision 6a). Since the immutable file storage security architecture of Elyse means that the database does not participate in file editing in any way, the database cannot automatically synchronize a release number stored within the database with that printed on the document, while still at the same time allowing unconstrained free format release numbers and unconstrained file formats and filenames. The task of ensuring that the release number printed on the document matches that recorded in the database must be managed by the user, or otherwise by an application layer which automates and constrains what is sent to the database.

On the Command Palette, enter Booking into the Objects field to display a list of all booking-related commands.

Workflow Management

Introduction

Apart from the operating system, the Elyse database is application layer agnostic. It is designed to function independently of document file editing software and hence cater for any type of file produced by any existing or future file editing software. The application layer may exploit the markup functionality of file editing software but will need to store the marked-up file separately from the original file. In the interests of providing a secure immutable historical record, no functionality is provided to alter files stored in the database. Files can only be either inserted or deleted. Hence, simultaneous collaboration functionality must be handled at the application layer, either in the Elyse application or a different application. If a finely grained and single comprehensive record of the history of all of the markups or changes and comments made to a file is required then the file must only be inserted into the database after all changes or markups have been completed.

How Workflow Management Works

Creation of workflow models can only be performed by Configurator level roles. Controllers link a workflow model to a document ID to create a workflow instance, and assign participants. Editors link input files to a workflow instance to commence the review process. Reviewers link output files, being the marked up reviews, to the workflow instance.

A workflow model defines the steps that are to be applied to a workflow. Workflow instances comprise a copy of a workflow model as applied to a particular document for a particular instance.

Workflow models are defined using a graph database. This defines the nodes and edges that comprise a graph. Any type of graph can be created, including graphs with cycles. The nodes of the graphs are referred to as workflow steps. The edges are referred to as step transitions. At each step transition there can be a defined workflow action. For example: revise, review, approve, publish. Each step transition can also be linked to one or more workflow rules. An example of a rule might be 'all participants must respond', or 'time-limited review, after which progress proceeds automatically to the next step'. Workflow rules can contain up to three integer values. These values can be used by the application for purposes such as defining intervals for review expiry warning and review expiry.

A workflow instance links a single document with a workflow model. Workflow instances contain steps which are linked to the workflow model step definitions. Associated with a workflow instance definition is a present step identifier. Each step can be linked to one or more input files. Each workflow step can be linked to a step status definition, for example: planned, in progress, completed. Each workflow instance step can contain up to three dates which can be used by the application for purposes such as recording start and end date of the step for example. Each workflow instance step can be linked to one or more workflow step participants. This links the step back to individuals. The steps can also be linked to duty functions, which are in turn linked to individuals. Each of the workflow step participants or duty functions can be linked to a workflow output definition, such as: approved, revise and resubmit, rejected. Each of the workflow step participants or duty functions can also be linked to one or more output files. These are the copies of document markups for example. A separate copy is stored, rather than depending on the internal markup features of the file editing software. Hence the step definition is linked with input files and the participants or duty functions linked to the step are linked to output files.

Any individual who is required to return a file as part of a workflow step must have Editor or Reviewer role permission to be able to add a file to the database and update the workflow step.

Workflow instance data is recorded in a track log. The workflow track log is automatically triggered by the following events.

Data in the track log table is a copy of the original data. Hence the track log only records historical data and will not update when source data is changed. Deleting workflow track log data can only be performed by a Database Administrator.

Viewing and editing permissions are applied to records in workflow management via checking the document which is linked to a workflow instance. When retrieving workflow related records, including the track log, only records which are linked to a document which the user has viewing rights to will be retrieved.

Document Groups

Overview

Documents can be grouped into Document Groups. Document groups in turn are used for two purposes:

Restricting visibility of documents is defined by creating a direct link between a document group and a user. Restricting metadata editing rights of documents is defined by linking a document group to a Duty Function List or a People List. Users can be granted membership to these lists.

Document Viewing Groups

Document viewing groups are used to restrict access to documents and associated files. This can be used for sensitive documents for example. Any other document grouping purpose can be met using metadata. Document viewing groups allow for collections of documents to be segregated between different groups of users such that users will have no visibility of documents or metadata of other groups, regardless of their role in the system.

The document viewing groups function works as follows.

The workflow sequence for document viewing control is as follows.

  1. A user with Configurator or Controller permissions creates a document viewer group name. At this point any files linked to that document viewer group will be visible to anyone.
  2. A user with Authorizer permissions links the document viewer group name to a user ID. (The user must have already been onboarded.) The Authorizer cannot self-authorize. From this point onwards only users who are linked to the document viewer group will be able to see any records of documents linked to the document viewer group or add documents to the viewer group. Any file which is linked to a document which is restricted will be restricted in the same manner as the document.
  3. Controllers who have document view permission for a given document viewer group may link documents to the document viewer group.
  4. If multiple document groups are linked to a document and the document viewer groups have different groups of users linked to the different document viewer groups then all users who are linked to the different document viewer groups will have rights to the document.
  5. Document viewer group permissions are revoked by an Authorizer. Note: Because documents are viewable by default if there are no users linked to a document viewer group, deleting the last user from a document viewer group will render all the documents of that group viewable to all users. For this reason it is not possible for an Authorizer to delete the last user from a document viewing group unless there are zero documents linked to that group.

Documents are viewable by default. A document only becomes restricted for viewing when there is at least one user linked to a document group via document group viewing permission.

Document Editing Groups

Overview

The following applies to Editor level permissions only.

Document group editing permissions function differently from document group viewing permissions. Whereas document viewing groups are accessible for viewing by default, document editing is restricted by default.

Another difference between edit permissions and viewing permissions is that viewing permissions are managed at Authorizer role level whereas Editor level editing permissions are managed at Controller role level.

How Document Group Editor Level Permissions Work

Document group edit permission grants an Editor role user permission to edit metadata associated with a document which is a member of a document group. The authentication of document group edit permission first checks if the user has viewing permission for the document group and fails if the user does not have viewing permission. Hence a user can be on a list which has document group editing permission but the permission will not be effective if the user does not also have viewing permission.

Only Controller and Editor roles can edit document metadata. A Controller or Editor role user can only edit metadata for documents for which they have both viewing permission and edit permission. A Controller can create a document group and grant access to an Editor.

There are two ways in which an Editor role user can gain metadata editing permission for a document.

If a Controller adds a user with Editor role permissions to a Duty Function and the duty function in turn is a member of a Duty Function List which in turn is linked to the document group. Similarly, if a Controller grants the user membership of a People List which in turn is linked through to a document group. In either case, if there is a chain link from the document through the document group to the user then the user will have metadata editing rights.

A user with editing role permission can also create a document ID and specify a document editing group for which they already have editing permission. When the document ID is created it will be automatically linked to that document group. The user can therefore be given a sandbox within which they can create documents and then edit the metadata for the document they have created.

Restricted Metadata Fields

Document radio button lists and file radio buttons lists include a column named restricted. If the value of restricted is set to True then only a user with Controller role will be able to create or update a link between an attribute in that list and a document. An example of how this feature can be used is for setting the publication status of a document. An Editor may have permission to set various attribute values for a document they have edit permission for but be prevented from setting or changing the publication status. Only a Controller would be able to set or change the publication status.

Document Group Editor Level Permissions

Overview

The following applies to Editor level permissions only.

Document group editing permissions function differently from document group viewing permissions. Whereas document viewing groups are accessible for viewing by default, document editing is restricted by default.

Another difference between edit permissions and viewing permissions is that viewing permissions are managed at Authorizer role level whereas Editor level editing permissions are managed at Controller role level.

How Document Group Editor Level Permissions Work

Document group edit permission grants an Editor role user permission to edit metadata associated with a document which is a member of a document edit group. The authentication of document group edit permission first checks if the user has viewing permission for the document group and fails if the user does not have viewing permission. Hence a user can be on a list which has document group editing permission but the permission will not be effective if the user does not also have viewing permission.

Only Controller and Editor roles can edit document metadata. A Controller or Editor role user can only edit metadata for documents for which they have both viewing permission and edit permission. A Controller can create a document group and grant access to an Editor.

There are two ways in which an Editor role can gain editing permission for a document. If a Controller adds a user with Editor role permissions to the membership of a duty function list which is linked through to a document group then the user will have editing permission for any document within that group. A user with editing role permission can also create a document ID and specify a document editing group for which they already have editing permission. When the document ID is created it will be automatically linked to that document group. The user can therefore be given a sandbox within which they can create documents and then edit the metadata for the document they have created.

Document radio button lists and file radio buttons lists include a column named restricted. If the value of restricted is set to True then only a user with Controller role will be able to create or update a link between an attribute in that list and a document. An example of how this feature can be used is for setting the publication status of a document. An Editor may have permission to set various attributes for a document they have edit permission for but be prevented from setting or changing the publication status. Only a Controller would be able to set or change the publication status.

File Groups

Overview

File groups are used for managing rights to edit the metadata of files. File groups are managed at Controller level.

Unlike document groups, file groups do not have a corresponding file viewing group permission. File viewing restrictions are managed via linking of files to documents which in turn have viewing restrictions applied. This avoids a clash between document viewing restrictions and viewing restrictions applied to files which are also linked to documents with a different set of restrictions. There is only one set of viewing restrictions. However, this arrangement also means that, unlike document groups, all users have permission to see all file groups. With document groups, other than Authorizers, only users with permission to view a document group can view the details of the document group. Hence file group details, such as name or description, should not be used for storing sensitive information.

How File Groups Work

The following applies to Editor level permissions only.

File group edit permission grants an Editor role permission to edit metadata associated with a file which is within a file group.

File metadata editing is restricted by default. A Controller role can edit any metadata for any file for which they have viewing permission and for which they are not excluded by Controller level edit permission restrictions. An Editor role can only edit metadata for a file for which they have viewing permission and edit permission.

The authentication of file edit permission first checks if the user has viewing permission for the file. If the user has viewing permission for the file a check is then made to establish if there is a link from the file back to the user ID of the connected user. The authentication will fail if there is not a link from the file to the user's ID.

File group edit permissions are managed at Controller role level. However, an Editor role user can grant themselves permission to edit metadata of a file by linking the file ID to a file group, providing all of the following conditions are met:

  1. The connected user has viewing permission for the file, and
  2. The file is free from edit restrictions which exclude the current user, (i.e. the file has edit permissions for other users but not the connected user), or it has no edit permission restrictions at all, and
  3. The connected user has edit permission for the file group which the file is to be linked to. File edit permission for a user must be granted by a user with Controller level permission, except where the user creates a personal person list.

This allows an Editor role user to add a file and then edit the metadata for that file. The user must first have edit permission for a file group. An Editor role cannot delete a file to file-group link however. Deleting the file to file-group link is a Controller role level function. Otherwise an Editor level role could remove file edit permissions from other users.

Note that a Controller level user can create, edit and delete file groups and they can grant file edit permissions but they cannot edit metadata for a file unless they have the required file edit permission.

File Group Editor Level Permissions

Overview

File groups are used for managing rights to edit the metadata of files. File groups are managed at Controller level.

Unlike document groups, file groups do not have a corresponding file viewing group permission. File viewing restrictions are managed via linking of files to documents which in turn have viewing restrictions applied. This avoids a clash between document viewing restrictions and viewing restrictions applied to files which are also linked to documents with a different set of restrictions. There is only one set of viewing restrictions. However, this arrangement also means that, unlike document viewing groups, all users have permission to see all file group names. With document groups, other than Authorizers, only users with permission to view a document group can view the details of the document group. Hence file group details, such as name or description, should not be used for storing sensitive information.

How File Groups Work

The following applies to Editor level permissions only.

File group edit permission grants an Editor role permission to edit metadata associated with a file which is within a file group.

File metadata editing is restricted by default. A Controller role can edit any metadata for any file for which they have viewing permission and for which they are not excluded by Controller level edit permission restrictions. An Editor role can only edit metadata for a file for which they have viewing permission and edit permission.

The authentication of file edit permission first checks if the user has viewing permission for the file. If the user has viewing permission for the file, a check is then made to establish if there is a link from the file back to the user ID of the connected user. The authentication will fail if there is not a link from the file to the user's ID.

File group edit permissions are managed at Controller role level. However, an Editor role user can grant themselves permission to edit metadata of a file by linking the file ID to a file group, providing all of the following conditions are met:

  1. The connected user has viewing permission for the file, and
  2. The file is free from edit restrictions which exclude the current user, (i.e. the file has edit permissions for other users but not the connected user), or it has no edit permission restrictions at all, and
  3. The connected user has edit permission for the file group which the file is to be linked to. File edit permission for a user must be granted by a user with Controller level permission, except where the user creates a personal person list.

This allows an Editor role user to add a file and then edit the metadata for that file. The user must first have edit permission for a file group. An Editor role cannot delete a file to file-group link however. Deleting the file to file-group link is a Controller role level function. Otherwise an Editor level role could remove file edit permissions from other users.

Note that a Controller level user can create, edit and delete file groups and they can grant file edit permissions but they cannot edit metadata for a file unless they have the required file edit permission.

Controller Groups

Metadata Edit Permissions Overview

Edit permissions for metadata are divided into two layers. At the first layer are permissions that are granted by Authorizers to Controllers. These are referred to as Controller level permissions. This gives members of the group exclusive metadata editing rights that cannot be altered by other Controllers. If a user is linked to a Controller editing group but does not also have Controller rights, or later ceases to have Controller rights, then the Controller level edit permission authentication will fail.

The second layer of edit permissions are permissions that are granted by Controllers to Editors. These are referred to as Editor level permissions. Any Controller can alter any Editor level permissions. Any Controller can also edit the metadata of any document or file which they are not excluded from through Controller level permissions. A Controller can grant Editor level permissions to any user. The edit permissions authentication does not check if the user has Editor rights for Editor level permissions, however a user will not be able to perform Editor functions if they do not have Editor level rights because the role authentication check will fail.

An application of the above structure would be as follows. In a large organisation, Controllers in different branches of the organisation must be able to view organisation-wide published documents but must not be able to edit the metadata of such documents unless they have been explicitly granted that permission. Hence Controller level permissions should only need to be altered if the organisation structure changes. Controllers would be granted specific Controller level permissions by being added to a given Controller level edit permission group. Within a branch of an organisation, Controllers must be able to grant document owners permission to edit metadata of documents which they own. This is managed through Editor level permissions. However Editor level permissions are overridden by Controller level permissions.

In the Command Palette select the Name/Description Search button and type Controller into the search field to display a list of all Controller level related commands.

How Controller Groups Work

Controller level permissions are divided into controller document groups and controller file groups. Only Authorizers can create and modify these groups and grant or revoke membership to a group. Authorizers cannot self-authorize.

Once a Controller has been granted membership of a controller document group or controller file group then they are able to link a document or a file to a respective group. The metadata for that file or document will then only be able to be edited by members of that group.

Users can be directly linked to the following.

Controllers can also be linked to controller file groups and controller document groups to provide metadata editing rights which are exclusive within the group. Controllers can also be linked to form groups as a form group owner to provide form editing rights which are exclusive within the group.

Duty Functions are intended for organizational duty functions, for example Safety Manager. Duty functions in turn can be grouped into Function Lists.

Function lists can be linked to the following.

People Lists are provided as a means of directly grouping users without needing to assign duty functions.

User-related fields can be linked to a General Field Name, for example Author. The following can be linked to a general field name.

Audit Logs

Overview

Elyse contains dedicated audit log tables for the following.

A record of connected user and time stamp are also included in the following records.

Managing and Reading Audit Logs

Authorizer privileges requests are logged and can be viewed by Authorizers.

When privileges are granted to the user, the time and grantor are logged with the entry. These can be viewed via the commands that list the privileges data. When privileges are revoked the details are stored in a dedicated log. This log can be viewed with Authorizer privileges by reading the Revoke Log.

The file read access log can be switched on and off by a Database Administrator via the File Read Log setting in Global Settings. The file delete log can be switched on and off via the File Delete Log setting in Global Settings. Global Settings can only be modified, and log records can only be deleted, via direct Database Administrator access.

Various commands are available for Controllers to access reading log records. Reading of file logs is filtered according to access privileges of the connected user. That is, only files which the connected user has viewing rights to will be listed.

Important: When a file has been deleted, the viewing rights restrictions are also deleted. However the filename will still be listed in the logs and will no longer be restricted. Hence the filenames of deleted files which were restricted prior to being deleted will be viewable to anyone with Controller level privileges after the file has been deleted.

The workflow track log can be viewed with Reader level privileges. The workflow track log does not have an option for disabling it.

More finely grained audit logging can be achieved by configuring SQL Server audit log.

Reader Level Role

Overview

The Reader level role has privileges that are not available to an unprivileged user.

To view a list of all of the privileges you have been granted, go to the navigation bar and select Connected User > List User Privileges.

Unfiltered Searching

All unprivileged searching of documents and files must be subjected to a filter group filter. Typically this is the filter that ensures that only the current latest release of documents are presented to the user. Elyse is pre-configured with this filter group as the default filter. Other selectable filters may be available depending on how metadata and the application layer have been configured.

Reader level role provides access to searches which do not apply a filter group. Permission filtering is still applied, but the user will be able to view superseded documents for example.

Personal Tag Browsing Trees

The Reader level role has permission to create tag browsing trees. These are essentially personal saved searches lists. In the Command Palette enter Tag Browsing Trees into the Objects field to see a list of applicable commands.

Editor Level Role

Overview

The Editor level role has all the privileges of the Reader level role, plus the following additional privileges:

The Editor level role is for users who need to be able to load files into the database and edit metadata. Editing of metadata is restricted to document and file groups which the user has been granted rights to by a user with Controller level privileges.

To view a list of all of the privileges you have been granted, go to the navigation bar and select Connected User > List User Privileges.

Note that by design it is not possible to edit the content of a file within an Elyse database. 'Editing' is restricted to editing of metadata only.

Creating Document IDs

In the Command Palette enter Create into the Actions field and Document into the Objects field and select the command Create and Edit Document ID (Editor Role).

The Document Group dropdown lists document groups for which either you have edit permission or which are unrestricted. If there are none listed then you will not be able to create a new document ID. Controller role permissions are needed to grant a user membership to a document edit group.

If auto-generation of document IDs is enabled then a new unique document ID will be automatically generated if the document ID field is left blank. Otherwise the string entered into the field will be used. The database is designed to securely handle strings containing any characters.

After the form is submitted a confirmation dialog will be displayed. A data entry form then appears where metadata for the document ID can be edited. Enter a title into the Title field and then press the Add Field (+ button) beside the field. A confirmation dialog will appear, followed by a results dialog after the transaction has been completed. The metadata fields which are available will depend on the configuration of the default form. Users with Configurator role privileges can configure the form fields.

The command Recently Created Documents will list document IDs that were created in the interval defined by Recently Created Duration under Global Settings.

Loading Files

Editor role privileges allows the loading of files. See the Loading Files section.

Editing Metadata

In the Command Palette, enter Edit into the Actions field to display the commands for editing documents or files. The edit form for a document or a file can also be opened via a context menu. From a table of documents or files, select a single row, right click and then navigate to Edit Document Data or Edit File Data.

Tagging

A user with Editor level role permissions can create tags via the Create Document Tag command. In the Command Palette, enter Tags into the Fields field to display a list of all tag-related commands. See the sub-topic on Tag Management below.

Booking Management

A user with Editor level role permissions can book a document in and out. In the Command Palette, enter Booking into the Objects field to display a list of all booking related commands. See the Booking Management section for more details.

Workflow Management

An Editor is able to manage the review workflow for a document for which they have metadata editing rights.

In the Command Palette, enter Workflow into the Objects field to display a list of all of the workflow-related commands.

See the Workflow Management section for more details.

Reviewer Level Role

Overview

The Reviewer level role has all the privileges of the Reader role, plus the following:

The Reviewer level role is for users who conduct document reviews under the direction of a document Editor.

A Reviewer will be assigned a file to review. The Reviewer can then mark up the file and re-submit it as an 'output file'.

Within the workflow system, a Reviewer is a Workflow Step Participant. Each of the workflow step participants or duty functions can be linked to one or more output files. These are the copies of document markups for example. A separate copy is stored, rather than depending on the internal markup features of the file editing software.

In the Command Palette, enter Workflow into the Objects field to display a list of all of the workflow-related commands.

To view a list of all of the privileges you have been granted, go to the navigation bar and select Connected User > List User Privileges.

Controller Level Role

Overview

The Controller function is intended to manage day-to-day administrative functions such as populating and updating metadata fields. There is some overlap between Controller and Configurator and also Editor functions. The main task that a Controller can carry out which an Editor cannot is editing forms. A Controller can also create, edit and delete Document Groups, which are used for restricting visibility of groups of documents. The main task that a Configurator can perform which a Controller cannot is creating metadata fields.

The Controller level role has all the privileges of the Reader and Editor level roles, plus the following additional privileges:

In the Command Palette, enter Forms into the Fields field to display a list of form commands.

Note that a Controller cannot see documents and the metadata of documents which are restricted via document group permissions which they do not have permission for.

Document Searching

When searching for documents it is important to remember that some searches apply a filter group and others do not. Recently Created Documents for example does not apply a filter group.

Locking Document IDs

Because document IDs often must appear as cross-references on documents external to the document management system and external to the organization, (such as correspondence), once a document ID has been set it should never be changed. A document ID can be locked by a Controller. However, in the event that a document ID needs to be unlocked again, a document ID can only be unlocked by a Configurator.

Document IDs can be locked when they are created by setting the Id Lock Status to Locked. Alternatively, the Lock Document ID command can be used to lock a document ID which is unlocked.

Editing Metadata

Refer to the Forms section for an introduction to how forms work in Elyse.

When a file is loaded using the Upload File and Edit command, the form permits the file to be linked to a document ID when it is uploaded. Once the file has uploaded a page will appear with all of the metadata fields for the default form. Document-related fields are displayed with blue shading and file-related fields are displayed with green shading. Against each field are four buttons: Update, Delete, Save and Revert. Fields can be individually edited and saved, or alternatively a number of fields can be changed and saved together with the Save Changes button.

The command Create Document ID & Edit Data opens a metadata editing page after the document ID has been created.

When a document or file record has been selected in a table, right click on the row and navigate to Edit Document Data or Edit File Data to open the metadata editing page.

At the bottom of the metadata editing page is a row of data which includes the Form Name. A different form can be selected from the Form dropdown field in the Edit Document Data and Edit File Data forms.

Note that if a document or file is linked to a Controller Document Group or Controller File Group then editing rights will be restricted to Controllers who are members of the given group. See the Controller Groups section for more detail.

Forms

Refer to the Forms section for an introduction to the form system.

For a list of all of the form-related commands, enter Forms into the Objects field in the Command Palette.

Form Group Ownership

A Controller can create and edit forms. However in order to have exclusive editing rights to a form the form must be linked to a form group and the user granted ownership of that form group.

Tag Relationship Trees

Refer to the Tag Management section for an explanation of tags.

Controllers can create and modify Tag Relationship Trees and Tag Browsing Trees. Enter Tag Relationship Trees or Tag Browsing Trees into the Fields field in the Command Palette to list the applicable commands.

Document Booking Management

Refer to the Booking Management section for an explanation of the booking management system.

A Controller can book in any document for which they have edit permission rights and which is currently booked out.

On the Command Palette, enter Booking into the Objects field to display a list of all booking-related commands.

Workflow Management

Refer to the Workflow Management section for an explanation of the workflow management system.

Controllers link a workflow model to a document ID to create a workflow instance, and assign participants.

On the Command Palette, enter Workflow into the Objects field to display a list of all workflow-related commands.

Edit User Details

The text fields of a user record can be updated by Authorizers, Configurators and Controllers via the Update User command.

Controllers manage duty functions, function lists and people lists. Refer to the User-Related Lists section for further details. On the Command Palette, enter Duty Function, Function List or People List to list all the commands for each.

Document Groups

Document groups are used to restrict visibility of sensitive documents to authorized users. Any files linked to a restricted document will be restricted in the same way.

Document groups can only be created, modified and deleted by a Controller. But only an Authorizer can link users to a document group and hence restrict visibility of documents linked to the group to users who are linked to the group.

Entering Document Viewing Groups into the Fields field of the Command Palette will list all of the document viewing group related commands.

Audit Logs

Controllers can read the file read and file delete audit logs. Entering Log into the Fields field of the Command Palette will list all of the audit log related commands.

Users

Enter Users into the Objects field of the Command Palette to list all of the user-related commands.

Configurator Level Role

Overview

The Configurator function is intended to manage the initial configuration of an Elyse database instance. The configuration is primarily that of defining the field lists and field attributes which become the lookup tables for document and file metadata. The Configurator also defines workflow models, which are templates defining workflows. A Configurator can modify any form whereas a Controller can only modify forms for which they have permission to modify.

In contrast to the Controller role, the Configurator is a function that should rarely be required once the database has been initially set up. Note that while there is some overlap between the two, the Configurator role does not have the same privileges as a Controller.

A Configurator is able to carry out the following tasks.

Metadata Fields

To create and edit metadata fields, open the Command Palette and select the Name/Description Search button. Enter the desired field type, e.g. Free Text, and find the desired command, e.g. Create, Update or Delete.

When a radio button list is created there is an option to restrict the field. If the value of restricted is set to True then only a user with Controller role will be able to create or update a link between a member in that list and a document. An example of how this feature can be used is for setting the publication status of a document. An Editor may have permission to set various metadata for a document they have edit permission for but be prevented from setting or changing the publication status. Only a document Controller would be able to set or change the publication status.

Workflow Models

See the Workflow Management section for an introduction to workflow management. To create and manage workflow models, open the Command Palette, select the Name/Description Search button and enter Workflow. Start by creating Workflow Actions (e.g. Review, Approve). Then create the Workflow Step Definitions. Finally, link the workflow step definitions together with Workflow Step Transitions.

Filter Groups

See the Filter Groups section for an introduction to filter groups.

To create a new filter group, open the Command Palette, select the Name/Description Search button and enter Create Filter Group.

After creating a filter group name, add rules using the following commands.

A filter group can contain no members and hence not apply any filtering. Such blank filter groups should generally not be created since this can be used to bypass the restriction on access to superseded documents. All users have access to all filter groups.

Forms

See the Forms section for an introduction to forms.

To create a new form, open the Command Palette, select the Name/Description Search button and enter Form Identifier to locate the Create Form command. After creating the form, populate the form with links to metadata fields using commands which can be found by searching Create Form To.

When a form is created it can be linked to a Form Group.

Form Groups

Each form can be linked to one form group. Form groups in turn are used for managing form editing privileges.

Controllers are granted permission to be form group owners by an Authorizer by linking the user to a form group. A user who is a Controller and also a form group owner will be able to create and modify forms which are linked to a form group which they are an owner of. A user can be granted permission as a form owner but if they are not also a Controller then they will not be able to modify a form belonging to that form group. A Controller can also create and modify forms which are not linked to any form group. A Configurator can create or modify any form, including forms which are not linked to any form group. Hence if a Configurator creates a form which is linked to a form group which in turn is not linked to any Controllers, then only a Configurator will be able to modify a form linked to that form group.

Open the Command Palette, select the Name/Description Search button and enter Form Group to list all form group related commands.

The form group for a given form can be updated with the command Update Form Group for Form.

Document Groups

See the Document Groups section for an introduction to document groups.

Open the Command Palette, select the Name/Description Search button and enter Document Group to list all document group related commands.

Note that document groups are for the purpose of restricting viewing rights to documents. Use tags or other metadata fields to group documents.

Edit User

The Elyse database stores a username separately from the Windows system username. A Configurator may edit the database username, description and email address for a user via the Update User command.

Unlock a Document ID

Because document IDs often must appear as cross-references on documents external to the document management system and external to the organization, (such as correspondence), once a document ID has been set it should never be changed. A document ID can be locked by a Controller. However, in the event that a document ID needs to be unlocked again, a document ID can only be unlocked by a Configurator. Refer to the Unlock Document ID command.

Date Style

The Elyse application layer will use a default date style that is recorded within the database global settings list. This can be set by a Configurator using the Update Default Date-Time Style command.

Authorizer Level Role

Overview

The Authorizer function is for managing the granting and revoking of privileges. With the exception of creating and modifying Controller-level document groups and file groups, the function does not have any modifying privileges other than those related to granting and revoking privileges.

An Authorizer is able to carry out the following tasks.

Managing User Roles

User roles can be managed via the Manage User Roles dialog box. This is available via the context menu for any list of users. For example, use the Command Palette to execute a command to find the user, such as Recent Users, or Users by Name. Then select the row on the table, right click and navigate to the Manage User Roles command. Select one or more roles to authorize or remove and then select Submit. A dialog will be displayed with the results of the transactions.

The User Roles, Users by Role and Privileges by User commands will list when the role privilege was granted and by whom.

Granting and Revoking Authorizer Privileges

In order to be able to grant Authorizer privileges to an account, without requiring Database Administrator access to the database, the database must have at least two different Windows accounts registered as Authorizers. The first two Authorizers must be configured by a Database Administrator during deployment. Each new grant requires approval of two separate Authorizers. Each revoke also requires the approval of two Authorizers. The system will not permit the number of Authorizers to be less than two.

The process for granting Authorizer privileges to a user is as follows.

  1. The user must be onboarded into the system via the self-onboard function.
  2. First Authorizer: Find the user via one of various user search commands. Select the user and execute the Grant Authorizer command. A dialog will appear stating One of two approvals for authorizer privilege grant request.
  3. Second Authorizer: Must not be the same as the first Authorizer. From the Command Palette execute the Authorizer Requests command to display a list of grant requests. Select the request, right click and execute Grant Request. The second Authorizer can also reject the grant request.
  4. A message will confirm the transaction.

The process for revoking of Authorizer privileges from a user is as follows.

  1. First Authorizer: Must not be the same user. Select the user from a list and execute the Revoke Authorizer command in the context menu.
  2. Second Authorizer: Must not be the same as the first Authorizer nor the Authorizer to be revoked. Locate the grant request on the Authorizer Requests table. Select the request and execute the Revoke Authorizer command. The second Authorizer can also reject the revoke request.
  3. A message will confirm the transaction. The transaction will be rejected if the revoke request will reduce the number of Authorizers to less than two.

The List Authorizers command will list all current Authorizers.

De-Activating and Restoring a User Account

An Authorizer can de-activate a user account in a single action by executing the Delete User command. When a user's Elyse account has been deactivated the Windows Account Current column will display No. The account can be restored again by executing the Restore User command. If the user being restored has Authorizer privileges linked to the account then the restore will fail. The Authorizer privileges must be removed from the user before the account can be restored after having been de-activated. For audit record reasons, a user account can never be completely removed from the system, it can only be de-activated.

Note that if a user is given a new Windows Account then the account will have a new security identifier (SID). Windows Account SIDs cannot be re-used.

Document Viewing Groups

Document groups are used to restrict visibility of sensitive documents to authorized users. Any files linked to a restricted document will be restricted in the same way.

Document groups can only be created, modified and deleted by a Controller. But only an Authorizer can link users to a document group and hence restrict visibility of documents linked to the group to users who are linked to the group.

Entering Document Viewing Groups into the Fields field of the Command Palette will list all of the document viewing group related commands.

Controller-Level Document and File Groups

Edit permissions for metadata are divided into two layers. At the first layer are permissions that are granted by Authorizers to Controllers. These are referred to as Controller-level permissions. This gives members of the group exclusive metadata editing rights that cannot be altered by other Controllers.

Controller-level file and document group permissions can only be granted by Authorizers. These permissions give members of the group exclusive metadata editing rights that cannot be altered by other Controllers.

If a user is linked to a Controller editing group but does not also have Controller rights, or later ceases to have Controller rights, then the Controller-level edit permission authentication will fail.

An application of the above structure would be as follows. In a large organization, Controllers in different branches of the organization must be able to view organization-wide published documents but must not be able to edit the metadata of such documents unless they have been explicitly granted that permission. Hence Controller-level permissions should only need to be altered if the organization structure changes. Controllers would be granted specific Controller-level permissions by being added to a given Controller-level edit permission group. Within a branch of an organization, Controllers must be able to grant document owners permission to edit metadata of documents which they own. This is managed through Editor level permissions. However Editor level permissions are overridden by Controller level permissions.

The Controller document group commands can be listed by entering Controller Document Group into the Fields field in the Command Palette, and Controller file group commands by entering Controller File Group.

Form Group Owners

See the Forms section for an explanation of form groups.

The form group commands can be listed by entering Form Groups into the Fields field in the Command Palette.

Edit User Details

The text fields of a user record can be updated by Authorizers, Configurators and Controllers via the Update User command.

View User Privileges

The Privileges By User command will list all of the privileges for a given user. This command is only available to Authorizers.

Demo Database Primer

The following is a primer introduction to Elyse, using the demonstration database.

Doc Title Contains

From the navigation bar select Basic Search > Doc Title Contains.

On the form which appears, select the Contains field and enter Food.

Click Submit.

Click on a hyperlink under the Document ID column.

A table now appears which lists the file for the latest release for that document.

Select a row by left clicking, then right click and click View File Details With Thumbnail. A thumbnail of the first page together with a table of all of the metadata associated with the file will be displayed.

Clicking on the File ID hyperlink will download the file.

Doc ID Equals

From the navigation bar select Basic Search > Doc ID Equals.

On the form that appears, select the Document ID field and type LVPL.

Click Submit.

A listing for the document ID LVPL is returned.

This function searches the Document ID field in the database for an exact match. If the document ID was not listed in the database, or was not accessible to the connected user, then no results would be returned. This function is very specific and does not search any other fields, or search the content of files for example.

Forms

Repeat the Doc ID Equals search again, only this time on the form, in addition to entering LVPL into the Contains field, select Long Form from the Form dropdown.

The results are now displayed using a different form which has more fields. Hover the mouse over the column heading DCB for example. A tooltip will appear with the full description of the column, Document Created By.

Forms are customizable by users with Configurator or Controller role privileges.

Tags

From the navigation bar, select Basic Search > Docs by Tag.

From the form that appears, select the > button beside the Tag field. Select Tag Contains.

In the popup form Tags by Name, select the String Contains field and type saf. Then select Submit.

From the table that appears, select the row containing the Tag Name 'Safety'. Click Confirm to return to the Documents by Tag form. The tag has now been selected for the Tag field.

Ignore the other fields on the form and click Submit. A table of documents will appear.

Clicking on the text of the column heading Title will sort the list by that column.

Left click the row for the document with the title Hazard Identification Procedure (but not on the hyperlink under Document ID).

Now that the table row has been selected, right click to open the context menu. Select Document Details.

A list of all of the metadata linked to this document is displayed.

Note that at the bottom of this table there is only one tag listed: 'Hazard Identification'. Yet the tag that was used for searching was 'Safety'. This is because the search included a default Tag Relationship Tree. Tag relationship trees are hierarchical tag trees which define parent-child relationships between tags. 'Hazard Identification' is listed as a descendant of 'Safety'.

If the same search as above is repeated but the Tag Descendants field on the Documents by Tag form is selected to Off, then the Hazard Identification Procedure will not be listed.

Tag relationship trees can be used to drastically reduce the number of tags which must be linked to a document.

Content Searching

From the navigation bar, select Basic Search > File Content Search.

On the form that appears, select the Contains field and enter Quality.

Click Submit.

A list of all files containing the word 'Quality' will be displayed.

More advanced file content searching functions are available under Advanced > Search > Files > File Content Searching. Hover over each menu item for more details.

Command Palette

Click the ⌘ button to open the Command Palette.

In the Actions field type Select and press Enter.

A complete list of all of the available select-related commands will be displayed. Note that not all of these commands will return results, depending on what metadata has been entered into this database.

Clear the previous search term by clicking the x next to it.

In the Fields field of the Command Palette enter Tags and press Enter.

A list of all of the commands related to tags will be displayed.

What Is A Controlled Document

Controlled documents have characteristics that differentiate them from other types of documents. The management of these types of documents is governed by strict rules, often dictated by regulatory or compliance obligations. Examples of controlled documents include standards, procedures and policies.

The following are typical key characteristics of controlled documents.

  1. Review and approval. All controlled documents are subjected to review and approval. A document must be formally approved before it can be released and used.
  2. Formal issuance and withdrawal. Controlled documents are formally issued for use, and withdrawn from use when no longer valid.
  3. Currency status and distribution control. All controlled documents must have a currency status. That is, a document may have a status of current, superseded, obsolete or cancelled for example. Controlled documents that are no longer current must be withdrawn from use so that they are not inadvertently used.
  4. Issue history. Different issues or releases of a controlled document must be uniquely identified (e.g. with a revision or version number).
  5. Directive authority. Controlled documents, such as standard operating procedures for example, typically carry directive authority. That is, the document gives instructions that must be followed.
  6. Periodic review. Directive authority type controlled documents, such as standards, procedures and policies, must be reviewed on a periodic schedule and revised and re-issued as appropriate. Engineering drawings are a class of controlled document but are generally not subjected to review on a time-based schedule but are revised based on other triggers.
  7. Unique identification. Controlled documents must be uniquely identifiable. Generally this is via a document ID, being a string of characters, a sequence number or a combination thereof.

Elyse is specifically designed to handle these unique characteristics of controlled documents.

Frontend Functional Specification

Overview

This section describes how the frontend application layer can be zero-code customized via editing csv files in the deployment folders.

The Elyse document management application comprises a Microsoft SQL Server database, a .Net C# backend and an Angular Typescript frontend.

The SQL database contains approximately 900 fully parameterized stored procedures. Applications can only interact with the database using these stored procedures via application roles. The stored procedures contain all of the business logic. Each stored procedure that the backend executes performs either a Create, Read, Update or Delete function. These are identified by INS, SEL, UPD and DEL in the stored procedure names.

The backend merely performs a pass-through function and does not contain any business logic. Each backend API corresponds to one stored procedure.

This document is a description of part of the functionality of the front end.

The front end is primarily a data driven application. Some code is function-specific, however the majority of the code is generic and is driven by data contained in csv files.

The following are the primary entities of the front end.

The data files provide the data which is used to construct these entities, how data flows between them and how the user interacts with them.

Menu Files

User actions are initiated through one of the following:

The navigation bar item can initiate one of the following:

Navigation bar items are defined in file navigation-bar.csv. This file defines the following:

The file navigation-bar.csv contains the following fields.

A context menu item will only perform an action related to the table which is presently displayed. A context menu item can initiate one of the following:

Note that if a form has only one parameter and that parameter is a record to be selected from another table, the form itself will not be displayed, giving the appearance that the menu item directly opens the table for selection.

The context menus are defined in the file context-menus.csv. This file defines the following:

The file context-menus.csv contains the following fields:

Endpoint Data Files

The following files contain the endpoint and related data for different action types. These are referred to as endpoint data files.

The endpoint data files contain a list of input parameters named according to the backend names. However the endpoint data files do not indicate whether input parameters are mandatory or optional. The code will construct an API call with whatever parameters it is given and ignore parameters it is not supplied with. Forms however include the option to control whether a parameter on the form is mandatory or optional.

The purpose of the file read-routes.csv is to specify the displaying of a data table and facilitate the selection of records from the table. The following are defined:

The file read-routes.csv contains the following fields.

The file duc-routes.csv is used for all delete, update and create routes. It contains the following fields.

If a parameter in InputParameters is not found in state variables then a check will be made of the URL to see if it is contained in the URL. If a parameter string in InputParameters contains '=' then the string to the left will be taken as the parameter and the string to the right will be taken as the value. Hence input parameters which are not in state variable or the URL can be hard-coded into duc-routes.csv. If the parameter is not found in either then an error is raised and the process exits.

Custom View Data Files

The following files contain the configuration data for custom views that display data in specialized non-tabular formats.

The purpose of custom views is to display data retrieved from backend endpoints in specialized formats such as image galleries, card layouts, or other custom visualizations that cannot be effectively represented in standard tables.

The file custom-views.csv contains the following fields:

The file custom-view-fields.csv contains the following fields:

Custom views follow the same parameter management rules as tables and forms. Input parameters not found in state variables are checked against the URL, and if still not found, an error is raised.

For IMAGE field types, the DataSource should contain either:

Custom views integrate with the existing menu system and can be opened from navigation bar or context menus using ActionType=CUSTOM.

Record ID Management

When one or more rows in a table are selected, the key columns corresponding to record IDs are stored by the application. This is defined in read-routes.csv. A corresponding ID name is also stored.

Apart from Document IDs, the application does not display underlying IDs to the user. Instead, a corresponding name is displayed. Each ID type has a unique name. For example, document group IDs are returned by the stored procedure with a parameter name "Doc Group ID". The ID is in the form 12345. Each record in the document groups table has a mandatory name field. The content of this field is returned by the stored procedure with the parameter name Doc Group Name. Hence the data structure is:

ID Type: ID; ID Name Alias: ID Name Value
Doc Group ID: 12345; Doc Group Name: Standard Specifications

A form will display "Standard Specifications" to the user. The ID 12345 is stored in the background. Hence, when a form requires an ID type parameter to be supplied, the actual ID will be stored in the background while the associated record name is displayed.

The file input-id-parameter-mapping.csv maps the ID Name Alias from a table to the backend endpoint input parameter. This only relates to ID type parameters. The file contains the following fields.

Some ID Name Alias' map to more than one input parameter.

The NameFieldAlias column is used by the form-field.service to dynamically map dropdown API responses to standardized Id and Name fields.

When a context menu item is selected the reference row in read-routes.csv, duc-routes.csv or forms.csv is referred to. For read-routes.csv or duc-routes.csv the InputParameters column for the corresponding row is read and the input parameters mapped to the aliases given in input-id-parameter-mapping.csv. Any that don't have a match are ignored. For any that do match the matching value from IDNameAlias is then compared with the most recent state variable row selection data against the second element of the KeyColumns pair. Where a match exists the first element of the pair is then used as the value for the corresponding input parameter. For example:

  1. Displayed table is all-documents.
  2. Context menu ActionType = READ. Reference = files-for-one-document.
  3. InputParameters from read-routes.csv are documentId;filterGroupId;formId.
  4. Mapping with input-id-parameter-mapping.csv results in a match only for documentId.
  5. The IDNameAlias for documentId is Document ID.
  6. The ID field name of the state variables for the selected row matches Document ID. The value is BFRY.
  7. Executing the menu item calls /reading/files-for-one-document?documentId=BFRY

Output Parameter Management

The backend endpoints contain output parameters. The files read-routes.csv and duc-routes.csv contain a column OutputParameters which lists which of those output parameters are to be displayed. The file output-parameter-labels.csv maps output parameter names to message labels that are to be displayed against the content of a given output parameter. The file contains the following fields.

Iterated Actions

If more than one table row has been selected then the action is iterated over the parameters. This applies to all delete actions. This also applies to create actions where a record ID is an input parameter to the action. Iterating does not apply to read or update actions. This functionality is custom-implemented for the documents table and files table. The same functionality applies to other tables but in a generic form.

Iterating also applies where more than one record is selected for an input parameter for a form which has only one input parameter. For example a document may be linked to a number of files. The document record is selected and then a lookup table of files is opened and a number of file records are selected. The create API call will be iterated over the selected file records to link each one to the document.

Forms

Forms are defined in the code by a series of tables in a similar manner to a relational database.

The following data files contain the data to manage files.

The file forms.csv defines each form. The file form-fields.csv defines the form fields. These form fields are related back to forms via the FormId key. For some form fields there are several options for how the required data can be selected. The file form-field-menus.csv lists menu items that can be associated with a form field. These link back to the form field via the FormFieldId key.

Forms are defined in forms.csv. Form fields are defined in form-fields.csv. This data file defines various details including how the field is to be populated. For example, the field may be populated via one of the following options.

Forms are recursive. A progressive data selection system is used. This means that sometimes retrieving the data for a field on a form may require another form. The process continues until a data item is selected. The data is then passed back to the previous form. When the user confirms the action on the previous form, the data is passed back to the earlier form, and so on until the original form is reached.

For some parameters there may be more than one endpoint call that can be used for retrieving the value. In such cases the action to initiate searching for the parameter value presents a menu. These menus are defined in form-field-menus.csv. The Reference field in form-field-menus.csv is referenced back to read-routes.csv or forms.csv. The file form-field-menus.csv defines forms. The file read-routes.csv defines how data is retrieved and displayed in a table. The process loops back and proceeds from the beginning following the same rules as before in a progressive data selection pattern. A chain of interlinked forms can be initiated in a progressive data selection process. Each new form is initiated by a user action. The progressive data selection process terminates when the action on a field returns data to populate the field rather than opening another form. That data is then passed back to the earlier form. This data being passed back is then used to select another required element of data. The process cascades back until the original form is reached and the field is filled in using the end result of the progressive data selection. If the process is cancelled during the progressive data selection process then the user is returned to the original form.

A form will be opened from a navigation bar item or a context menu item or from another form. A form is used to enter input parameter data necessary for an endpoint call. The data is either entered or selected from a table. An input parameter may also be pre-populated from a table record selected prior to opening the form.

The file forms.csv contains the following fields.

All forms shall have the same behaviour with regards to cancelling. "Cancel" shall cancel the form and revert to the state prior to the form being opened.

NOTE that the values from the table row selected before the form was launched must be retained for passing forward to the API call or for passing forward in the progressive data selection process. This is the TitleData field.

Passthrough Forms

PASSTHROUGH forms are a special form type that collect user input and pass it directly to the next step in the progressive data selection process without calling any backend endpoint. This is useful for direct entry fields in form field menus where the user types a value that is then used as a parameter for a subsequent action. PASSTHROUGH forms still apply all form validation rules (mandatory fields, character limits, data type conversions) but do not make API calls. The form data is mapped to parameters using the ParameterId field from form-fields.csv and returned directly to the calling context. PASSTHROUGH forms are particularly useful when included in form-field-menus.csv to provide a direct entry option alongside table lookup or other form options.

The file form-formfield-links.csv defines which fields are to be included in a given form. It allows for a normalised data structure whereby form fields can be re-used across multiple forms. The file form-formfield-links.csv contains the following fields.

The file form-fields.csv contains the following fields.

If a form contains only one field and the PopulationType is LOOKUP_TABLE then the form does not appear but rather the lookup table is immediately displayed so that the user does not have to make an unnecessary click. For example, if a context menu action is to link selected records in one table to one or more selected records in another table then selecting the context menu item will cause the second lookup table to be immediately displayed. The action is handled by a form but the form is not displayed. Also under these conditions, if more than one record in the lookup table is selected then the action will be iterated over for each instance of the records selected in the lookup table. This iterating only applies if there is only one field in the form.

NOTE that the TitleData field passed forward from the table row selection is not displayed as a data entry field.

Fixed dropdowns are hard-coded dropdown lists of options. The file fixed-dropdowns.csv contains the following fields.

The file form-field-menus.csv contains the following fields.

Form field menus are single level only.

Context menus and navigation bar menus support multiple levels of nesting through the ParentMenu field.

Form Chaining Functionality

Overview

Form chaining allows the automatic transition from one form or dialog to another based on predefined rules. This functionality enables two key workflows:

  1. Automatic Form Transitions: When a form operation completes, the system can automatically open another form, passing relevant data from the first form to the second.
  2. Dialog-to-Form Transitions: When a dialog box is closed, the system can automatically open a specific form, creating a guided workflow experience.

Configuration

Form chaining is configured through a dedicated CSV file (form-chains.csv) as defined below.

The file form-chains.csv contains the following fields.

Example 1: Document Creation to Document Editing

When a user creates a new document ID, the system automatically opens the document data editing form:

rid-ins-document-id,rid-edit-doc-file-data,documentId:newdocumentid,transactionStatus=Good,AUTO

Example 2: Document Count to Document List

When a user views a document count summary and closes the dialog, the system automatically shows the full document list:

number-of-all-docs,all-documents,,,DIALOG_CLOSE

If a user navigates away from the forms then form state is not preserved.

Doc File Form Field Routing

The file doc-file-form-field-routing.csv contains data that is used for the forms for managing metadata for documents and files. The file Explanation of edit-doc-file-data page.txt explains how the data contained in doc-file-form-field-routing.csv is applied.

Adding New Endpoints

To add a new endpoint for a stored procedure, carry out the following basic steps.

  1. Populate stored_procedures.csv in the backend with the stored procedure details.
  2. Create the backend C# endpoint controller file, following existing patterns.
  3. Create a corresponding record in read-routes.csv (for a read type endpoint). The ApiEndpoint and other fields must match those in the endpoint controller. The frontend RouteUrl can be anything and is only defined in this field.
  4. The endpoint is now ready to be linked to menus and forms.

Help System Functional Description

Overview

The help system follows a data-driven architecture pattern using CSV configuration files to define help content, routing, and display behavior.

The help system comprises the following main components:

Help Content Architecture

Help content is organized using a directory-based structure with CSV configuration files defining the help topology, content mapping, and role-based visibility.

Help content files are stored in the following structure:

assets/help/
├── help-directory.csv       # Primary help directory structure and navigation
└── content/                 # Markdown files containing help documentation e.g.
    ├── some-help-topic.md
    ├── another-help-topic.md
    └── [additional help topics]

Help Directory Configuration

The file help-directory.csv defines the hierarchical structure of the help system and determines how help topics are organized and accessed through the help menu. This file contains the following fields:

The help directory supports unlimited hierarchical nesting. Topics without a ParentHelpId are displayed as top-level categories in the help menu.

Hierarchical Navigation Features

Parent Topics with Content

Sub-Topic Listings

Menu Behavior

Role-Based Filtering

Integration with Role System

Role Field Behavior

Markdown Content

Supported Markdown Features

Explanation of Command Palette

Query Constructor

The command palette is a query constructor which translates user intent into a query which finds the applicable command. Commands are found by a combination of Actions, Objects and Fields. The system uses permission-aware filtering to only display commands that the connected user has access to.

Field Name Loading

Most data fields are user-configurable and hence are not natively known to the application – they must be read from the database. At session start, endpoint calls are made to collate a list of all available user-configured field names. The file metadata-field-loading.csv contains three columns. ReadRoute maps to the ReadRoute column in read-routes.csv. This points to an endpoint that will retrieve a table of field names. The field name ID and field name columns are identified by the labels in the FieldKeys column of metadata-field-loading.csv, separated by '::'. The application calls each endpoint and creates a table which maps each field ID and name to the field type in a FieldNames table comprising FieldID, FieldName and FieldType. This is used to map field names to the Fields column of command-palette.csv.

However there are additional field names which are fixed and are not retrieved by endpoint calls. These are added to the list as follows. The Fields column of command-palette.csv contains field names separated by ';'. This column is read and any string within the Fields column that doesn't match a FieldType entry in metadata-field-loading.csv is added to FieldName and FieldType, with FieldID left blank.

Session Initialization

Also at session start the application parses command-palette.csv as follows. It constructs a list of unique action words from the Actions column of command-palette.csv and does the same for the Objects column. Hence three tables are stored in session state memory: FieldNames, Actions and Objects.

User Interaction

The command palette UI has three fields: Actions, Objects, Fields. The user can type multiple entries into each field, separated by commas.

As the user types into the action field the application searches the table of Actions to find a match (using fuzzy matching). Each Actions word match is used to find entries in the command-palette.csv table which have that Action word in the Actions column. The same is applied to Objects.

As words are typed into the Fields field the application searches the FieldNames table for a match (using fuzzy matching). Each match is used to retrieve the FieldType which corresponds to the FieldName and then identify commands in command-palette.csv which have the FieldType in the Fields column.

Result Ranking

Results are ranked according to the following algorithm. All commands which have at least one match are given a score according to the number of matches for that command. The results with the top score are displayed. Within the results the Weight field in command-palette.csv is used to rank the results, from highest weight to lowest.

Additional Features

The command palette has other buttons: Name/Description Search, All, Recent and Favorites.

Form Pre-Population

When a command is selected, if the ActionType is FORM then the FieldId and FieldName values are passed on to the form and the corresponding field pre-populated when the form is displayed.

Explanation of Edit Doc File Data Page

Form Function Overview

The edit-doc-file-data form functions as follows. The API call to a doc-file-form-values endpoint returns an array which is passed into the formFields array. It includes a field 'Field Type'. The value of the 'Field Type' is mapped to the 'Field Type' column in doc-file-form-field-routing.csv to determine the behaviour of the field and the associated buttons. Each row in doc-file-form-field-routing.csv contains the information for making API calls initiated by the buttons, and also the API for populating dropdown lists. The data in form-field-routing is also used to customise the function of each field on the form.

ID Type

Each field on the form is either a Document type field or a File type field. A field will be one or the other but never both and never anything else. This is defined in the 'ID Type' column of the table. The purpose of the 'ID Type' is to determine whether to use the documentId parameter name or fileId parameter name when making an API call. Every API call initiated by one of the field buttons includes the ID Type parameter name, either documentId or fileId.

Data Type

The next column in the CSV table is 'Data Type'. This determines how the field is managed. The different Data Types are explained in the Data Type Details section below.

Name ID Parameter

The next column is 'Name ID Parameter'. Where this column contains a value, the value is the name of the second parameter which must be passed when an API call is made. If it is not present in the table then it is not relevant to the API calls. The 'Name ID Parameter' is the name of the parameter for which the value is stored in formFields as 'Name ID'.

Attribute Parameter ID

The next column is 'Attribute Parameter ID'. The value in this column is the name of the third parameter which may be sent with API calls where applicable. The value assigned to this parameter is the ID in the form field which is to be sent to the API. The 'Attribute Parameter' is the name of the parameter which points to the value in the 'Value' field of formFields. An API call will require either an Attribute Parameter ID or an Attribute Value, but never both. Which one is required depends on the data type.

Attribute Value

The next column is 'Attribute Value'. This column is the name of the parameter which contains the value to be sent with an API call where applicable. For some data types there is no Attribute Parameter ID and only the value is to be sent.

API Route Columns

The next four columns are the routes for API calls. Create, Update and Delete act on data. Read reads the data to populate a dropdown list.

Create

'Create' is the route to the call to create a new field link in the database. The field on the form is merely a representation of a form template. There may or may not be a corresponding field record in the database. The Create function is used to create such a field. Some fields (Transaction Group, Lock Status, Filename) are permanent, hard-coded in the database and hence the Create API is not relevant. In those cases there is no entry in the Create column of the table.

All Create API calls require the ID Type parameter of either documentId or fileId plus also the Name ID Parameter, plus also either an Attribute Parameter ID or Attribute Value.

If there is a value in the 'Record Name ID' field of the data then this indicates that there is a record in the database, except where it is not applicable. The Record Name ID is not applicable for cases where the 'Name ID Parameter' field for the applicable 'Field Type' in doc-file-form-field-routing.csv is empty. If the 'Create' column is empty then the field is a type for which the creation of records is not applicable.

For example, for the 'Field Type' of 'Filename', the value can be changed but never created or deleted. The Filename can only ever be updated. However for a 'Field Type' of 'File Free Text' for example, a record for a particular Name ID cannot be updated if a record has not already been created. If a record does not already exist for a 'File Free Text' field then Delete and Update are not applicable.

Read

The Read column contains the route for the API call to read the contents for a dropdown list. All of the APIs for Read routes ending in 'read-by-list' require the 'Name ID Parameter'. All the other APIs for Read routes do not require the 'Name ID Parameter'. If the Read column is empty then no Read route or dropdown list is applicable for that Field Type.

Update

The Update column contains the route for the API call to update the contents of the field. Not all fields require an Update API since only Add or Delete are applicable.

All Field Types for which an Update route is supplied — except for Document Transaction Group, File Transaction Group and Document Lock Status — require all three parameters to be passed to the API: documentId or fileId; 'Name ID Parameter'; 'Attribute Parameter ID'. The transaction group fields require the Document ID or File ID, plus the Name ID Parameter, which is 'transactionGroup'. The Document Lock Status Update route only requires the documentId parameter.

Delete

The Delete column contains the API routes for record delete functions. All of the delete APIs except for 'Document Lock Status' and 'File Transaction Group' and 'Doc Transaction Group' require all three parameters of documentId or fileId; 'Name ID Parameter'; 'Attribute Parameter'. The 'Document Lock Status' delete API only requires the documentId and the Transaction Group fields only require the documentId or fileId as applicable.

Data Type Details

A 'Data Type' of 'List' is a dropdown list from which a single element can be selected. A 'Data Type' of 'MultiSelectList' is a dropdown list from which more than one element can be selected. All List types have a read API which returns the data for populating the dropdown list.

All of the List Data Types except for the Transaction Group types return an array which includes a field 'Object ID' and another field 'Name', among others. The Transaction Group Data Type read APIs return an array which includes 'Transaction Group ID' and 'Transaction Group Note'. In both cases the ID must be stored in the background and used as the Attribute Parameter value in API calls. In the dropdown lists, for all cases the 'Name' value returned by the API is what is to be listed in the dropdown box.

A 'Data Type' of Text is a free text field; Date is a date; Integer is an integer; Real is a real number; Value is just a text string but is not a free text field. The field of Value is not editable. It is like a dropdown list but is not treated the same way.

Button State Management

Earlier it was mentioned regarding the logic for establishing the absence of a corresponding field record in the database. Hence if a corresponding field record is not present then all buttons must be disabled until the user interacts with the field. When the user starts interacting with the field then the 'Add field' button must be enabled, but not the other buttons. The 'Add field' button then calls the Create API route using the data from the field, either a value that has been entered or the ID of an item selected from a dropdown list, as applicable.

The state of the presence or absence of a corresponding field record in the database is to be stored in the background as an array so that the doc-file-form-values endpoint does not need to be called again. All these values are to be reset when the doc-file-form-values endpoint is called again when the page is refreshed.

Delete Field Button

The 'Delete field' button must be permanently disabled for any 'Field Type' which does not have an entry in the 'Delete' column in doc-file-form-field-routing.csv. Otherwise it must be enabled whenever the logic is true that there is a corresponding field record in the database, as per the logic mentioned earlier. Note that the Delete function is not related to deleting the contents of the field but deleting the record that it relates to.

Save Value Button

The 'Save value' button must only be enabled when there is a value in the field AND the logic is true that there is a corresponding field record in the database. Remember that if a value is entered into a field AND there is no corresponding field record in the database then the applicable button is the 'Add field' button.

Revert Value Button

The 'Revert value' button is to revert the value in the field to the original value before the user started interacting with the field. However this is to reset when an API call is made. The 'Revert value' button does not make an API call.