Welcome to Alchemy Configuration Portal User Manual!
This document will guide you through the Configuration Portal, a tool that enables the configuration of processes reflected in the Alchemy User Portal.
Configuration Administrators (Admins) will use the Configuration Portal to configure custom process and record templates to fit the needs of your organization. In the User Portal, these configured templates allow users to capture their work in a structured and predetermined way.
This manual will help you navigate the Configuration Portal and learn best practices as you set up your organization's workspace.
After logging into Alchemy, Admins can choose the UAT version of their tenant from the dropdown list at the top of the blue navigation panel.
From the UAT tenant, click on the profile icon in the lower left corner of the gray navigation panel and select Configuration to open the Configuration Portal.
The Alchemy Configuration Portal is divided into seven sections:
These sections are used to define custom content and manage general settings, users and user group identifiers (tags).
The Home Page shows the status of any configuration work. Here you will see if there are any invalid templates, changes to templates that need to be published, or templates that must be back propagated to all historical data in the system.
The Process Templates and Record Templates sections contain the data elements commonly used across the organization, such as standardized flows, entry forms, test methods, evaluations, documents and databases.
The View Templates section is where standardized data reports and visualizations can be created and shared with certain users or tags.
The Tags and Users sections are tools for managing the users, as well as how they interact with each other and with the portal across different user groups.
The Company section is used to set basic information related to your organization, such as the name or logo that will be shown in the User Portal. A theme can also be applied to input field types to save you time when configuring process and record templates.
Alchemy configuration data should be based on your documents, forms, work patterns, templates, data capture, users and user groups.
Configuration data contains:
These templates and privileges make up the configuration data which is then accessible by the users in the User Portal. Based on tags and privileges, the user will be able to see or edit the data.
System data is made up of configured templates and their inputs from users in the User Portal. The system stores:
While configuring, all changes to record, process and/or view templates are actually made in the 4UAT tenant. In order to see these changes in the User Portal, they should be pushed from the 4UAT to the main tenant. This is enabled by an Integrated Configuration Environment. Changes made to these templates in the 4UAT tenants are automatically saved. However, these changes are not yet available on the User Portal. Prior to pushing the changes to the main tenant you need to do the following steps in the 4UAT tenant:
Steps 2 and 3 are done from the Home Page of the Configuration Portal in the 4UAT tenant.
First, verify configured work by clicking the Verify button in the upper right corner of a Record, Process or View Template. Alchemy is checking all expressions in the template for any errors. If there are errors, the template will not verify successfully and a pop-up message will display with additional information so issues can be resolved.
Templates that contain errors will be shown in the Invalid Templates section of the Home Page of the Configuration Portal. Once all errors have been resolved and the section is empty, continue with publishing template changes. Subsequent steps will not be active until all issues have been resolved.
All the changes made to the Record, Process or View Templates need to be published in order to be applied to the environment. Altered, unpublished templates will appear in the New Changes section of the Home Page of the Configuration Portal.
When you create a template for the first time, it will be visible on its respective template's landing page. However, it will not have a Last Published Version until it has been published for the first time, when it receives a Version 1. Each time you make a change to a template and it is verified and published, it will get a new version number.
All templates that are not published, after changes have been made or published for the first time, will appear in the New Changes section of the Home Page of Configuration Portal in the 4UAT tenant. In order to publish them you need to press the Publish button.
After you have successfully Published all Record and Process Templates from the New Changes section, they will appear in the Back Propagate Section and the Publish button will become disabled.
New records, processes or views will have the latest changes when the instance is created in the User Portal.
To implement changes to previously existing template instances in the User Portal, click the Back Propagate button. By doing so, the system will start applying changes to all records, processes and views existing in the system that are created using templates listed in the Back Propagate section of the Configuration Portal home page.
This action may take several minutes, depending on the amount of data that exists in the system. You can track the progress of Back Propagation through the Tenant Status. Hovering over this area will provide an indication about how many template instances are left to be upgraded.
During Back Propagation, the tenant will show its status as Busy. While the tenant is in this state, configuration work can still be done but you can not add new Users or Tags, nor do another Publish and/or Back Propagate until the previous one is finished.
It is a good practice to Verify, Publish and Back Propagate changes you make in the templates frequently while configuring, and afterwards, checking the effect of the change in the User Portal. This way you are verifying and checking smaller pieces of work, and you can discover and correct any errors quickly and easily.
There are certain considerations that you should take into account while making changes in the configuration portal and back propagating them. This process can be complex and sometimes it requires to be executed in phases. Some guidelines, rules and examples are given in Appendix E - Back Propagate Properly.
After Verify, Publish and Back Propagate steps are finished, changes are applied to the 4UAT tenant. To transfer these changes to the main production tenant, follow the steps given below:
After all actions have been successfully pushed to the main production tenant, the Actions Log will be empty and changes will be visible in the User Portal.
Changes made to users, creation of user tags and assignments are automatically saved in both environments and do not need to undergo the Verify, Publish, and Back Propagate process.
Users are all the people who will have access to the system in the User Portal.
The Users tab is a table that displays information of Alchemy users who have been added to the system by an Administrator. Information includes:
Sorting options are available for each column and are accessed by hovering over each header.
To create a new user in the tenant, click + New User in the top left corner. This opens a New User modal (Figure 2.2).
Add a user email to the required field and click Save.
Note: The email address must be unique for each user.
Once saved, the user will get an activation email from Alchemy and can follow the steps provided to log into the system.
The user's email address will then be displayed in the list of users in the Configuration Portal. The first and last name will not appear for the user in this list until they log into the system for the first time and are prompted to provide this information.
Clicking on the row of a user will display a user menu in the right side panel (Figure 2.3).
Two sections of information are displayed. Under the Properties tab, displayed user information includes:
User Tags are broader groups that users belong to. It can be based on a function, location, expertise, seniority, knowledge area, etc. Multiple tags can be assigned to one user while multiple users can have the same tag(s). By adding a tag to a user, Alchemy will recognize a set of defined privileges. Additional information can be found in Section 3 - Tags.
The User Tags tab of the panel displays all assigned tags for the user. Additional tags can be added by clicking the + Assign Tags button. In the modal that opens, select one or more tags and click the Assign Tags button in the bottom right corner. There is no limit to the number of tags a user can have.
Newly assigned tags will now appear in the displayed list.
In Alchemy, tags are used to categorize users in a way that is relevant to an organization such as by function, location, department, product, or process. They are a powerful, yet flexible tool used to define user privileges and actions, and in turn how the users will interact with the system.
It is important to note that one tag can be applied to several users while a single user can have multiple tags.
From the Tags landing page, click on + NEW TAG in the top left corner. A modal appears with required fields for:
The Tag Identifier will automatically populate with an input based on the chosen tag name. Changes can be made to the identifier based on the rules outlined above, however it is strongly recommended that these two fields be as similar as possible.
Tag Identifiers must be written in CamelCase, which is capitalizing each word and removing the spaces between them (e.g. LabManager, OhioLab, FloridaHQ, TechServiceDept).
An Identifier is very important in Alchemy’s Configuration because every process, record, field, or group of fields has its own unique Identifier. The system uses these Identifiers to distinguish between different types of items, or between different items of the same type and uses them in order to perform filtered searches, calculations, triggered actions, etc.
Users can be assigned to a tag once it has been created. Click the tag name from the list on the landing page. This populates the right side panel with the tag overview information. Beneath the Users section, click + TAG USERS.
This will open a menu where you can select as many users as you wish. Alternatively, you may assign tags to a user directly from the Users Page.
Functions
Attached to users based on their function in your company. They are named according to the job titles of the employees. Examples include: Chemists, Lab Manager, Sales, etc.
Departments
Attached to users based on the department of your company they belong to. They are named after the departments in your company. Examples include: Synthesis Lab, Application Lab, R & D, Production, etc.
Geographies
Attached to users based on the location where they are working. These are named according to how your company views these geographies. Examples include: the Americas, EMEA, NewYork, London, etc.
Records are digital models of documents, spreadsheets, data input forms and images that the user fills out to complete their flow of work.
Record Templates are the blueprints used to create Records in the User Portal. In Alchemy, a different record template will be designed in the Configuration Portal for each set of data an organization needs to collect.
Depending on how the Record Templates are configured in the Configuration Portal, in the User Portal records can be created in two ways:
All record templates that you create will be stored in the Record Templates section of the Configuration portal.
The Record Templates landing page has the following features and information:
Record templates can be imported to an environment via a .json file that was previously exported from another tenant. From the Record Templates landing page, click Import Record Template to open a modal. Within the modal, copy and paste the text from the .json file and click Import.
To export a record template, use the record template menu icon for the selected template and click Export Record Template. This will open a modal with the template displayed in .json formatting. Click Export Template to download the file to your computer.
Any changes made to the file should be done through a plain text editor to prevent invalid conversions to the template which may impact your ability to upload the file to a different tenant at a later date.
To create a new record template click on + NEW RECORD TEMPLATE from the landing page. Enter a name and identifier in the modal.
As explained in Section 3 - Tags, the Record Template Identifier follows the same creation rules as the Tag Identifier. The unique identifier is used by the system to reference a record template within a process, create it or access data from it.
Certain words and phrases cannot be used as identifiers for Record Templates and Record field types. They are reserved by the system to use in different formulas and include:
• Name
• Status
• Template
• Stage
• Process
• CreatedOn
• CreatedBy
• Id
• ParentProcess
Once both fields have been filled out appropriately, click Save to create a blank record template.
In the right-side panel, there are two tabs:
If privileges are set for a record template, it can be created by those users in the User Portal as a solo record that is not linked to any process in Alchemy.
Privileges are set using User Tag Expressions. They define which users will be able to access this Record Template to create and view records. More about setting privileges will be discussed in Section 5.3 - Privileges.
Solo records require an alphanumeric field to be added to the template with an identifier of RecordName. Without this field in the configuration, the record template will not be able to be used outside a process.
If privileges are left blank for a record template, it implies the template will be placed inside a Process Template. The process template consists of Stages. Record templates are placed within those stages. More information can be found in Section 5 - Process Templates.
The Record Template Configuration page has the following features and information:
Configuration of the record template occurs in a grid. The grid is the working space for creating the digital record. Each template is built by placing fields on the grid.
Fields are the building blocks of any record template. There are multiple field types that have different use cases. These field types will be explained in detail in Section 4.4 - Field Types.
To delete a record template, navigate to the configuration page of the desired template and complete the following steps:
A record template can only be deleted from the Configuration Portal if there are no instances created from the template in the User Portal.
As previously stated, fields are the building blocks of any record template. This section will cover the role of fields within a template and how to properly configure a record.
Alchemy provides guidelines for how the fields should be designed within the template to provide the optimal experience for end users filling out these digital forms. Refer to the Field Property Guidelines design document for additional information.
Prior to building in the configuration portal, consider which fields will make up the contents of the record template. We recommend using the template referenced in Section 8 - Design Templates.
To add a new field to a record template:
A New Data Field modal will appear. Fields include:
These fields must be unique on the Record Template level. If you try to create two fields with the same name or identifier, Alchemy will warn you and your changes will not be saved.
Once a valid name and identifier have been added, click Save. The field will appear on the grid and a panel on the right-hand side will be populated.
Fields can be rearranged by dragging and dropping to a new location on the grid. Moving multiple fields can be done by holding the Shift key while selecting each field or by clicking and dragging the mouse over an area of the grid where the fields are located.
For more precise positioning of a field, move the selected field using arrows on the keyboard. When moving a field, it will always snap to the upper left corner of the target position on the grid. Moving a field outside of the grid borders will return the field to its original place. See the before and after grids in Figure 4.8 and Figure 4.9, respectively.
Before:
After:
The pink area displayed around a field is its margins. Margins can be adjusted for every field in any of the four directions. If the fields on the grid are not separated by margins between them, in the User Portal they may appear stuck together.
Areas on the grid that are not occupied by fields or their margins are blank. Blank rows and columns on the grid appear to separate fields in the Configuration Portal, but in the User Portal, these blank areas will be rendered differently. If the whole row on the grid is not occupied by field or margin, it will not be shown in the User Portal.
There are privileged directions in the grid - first, the field goes left and then up if there is empty space that is not occupied by the field or margin.
To make sure that the layout in the User Portal is the same as the one you configured, use margins in the necessary direction.
In Figure 4.10, fields are separated only by blank rows and columns with no margins around the fields. See the difference between the Configuration and User Portal.
In Figure 4.11, fields are separated by an added margin of 5 in the Configuration Portal. See how fields are separated in the User portal due to the added margin.
Margins can be adjusted in the right-side panel under the Design tab.
The same principle applies to fields that are placed next to each other. Fields in the User Portal will appear stuck to each other if not separated by left or/and right margins. When adding margins to fields in the Design tab, you can type in the desired number of squares for margins, or use the + and - buttons to adjust the margins gradually.
If you have a need for the margin-left to be 13 squares but you only have 10 available on the grid, adding the additional three squares in the design tab will not override the grid configuration. The User Portal will render the template with the 10 available squares for the margin of that field. This is applicable for margins in every direction on the grid and should be considered when placing fields.
Field size can be conveniently changed by clicking and dragging the lower right corner of the field. Another way to adjust the size of a field is by changing the field width and height in the Design tab.
When adjusting the size of the field in the Configuration Portal, the field should first expand to fit the entire name of the field, then expand for the input section (field identifier). The size of these areas will be preserved on the User Portal. If a user enters text that needs more space than what is set for the input section, a vertical scroll bar will appear, while the size of the field remains the same.
To delete a field in a record template select the desired field and:
Fields can also be copied and pasted into another record, even across different configuration environments by completing the following steps:
The field name and identifier will both begin with Copy of [Field Name or Identifier] but can be updated in the Functions tab of the field, along with any other inherited properties.
Each field has a properties panel that appears, when selected, on the right side of the configuration window. In this panel is a Functions tab.
Most of the settings in this tab are the same for each field type. Common fields will be explained in this section while future sections will discuss specific use cases for each field type, if applicable.
Visibility Expression - A field can be displayed in the User Portal if specific conditions are met. For example, a pH value field can become visible when a pH test is selected. When a pH test is not selected, the field is hidden from view. A field visibility expression is written in the form of a formula and returns a boolean value (true or false), which determines if the field displays in the User Portal. Visibility expressions will be explained in more detail in
If a user makes a previously visible field invisible, any data that may have existed will be deleted from the record.
Formula Expression - To give the field a calculated value, users can write a formula in this field by following the guidelines from Section 7 - Formulas. Additional examples can be found in Section 4.6.3 - Formulas in Calculations.
In the record, Characterization Tests, chemists are doing three measurements for the pH values of a solution and then calculate the average of those three results. The input field identifiers are: pHResult1, pHResult2, pHResult3.
For the input field identifier, FinalResult, write the following expression in the Formula Expression field: (pHResult1 + pHResult2 + pHResult3)/3.
Reportable - Under this field there are 3 available options:
Field Helper Text - Text entered in this field will be visible in the input field in the User Portal prior to any data entry.
Field is Editable - Enables the user to edit the value in the User Portal if checked. If the checkbox is unchecked, the field will not be editable in the User Portal, with the value given by calculation.
Required - Checking this box will make the input for the field required in the User Portal. Visually, the field name in the User Portal will have a red star and the field will be framed in red to indicate that input is required.
Allow Multiple Values - Checking this box will allow a user in the User Portal to select multiple values. Selected values will be displayed separated by commas. This is applicable to values of Alphanumeric, Number, Attachment, User Reference, Process Reference, and Record Reference field types.
Cloneable - When a user in the User Portal clones a record, if this box is checked, the value of the field will be copied to the cloned record. Users should uncheck this box in the event the record is cloned and the field needs a different value. In this case, only the blank field will be cloned to the new record.
Certain fields should not be marked as cloneable when configuring record templates, such as:
Instead when a record is cloned only the relevant fields, and not their data, will appear in the new record.
Printable - This box is checked by default and determines whether the field will be shown when printing the record. If unchecked, the field will be visible in the User Portal but will not be not printed, with a blank space displayed instead.
Hidden - Checking this box will prevent the field from being displayed in the User Portal. However, hidden fields will still have values. This is useful for intermediate calculations or filtering that is irrelevant to the user.
In the record, NPD Request Form from the the New Product Development process, a user might be asked to assess the complexity of a project. You can configure the input field for Complexity to have alphanumeric options: Low, Medium and High. You can further configure a hidden field, that will take the alphanumeric input and convert it to a number:
This hidden field will not be visible in the User Portal, but it allows you to use the numerical values to calculate additional field values for an end score or risks, etc.
A field type defines what kind of input will be required in the User Portal and how it will be saved in the system. There are 15 different field types:
Each field type has additional properties you can define, other than the Name and Identifier.
Note: The button field type will be covered in Section 4.7 - Usage of Formulas in Fields and Groups.
The Label field is the only field type that does not have a corresponding input field in the User Portal. When this field is selected for creation, a New Data Field modal appears where users can input and format the desired text to be shown on the Label (Figure 4.18).
The Label field type does not have an identifier, meaning it does not have to be unique to the record template. It can be used as a headline for another field, section of a record, or table, or provide additional information on the digital form. It is always used for column and row headers when making tables in Alchemy, and sometimes for the label of checkbox fields.
Labels are not visible in Views because they do not contain any user entered information.
If the name of your field is in the form of a question, it is better to uncheck the Show Field Name as Label checkbox and add a label instead. This is usually the case when you are creating a Yes/No or a Checkbox field type.
Label fields can be formatted as rich text. They can contain bulleted or numbered lists, headings etc. Formatting a label will reflect the changes both in the configuration and the user portal.
If you need a border between the label and the input field, hide the field name and add a separate label. Then adjust the borders for each.
The Alphanumeric field type is most frequently used. The input of these fields will be saved as text (e.g., Raw Material, Viscometer, Lot Number). You can define the minimum and maximum number of characters a user can enter in the Advanced Settings section. The default maximum is 255, but it can be increased up to 3000 characters.
While creating the field, you can also select whether the input in the User Portal should be unique. If selected, you can choose the level on which the field will be unique (Figure 4.19).
The levels in which the field must be unique are:
A sales person will fill out the record, Company, when they need to add information about a new company in the system.
In the record template, create a required alphanumeric field named Company Name where the user will fill out the name of the company that they are adding. The value of this field should be marked as unique to the system so only one company with that name exists in the system.
Alternatively, there can be another alphanumeric field named Contact First Name whose value will not be unique on any level. For example, there can be 10 people with the first name “John” working for that company, or in all companies entered in the system.
For alphanumeric field types can limit the input to a list of predefined values. It will be shown in the User Portal as a drop-down list of values, with users having to make one or more selections.
Under the tab, Values, in the properties panel you can add predefined values by clicking on + NEW VALUE. A modal will open where you can enter the predefined value you wish to have, limited to 80 characters per item. After the value is added, it will be displayed in a list under the Values tab (Figure 4.20).
An expression can also be added to predefined values to display a certain selection when other actions are taken in the record.
To allow for more than one selection to be made, ensure Allow Multiple Values is selected under the Functions tab.
An alphanumeric field can be used to create barcodes on your record template. Under the field’s Functions tab, set the desired barcode type from Not a Barcode value to the one you need to configure (Figure 4.21). There are several types of Barcodes supported in the alphanumeric field and are listed in Appendix D - Barcode Types, in addition to the types of characters needed and their limitations.
Once a barcode type is set in an alphanumeric field, set the Formula Expression that will generate a visible and scannable barcode in the User Portal.
Note: When an alphanumeric field is used to display a barcode, it can not have predefined values.
In a Number field users can enter any numerical value in the User Portal. Decimal places are displayed with a dot and must be entered as such in the User Portal.
In the Configuration Portal you can define the number of decimal places that will be visible in the User Portal. This can be set at the bottom of the Functions tab in the field properties panel, under the Decimal Places Format.
Note: In the User Portal, the system will save the full number entered or calculated, preserving all values after the decimal place and using them in further calculations. However, if the entered or calculated value has more values after the decimal place than what is defined, only the set number of values will be displayed and the number will be rounded.
The Number field, like Alphanumeric, can also have a defined uniqueness at the System, Process or Record level.
Under the Functions tab of the number field you can select the Scientific Notation checkbox to show a number in the User Portal in that format.
Minimum and Maximum Values can also be defined if needed (i.e., 1 to 14 for pH, 0 to 100 for percent, etc.)
Predefined Values can also be configured under the Values tab.
Some example of numbers input that should be used in the Alphanumeric field type are:
These values cannot be used in mathematical operations.
Some examples of the Number field type that can be used in different calculations are:
Date & Time is a field in which the user can select the date and time in the User Portal (e.g. , Shipping Date, Sample Received Date). This type of field cannot have multiple values, nor can it have a predefined value list selection.
By default, the format the date and time is displayed is MMM DD YYYY hh:mm. However, this can be changed. To change the format, use one of the corresponding formats in the Date & Time Format field under the Functions tab. See different options for Date and Time formats in Table 4.1.
Date and Time fields can also be subtracted. For example, ProjectDuration = EndDate - StartDate. The field for ProjectDuration needs to be a Number field in order for this equation to work. The result will be presented in milliseconds but can be converted to hours or days by using the appropriate mathematical formulas.
It is common to use the TODAY() function in a date field. This writes the current date in the field when evaluated (i.e. on Record creation, or when the field becomes visible). Remember to check the Field is Editable checkbox below the Calculation Formula so that users can edit the date if needed.
The Yes/No field is represented as a radio button in the User Portal and the value is saved in the system as boolean (true or false). If neither option is selected, the system evaluates it as false.
Admin users can pre-set the value of the field by writing true or false under the Calculation Formula. You can also opt to make this default formula editable.
The yes/no fields are most commonly used as a gate where further transitions depend on the value of this field, such as:
They are also good for dictating visibility conditions:
A checkbox field is represented in the User Portal as a box that the user can mark checked, true, or unchecked, false (e.g. SDS Needed, Customer Notified, Lab Testing Complete).
By default, a checkbox has a Calculation formula false and is editable. This means that in the User Portal, it will be unchecked and could be updated to checked, with the value changing to true.
If a checkbox is set as a required field, it has to be checked by the user in the User Portal in order to complete an action.
For example, selecting a checkbox may complete the stage and allow the user to continue through the process.
As mentioned in the Label field type, if you are making field names that will contain a question, it is better to use a separate Label field for the question and have a checkbox field with the Show Field Name as Label unchecked.
A Rich Text field is used to input formatted text in the User Portal, such as in a description field.
Rich text is different from the alphanumeric field type in the following aspects:
Attachment fields are used to enable users to attach files to records in the User Portal. The file preview size is set by the configured field size. Refer to the Field Property Guidelines for additional information on how to configure the size of the field.
Alchemy supports common attachment file types, displayed as thumbnails, such as:
When you click on the field in the User Portal, the attached images are previewed in a modal window on the same page. For other files the preview is opened in a new tab. The maximum file size that can be attached is 2 GB.
Only one file (Excel sheet, image, PDF, etc.) can be added per field. If you would like to enable the user to attach multiple files, you must enable Allow Multiple Values in the field's properties.
The Record field is used to create a connection with another record to access its data. In the User Portal, the field will be displayed as a dropdown list with all records created from the referenced Record Template. When choosing a record from the dropdown, it will be shown as a hyperlink to that specific record instance.
The create a record reference in the template:
When creating the formulation from the record template, Formulation Design, a Chemist needs to choose desired materials. In the template there is a field, Material. By clicking on that field, a dropdown list of all materials in the database will appear, and the user can choose the desired material.
The Material field type, Record, is referenced to the record template, Main Material (i.e. connected via this field to the database of all Materials entered in the system so far).
Furthermore, the Chemist needs to choose which Lot Number of the chosen material needs to be used in the Formulation. Next to the field, Material, there is a field, Lot Number. Clicking on this field, the Chemist will see a drop-down list of all Lot Numbers created for this Material. This is also of the field type Record and is referenced to a record template, MaterialLot (i.e. connected through this field to all available Lot Numbers.
Under the Functions tab for the field type, Record, an additional section is available called Record Filter Criteria. By setting a Filter Expression, records can be filtered down for the user to select from in the User Portal.
Filter expressions for the field type, record, are written in this way:
As seen in the previous example, the Chemist can choose the Lot Number that needs to be used for the Material in the formulation. In the previous example they chose the desired material from the referenced record template, Main Material.
In this example the Chemist needs to choose the Lot Number from the referenced record template, Material Lot.
Since the user does not know the specific lot number they need, a filter expression is applied to the field, Lot Number, so it only shows Lot Numbers of the chosen material. The filter expression needed is:
Result.Material==Material
What the filter expression does is show only a list of records, Lot Numbers, in which the field Material (Result.Material) is equal to the Material chosen in the actual record template Formulation Design.
Please note that in this example the field identifiers completely match, but that is not always the case.
There can be another type filter expression for the record field where the right side of the expression == is not a field identifier, but the chosen predefined value of the alphanumeric field. This is explained in the following example:
There are two types of products in the Alchemy Coatings Company: finished goods (paints) and sundry (brushes). This is configured in the record template, Product, by setting an alphanumeric field, Product Type, (field identifier: ProductType) with two predefined values: ‘Finished good’ and ‘Sundry’. These values are basically text. Chemist wants to test the pH of the product, but only need a list of products that are finished goods. In the record template, pH Test, there is a record field with the referenced record template, Product.
The needed Filter Expression is:
Result.ProductType=='Finished good'
This expression shows a list of Product records in which the Product Type field (Result.ProductType) is set to (==) a predefined value ‘Finished good’. Since a predefined value is basically text, it must be written using single quotes(‘), otherwise it will be treated as an identifier by the system.
More examples for the Record Filter Criteria formulas are explained in Section 7 - Formulas.
The Process field type is a field in which users can reference a process, accessing a specific process and its system data . In the User Portal, it will be shown as a dropdown list with a link to the process. You can use this field type to create a hyperlink to another process, access data from that process, or if you need system data for that process. System data is further defined in Section 7 - Formulas.
When creating a process field, you have to define which process template you are referencing. For example, by selecting Lab Work as the referenced process Template, the user will see a dropdown list with all the Lab Work processes created in the User Portal.
There are record templates that are standardized across the organization that can be used inside different process templates. If you need a record from a specific process, use the Process field in order to distinguish which process you would like to pull that record information from.
Under the Functions tab for the field, Process, an additional section called Process Filter Criteria is available. Similar to the Record Filter Criteria, you can write Filter Expressions to filter the processes displayed in the drop-down list of the process field in the User Portal. After a process is selected in the User Portal, it will create a link between processes. However, if you check the Allow Multiple Values box, the user will be able to select multiple processes but none of them will be a hyperlink.
Filter expressions for the field type, process, are written in this way:
In the process, Lab Work, there is a record, Work Plan. In this record there is a Process field with the Name, Related New Product Development (identifier: RelatedNewProductDevelopment). In this field the Chemist is choosing the process, a previous New Product Development instance, which is connected to the current Lab Work process on which they are working. To filter down all possible New Product Development processes to just completed ones, write in the Process Filter Criteria field:
Result.Status == 'Completed'
The keyword Result is used to filter down processes. Status is the property according to which the system needs to filter and 'Completed' is the value for the filtering criteria.
After you have made a Process field, it can act as a connection to pull the specific record from the referenced process. Through that record, you have access to its system fields and can use it to access another record from that process, or as a filter in record field drop-downs. More on this is explained in Section 7 - Formulas.
The Parent Process field is a step toward implementing the hierarchy between Processes. It will help in better understanding of data hierarchy and link among the processes.
The Parent Process field will be a field with a reserved field identifier, ParentProcess, positioned in the process creation record (i.e. the record with reserved ‘Name’ field from which the process is drawing its name). This identifier should be used on a process reference field and its value will be a reference to the parent process of the process on which this field is positioned, thus creating the parent - child processes link.
There are certain requirements that must be fulfilled. Namely, one child process can have only one parent process, but one parent process may have multiple child processes. Hence, the Parent Process field cannot have multiple values, neither can it be positioned within a repeatable group.
The User field type is used to reference users in a record and displays a list of users in the User Portal. In most cases, this list needs to be filtered in order to show only users of interest.
If the filter is not defined, a dropdown menu in the User Portal will show the complete list of all system users. Filter Expressions for the User field follow the form:
While approving the Lab Work record request, the Lab Manager needs to assign the lab work to a specific person. In the record template, Lab Work Approval, there will be a User field with the User Filter Criteria set:
Result.UserTags==Tag[Chemist]
This expression will filter the list of all users in the User Portal and will only show users who have the Chemist tag.
There are some words and phrases that cannot be used as Identifiers for User fields. They are reserved by the system to be used in different formulas. These are:
The Link field type is used to paste URL links which lead to a new website. In the User Portal, the user can define the Link Text and Link URL by clicking on the field. The entered link text will be blue and clicking on it will show three available options: go to link, change, or remove. Choosing the option, go to link,Ç will open a new browser tab and load the defined webpage. See how the Link field type looks in the User Portal in Figure 4.23.
Multiple links can be enabled by putting this field inside a Repeatable Row group, similar to an attachment field. Additional information can be found in Section 4.6.2 - Repeatable Row.
The Link field, like the Alphanumeric, can also have a defined uniqueness on the System, Process or Record level.
The Image field enables users to upload an image in the Configuration Portal. This image will always be shown in the User Portal and the user will not be able to change or edit it. Uploaded images are automatically resized to fit the size of the image field.
When uploading a picture to the image field, the picture size must not be greater than the image field size. Each "box" in the configuration portal equals 8 pixels. So if you want to upload a picture of 160x80 pixels, the image field in Alchemy must be at least 20 x 10 "boxes''.
This field is mostly used to attach an image of a company’s logo to records that need to be printed.
The Chemical Structure field type is used to create a space in the record template where users can draw chemical structures in the User Portal.
In addition to fields you can also add a page break anywhere in your record template. This element has no additional settings and is represented by a simple blue line in the configuration portal.
This element is not shown in the User Portal, and its function is to move all the fields below to a new page when using the print record option in the User Portal.
In the section, Company, of your Configuration Portal you can set a Theme. Here you can pre-set the default layout for all field types. You can expand each field type and set the properties for each. Once complete, each time a field is created in the grid, it will have the settings configured in the Theme. In the Appendix C - Configuration Styling Guidelines, rules are given regarding the field layout for each field type.
Themes can be imported or exported between tenants.
Field Groups in Alchemy are used to connect multiple fields in a certain context. They are used to define how fields are treated in the system. When a group of fields is wrapped in a field group, the system will put them all into one connotation.
There are three different types of groups: Simple, Repeatable Row, Repeatable Column. Each type will be explained in further sections.
They can be created in the Configuration Portal in a few simple steps:
Each group type has special setting requirements for margins that will be explained in the following sections.
Both fields and their margins have to be placed inside the group lines. If either field, or a margin of any field is extending outside of group outlines, unexpected behavior might occur in the user portal.
When you add a Simple group on top of fields, always make the size of the group a little bit bigger than the borders of the fields (or better yet, the largest field inside the group). This is shown in Figure 4.26 - the darker gray square is bigger than the fields inside it.
Repeatable Row groups make a larger group by one square on the right side, so the width of the group should be: width of the last field + 1.
For the Repeatable Column group, make a larger height of the group by one square on the bottom, so the height should be: height of the field + 1. This is useful because it will be easier to select just the group to change settings, as well as each separate field inside the group.
When you want to move the field group on the grid, the fields inside it will not move with the group, they need to be moved separately.
The Simple group type is used to associate fields together in these cases:
In the right-side menu, groups also have different additional options, just like field types have. In the Functions tab for the Simple group type, you can set the Field Group Visibility Expression (Figure 4.27).
The Design tab is for setting up group width, height and margins. Margins can be added to groups, and the fields inside the group can have margins of their own. However, remember that the group needs to cover the whole field with its margins in order for the rendering and calculations to work properly.
In the User Portal, the evidence of groups is subtle. When the Field Physical Properties Needed (Figure 4.26) is checked, the three fields inside the group with the visibility condition PhysicalPropertiesNeeded == true will appear. The user will not see any borders around groups, nor the dark square fill.
Multiple fields in the record, Characterization Tests, can be grouped together. Properties like pH, Density, and Viscosity can be grouped inside a simple group. In addition to being related to the same topic, all these fields need to have the same visibility condition. In the group's Function tab, in the Visibility Expression field, write the condition for the visibility (e.g. PhysicalPropertiesNeeded ==
true
).
The margins of this group can also be set so all the fields inside the group will have the same margin.
As previously mentioned, Visibility Expressions can be set for the field in the same way it can be set for the group. In the text below, it will be explained for the field, but the same principle applies for setting the visibility condition for a group.
Field Visibility Expressions are written in the form of a formula, using a Field Identifier, operator (such as ==, IS SET, NOT SET, IN, NOT IN) and a field value. Field identifiers and field values are chosen depending on the desired condition of the visibility. A complete list of available operators is given in Section 7 - Formulas.
The most common use cases of setting the field Visibility Expression are:
CheckboxIdentifier
== true
YesNoIdentifier
== true
AlphanumericIdentifier
== ‘predefined value’
A Chemist is filling out the Characterization Tests record, and they are choosing tests to be performed. There is a list of tests and next to each test there is a checkbox that needs to be selected if that test is needed.
In the User Portal, a field where the test result can be entered should be visible only if that test is selected. The identifier of this checkbox field is pHNeeded. The field where the user should write the result for the pH test has the name, pH Test Result, and the identifier, pHTestResult. In the Functions tab of this field you will put the Visibility Expression:
phNeeded == true
In this case, only when the checkbox pH is selected will the field for entering the result will be visible.
Fields can be used in calculations only if the visibility condition is true. If that field is used somewhere else in the calculation formula, the calculation is triggered only when the field is visible.
This is different from the hidden fields, since hidden fields are only not shown on the User Portal.
In addition, each field that is used to set the visibility expression can be located in a different record template than the one where visibility is being set. To achieve this, there needs to be a connection between the record templates - through a record field type. The form in which visibility expression is written is similar to that of a Filter Expression. There is a Record Template Identifier and then a dot (which brings up the exact location on the referenced record template), after which comes the Field Identifier, expression == and at the end, the value of that field required for the visibility.
In the record, Work Plan, a Chemist chooses the tests to be performed by selecting the checkboxes (identifiers: pHNeeded, DensityNeeded, ViscosityNeeded). Later in the record Formulation Design, they will fill out the results. The fields for entering the results should be visible for those tests which were selected in the Work Plan record.
To configure this you need to set the connection between the record templates, Formulation Design and Work Plan. In the record template, Formulation Design, make a record field, Related To Work Plan (identifier RelatedToWorkPlan) and select the record template Work Plan as a referenced record template.
The field for entering pH Results (pH Result) should have the following visibility condition:
RelatedToWorkPlan.pHNeeded == true
The same goes for the other result fields (Density, Viscosity) using the appropriate identifier.
This way, the field's visibility can depend on the selection in the other record template.
There are also various operators available that can be used in Visibility Expressions that will explained in later sections.
You can delete a simple group in the same way a field is deleted:
Deleting the group will remove the group only, while the fields inside the group will remain.
You can Copy/Paste a group by selecting it, right-clicking the mouse and choosing Copy/Paste. This action will paste only the group, not the fields inside the group. All the settings will be copied, including the design elements, as well as the visibility expression.
If you want to copy/paste more fields, or fields and group(s) you can do that by selecting all the fields/group(s) together. Right-click the mouse and select copy/paste. Selecting multiple fields and/or groups is done by pressing shift+left click on each desired field/group or selecting the area of the grid where the desired fields/group(s) are.
The Repeatable Row group type is enabling the fields inside the group to repeat under each other in rows. Use cases for the Repeatable Row groups are:
All field types, except labels, can be placed inside a Repeatable Row group. The Repeatable Row group is created the same way a Simple group is created. The gray square that appears has slightly bigger dimensions, and the Functions tab has an additional field called Repeatable Options explained in the next subsection.
While configuring, be careful when adding groups (simple or repeatable row/column). Check that groups located next to each other are not overlapping in any part. Overlapping of groups can create bad behavior in the system.
Tables in Alchemy are built horizontally OR vertically. They cannot be expanded in both directions at the same time. Creating a table in Alchemy consists of two parts.
Let’s say you are configuring a table with several columns, and you expand it vertically repeating the rows below each other. First you need to create the column names, by creating the desired number of Label fields. All labels should be either in a simple group, o outside of any group.
The next set of fields are the input fields that will be placed under the labels on the grid, with each field under its corresponding label. These fields will be placed inside the repeatable row group because you want just the input fields to repeat, not the labels. Since these input fields have their names in the labels you just created, the box Show field name as label should be unchecked. However, the field names will be visible and available in the View Templates, so make sure they are also self-explanatory.
To create a table in Alchemy:
In the Functions tab of each Repeatable Row group, there is a field called Repeatable Option where you can choose different options from the dropdown list. Options include:
Choosing the option Defined by User, will allow the users in the User Portal to add as many rows below as needed by clicking a “+” Row button.
Other three options are for making the tables where users can not add rows. These types of tables are automatically created by the system in a way that is configured in the Configuration Portal. Tables determined by Formula, Record Reference and Filter will be explained in detail in the ADVANCED section.
This is one of the most frequently used tables in Alchemy. A user is allowed to add as many rows as they need, or to delete or clone rows using the appropriate icons. The options, delete and clone, are available when multiple rows are selected as well.
Rows can be rearranged in the table by using the drag-and-drop icon. Because of these additional icons, you need to set the left margin of the repeatable group to 13 in order to display them all in the User Portal.
To create a Repeatable Row group, follow the same steps as explained for creating the Simple group.
First create Label fields for the column headers. Then create fields that will be repeated in each row and make sure Show field Name as Label is not selected. To create a group, left click on the grid and choose Repeatable Row. Set the Name and Identifier of the group, and then the size and margins. Position the group over the fields you want to repeat. It is advisable to have the group slightly wider than the field so you can select the field easily, if needed.
If the Repeatable Row group has the Repeatable Option set to User Defined, the Left margin needs to be minimum 13. If you place the above labels for column headers in the Simple Group - the same rules apply to the Simple Group: Left margin 13. If you leave the labels for column headers without the simple Group on top, you should have an additional Top margin set to at least 3 in the Repeatable Row group.
If the group has any other Repeatable Option set up (Determined by Filter, Formula or Record Reference), minimum margins on the Left need to be 5.
The reason for the extra margins is that the additional select options and controls are visible in the User Portal and in order to display them properly, you need to set more space for them.
In Appendix C - Configuration Styling Guidelines are given rules regarding field and group layout for each type. Some general rules regarding table layout and best practices are also included.
To make a characterization table in the Characterization Tests record template, first think about what columns you would like to have in the table. As explained, make the labels of the table and put them inside a simple group (Left margin on 13 to align with the rows below).
Next, make the input fields. In this example, all input fields will be a number field. Make a repeatable row group, choose User defined and place it over the input fields. In the user portal, Chemists will add as many rows as needed for their characterization measurements.
Borders should be added to the field cells in the table but you should not duplicate them. If you put all four borders on the first field of the first row, then on the second field, one border is already shared with the first field, so you would need to add only the remaining three borders.
In the second row the first field has a shared border with the field above, but the field next to it already has two borders shared with the field above and before it. In this case just two additional borders are needed.
Make sure the same visibility expression is set for both parts of the table: simple group (where the labels are) and for the repeatable row group (where the input fields are). It is possible to set visibility expressions for each label and input field individually, but it is best to wrap all labels into one simple group and all input fields into one repeatable row group and set the group visibility for each.
If you select Determined by Record Reference, additional fields for Referenced Record Template, Referenced Record Fields and Filter Criteria will appear. With this repeatable option, your goal is to connect two different records, from the same or different processes, and pull the required data. To explain this better, imagine you have two records, R1 and R2. You are currently in the R2 record making a table where you want data from the R1 record to be copied.
Following the theoretical example in the previous section, users can make a table that allows them to pull information from other records into a table. The table is automatically filled and it accesses data from created records. It will have as many rows as there are records created from the referenced record template in the Repeatable Row option, related to the record template where the table is.
A chemist is making a plan for the experiments. They are doing a lot of literature research on the internet.
You want to configure a record template, Work Plan, where a chemist can describe all the work that needs to be performed and have all literature searches (scientific articles, web pages, etc.) in one table, related to one Work Plan.
To parallel the theoretical example from the previous section, Work Plan is record template R1, and Literature Search will be record template R2.
From the above example, in the Work Plan record there will be a table with as many rows as Literature Searches related to that Work Plan that are created. See Figure 4.31 for the graphical presentation.
Now that the two tables are connected, or bound to each other, users can access other fields from the Literature Search using the keyword Item followed by dot and an identifier of a field from RT Literature Search that you want to pull in the table.
Since the Chemist needs more details, you will add some more fields in the Literature Search Record Template: Literature Link (field type link, identifier: LiteratureLink) and Literature Comments (field type rich text, identifier: LiteratureComments). In the Work Plan Record Template, next to the Related Literature Search record field, you should add corresponding fields: link type field (name Link) and rich text type field (name Comment). In these fields the data will be automatically copied from the Literature Search record by setting the correct Calculation Formula. You should expand the Repeatable Row Group over these additional fields in order to make a table of them.
In the Calculation Formula of each added field inside the Repeatable Row, a formula expression with the keyword Item, a dot (to access the referenced Record Template in the Repeatable Row) and a field Identifier (of a field in the referenced Record Template that you want to copy) should be added:
See how graphical representation looks now in Figure 4.32.
By selecting the Determined by Formula option, another field for the Formula Expression will appear. Here, you can write a formula or condition for the final number of rows that will be available. In this case, the user will not be able to add rows.
A Chemist needs to fill out the Characterization Tests record, where they will define how many samples are tested and enter the test results for each sample. In the Characterization Tests record template, you made a field for the number of samples that are needed. The field type is number, the name of the field is Number Of Samples, and the identifier is NumberOfSamples.
According to the number of samples, only that many rows will be available in the characterization table to be filled out. To achieve this, make a repeatable row group and put it on top of the input fields. In the Repeatable Option field of the group's Functions tab, select Determined by Formula. In the Formula Expression write NumberOfSamples (Figure 4.33).
In some cases, you need to copy values from one table to another table. Let’s say you have configured a record template, Formulation, where you have a user defined table. The user composes this table by adding rows to it. Each row is for one material in the formulation. The Material is a record field and the user chooses from a dropdown which material they are adding to the Formulation. Additional fields are needed in the table, containing information related to the chosen material: material type (pulled from Material record), mass of the added material to formulation (number field, free entry), volume of the material added to formulation (calculated from the mass of the added material and material’s density), material density (pulled from Material record), weight percent (calculated value based on material mass added and total mass of the formulation). See Figure 4.34.
All of these fields are in the repeatable row (identifier Group1), repeatable option defined by the user.
In the Characterization Tests record you want to copy this table from the Formulation record, but you do not want to allow the user to add rows. You want the user to see all materials and amounts present in the formulation before testing it. This is where you will use a repeatable row with the option, Determined by Formula.
As with any table, first create the labels for column headers. Add fields for values you want to repeat. For example, in this table you want to copy information about Material, Material Type and Added Mass. Fields will be pulling values defined in the Formulation record so types must coincide. In the record, Characterization Tests, there is a record reference field where the Formulation record template is referenced (identifier FormulationToTest). The user will choose which Formulation is being tested and the table with the corresponding materials will be pulled.
Place a repeatable row over the fields and choose a repeatable row option Determined by Formula. In the Formula Expression place the following expression:
FormulationToTest.Group1.RowCount
This expression will count and create the same number of rows found in the Materials table (Figure 4.34, identifier Group1) from the Formulation record that is selected in the field, FormulationToTest. Each field in the table needs to have a proper expression in order to pull the desired value:
FormulationToTest.Material
FormulationToTest.MaterialType
FormulationToTest.AddedMaterial
See Figure 4.35. In the Characterization Test record, a table is created and the desired information is copied from the Formulation record.
When selecting Determined by Filter in the repeatable options for a repeatable row group, you can define which record fields will be automatically filled in your table. After selecting this option, you will need to specify the Record Template which you are referencing, by choosing the desired one from the drop-down. In order to narrow down only desired records created from the referenced record template, you need to set the Filter Criteria using the keyword Result and a right filter expression.
A Chemist needs to fill out the LW Report record for the samples tested. Building on the previous example, there is a Characterization Tests record filled out with the results. In the LW Report, the Chemist wants to have a table with all the results measured. These results may be repeated in several Characterization Tests records created in the stage, Lab Work.
In the configuration of the record template, LW Report, make the input number fields for pH, Density and Viscosity. You also need to make a record field, Testing, and make a reference to the Characterization Tests record template. Place the Repeatable Row Group over the fields. In the repeatable option, choose Determined by Filter and from the drop-down choose the record template, Characterization Tests.
In the Filter Criteria write the following expression:
Result.Process==Process
This filter will automatically create a table with as many rows as there are Characterization Tests records created so far in the actual process. You can pull the data in each field from the corresponding Characterization Tests record by using the keyword Item, as explained in the table determined by Record Reference. See the graphical presentation in Figure 4.36.
Note: Repeatable Row Groups determined by Filter are reflecting a specific point in time. Once the record is created, and the table is populated, it will not update if new records fitting the filter criteria are created afterwards.
A Repeatable Column group is enabling the fields inside the group to repeat next to each other in columns. Use cases for the Repeatable Column groups are:
The creation steps, rules and logic are the same as for the Repeatable Row, explained in Section 4.6.2 Repeatable Row.
You cannot apply multiple different field groups to the same fields. For example you cannot apply Repeatable Row and Repeatable Column Group to the same set of fields.
You should not put a separate label field in Repeatable Row or Repeatable Column Groups. Labels are used for additional formatting options outside the tables.
When the Repeatable Column is made, the minimum width of the column that is repeating needs to be 13.
If the Repeatable Column has the Repeatable Options set to Defined by User the minimum Top margin needs to be 4 and minimum Left margin 9. When the Repeatable Column group is used to make a table, a Simple Group will be above it as labels of the columns. For the Simple Group in this context the same rules apply, Top margin 4 and Left margin 9.
If the Repeatable column is determined by any other Repeatable Option, the Top margin also needs to be 4 but the Left margin is not mandatory.
When you are allowing the user to add multiple attachments, best practice is to add a separate label outside the Repeatable Column group because it will be more aesthetically pleasing in the User Portal. Uncheck the Show Field Name as Label for the attachment field and add a label field above the group.
Tag Expressions can be combined using the functions UNION and INTERSECT. The resulting formula will calculate the specific list of users.
Generally, formulas are powerful tools and they are used in many different ways during the configuration. Formulas are written in different forms, depending on where you want to use them. They are generally composed using a function or an operator, combined with the field identifier or field value. Overview of all functions and operators available is given in Section 7 - Formulas. There are 4 types of formulas in Alchemy:
A field or a group can be visible in the User Portal under certain visibility conditions, written in a form of an expression. More complex visibility expressions are obtained using different operators and/or functions. The most frequently used are:
The following examples are demonstrating use cases and formulas for Visibility Expressions with the use of operators.
You are configuring the record template, Characterization Tests, where Chemists can choose the tests needed from different tests available. There should be a checkbox field for each type of test (for example: for pH there is a checkbox with an identifier of pHNeeded) which can be selected if that test is required.
The chemist might also want to see the step-by-step instructions for experiments they need to perform. Using the record template, Test Method, they can create records for each standard experimental procedure.
To accomplish both goals you need to configure a checkbox type field (identifier: pHNeeded). Next to that, you can create another checkbox which the user can select if they want to see and choose the experimental procedure (identifier: ShowProcedure). The next field needed is a record field, referencing the Test Method record template. This field should be visible only if both checkboxes are selected: pH Needed and Show Procedure. In the visibility condition of the record field for Test Method you need this visibility expression:
pHNeeded==true AND ShowProcedure==true
To build on the previous example, in the Characterization Tests record template, a Chemist can enter the test results for pH, density and viscosity. They can select from the three checkboxes depending on which measurement needs to be done (identifiers pHNeeded, DensityNeeded and ViscosityNeeded).
A section with fields for filling in the results should have a label as a title (Label field: Test Results). In the visibility expression of this label, the following expression should be applied:
pHNeeded==true OR DensityNeeded==true OR ViscosityNeeded==true
If any of the tests are selected, the label becomes visible, displaying where the results can be entered.
In the Characterization Tests record, the Chemist can choose from a drop-down what phase of the sample is tested. You need to configure an alphanumeric field (identifier: TypeOfSample) and create predefined values: Solid and Liquid. The Chemist can select Solid or Liquid or both phases at the same time, so for this field you should allow multiple values. There are two tables for entering the test results:
The visibility expression of the table where only ‘Liquid’ value is chosen should be (you will write this in the repeatable row group placed over the fields for entering the results):
'Liquid' IN TypeOfSample AND 'Solid' NOT IN TypeOfSample
The visibility expression of the table where ‘Solid’ or ‘Solid’ and ‘Liquid’ is chosen should be (you will write this in the repeatable row group placed over the fields for entering the results):
'Solid' IN TypeOfSample OR ('Solid' IN TypeOfSample AND 'Liquid' IN TypeOfSample)
Predefined values are basically text and need to be under single quotes. These values are defined in the field Type Of Sample so the operator IN is used. For the case when only ‘Liquid’ is chosen, ‘Solid’ should be excluded so that is why we used the operator NOT IN. Since we need to cover the case when both of the predefined values are selected (solid and liquid), operator AND is used. In this example you can see the combination of different operators and also how parentheses are used.
While testing the samples, the Chemist can make some modifications in the test procedure. These modifications need to be noted. You need to configure a field type, yes/no (identifier ModificationsApplied), and a rich text field where modifications can be described. The rich text field needs to be visible only if yes is selected in the yes/no field (the field will have the value true). The visibility expression for the rich text field is:
ModificationsApplied IS SET AND ModificationsApplied==true
The yes/no field needs to be set so the operator, IS SET, is used. The second part of the visibility expression also needs to be met so the operator, AND, is used.
Filter Criteria are used in fields of type record, process and user, and also in repeatable options of a table determined by a filter. If these fields are referenced to an entity that has a larger selection, it is useful to be able to filter the selection down. For example, if a Record reference field is referenced to a Formulation record, and there are over 100 Formulations with that record template already created, using Filter Criteria and a keyword Result allows this selection to be filtered according to a value in a specific field or system data.
Formulas are written using the keyword Result. Operators can be used in them as well. Below are some examples:
In the process, Lab Work, there is a record, Work Plan, in which the Chemist is planning the formulations and tests they want. Within the same process, the record, Characterization Tests, can be created to capture test results data.
In the Configuration Portal the record template, Characterization Tests, should have a field with the name Related Formulation (identifier RelatedFormulation, type: record, referencing Formulation record template). Since there can be a huge number of Formulation records resulting in this field, you need to set the filter. In the Filter Criteria, the following filter should be used:
Result.Process==Process
Process is a system field and will narrow the resulting records only to those existing in the current process. System fields are unique in the system and used for accessing the system data. They are listed in Section 7.1.2 - System Data Variables.
Let’s expand on the previous example. In the Record Template Characterization Tests there are two more fields:
Now when you have this configured, you can set this filter expression in the field Related to Product:
Result IN RelatedToWorkPlan.RelatedtoProduct
Here we are using the keyword Result and an operator IN.The resulting list of products will be filtered only in the products chosen in the Work Plan. In addition, not in any Work Plan, but in the last created Work Plan in the current process (due to the formula expression set in the field RelatedToWorkPlan).
A list of all operators available is given in Section 7 - Formulas.
Filter Criteria cannot recognize a location given in the square brackets [ ].
In the first example, you learned how to set filter criteria to give the result of only the desired records in the current process using a filter on the record field. You can also set the filter using the system field in the process field.
In the Formulation Design record template, the Chemist needs to choose the product. The product needs to be in any of the processes except the ones with the status Voided. In order to make that possible you will configure the field named Choose Product (identifier ChooseProduct, type: process, referenced process template: New Product Development). In the Filter Criteria of this field write the following expression:
Result.Status !='Voided'
Status is the system field that shows the possible status of the process (‘Active’, ‘Completed’, ‘On hold’, ‘Voided’). The operator, !=, is giving all the processes with the status different from Voided.
Below are general filter criteria that can be used:
Result.Status
- Used in the filter criteria to access system data, such as the status of the record.Result.Process.Status
- Used to add another dimension to the data. For example, to filter records based on the status of the process they are created in.You may need to reference Formulation Design records but only those ones which have the status Valid. This is system data and the valid status means that the record is fully complete. In the stage where you need this information you will make a record field (identifier: ValidFormulation). In the Reference Record Template field you will choose Formulation Design. In the Filter Criteria of the record field write: Result.Status == 'Valid'. In the dropdown of the record reference field in the User Portal, you will get all formulations that you are targeting.
You may also use the Result.Process.Status == 'In Progress' expression. This way, in the record reference dropdown, you will only be able to select from the Formulation Design records created in the ongoing Lab Work Processes.
Result.NumberField
- Used in a lookup to access the field with identifier NumberField in the resulting record. Result.NumberField < 1
and the selection will be filtered according to the value of the field.In the record Characterization Tests, the Chemist has to choose a Formulation Design record but only those which have the batch size less than 500g. Inside the Formulation Design record template there is a field with an identifier, TargetBatchSize, where the mass of the formulation is determined.
In the record template Characterization Tests you will make a record field (identifier: ConnectedToFormulation). In the Reference Record Template field you will choose Formulation Design. If you leave the settings like this, the chemist will get all the formulations, but they need the ones that have a batch size less than 500g. In the Filter Criteria of the record field write: Result.TargetBatchSize < 500
. In the dropdown of the record reference field they will get all formulations that they are targeting.
Result.AlphanumericField == 'String Constant'
- Used to filter records based on a result.alphanumeric
field. The alphanumeric field is usually a dropdown to avoid errors of user entry.A Chemist is adding materials in the formulation. Main Material is a record template where you have created the Material Application Type (identifier MaterialApplicationType, alphanumeric field), with predefined values ‘Ingredient’, ‘Intermediate’, ‘Auxiliary'. In the record Formulation Design, the chemist adds materials to the formula.
Add a field to select the material to add in the formulation. The field should be configured as a record field, referencing the Main Material Record Template. In the Formula Expression field, the following filter expression should be placed:
Result.MaterialApplicationType == 'Ingredient'
This way, the user will be able to select from the drop-down only materials that have the Material Application Type set as ‘Ingredient’.
To summarize, Result is the keyword that is always used when you are writing Filter Criteria in order to narrow the dropdown list of records. After Result. you can define the condition using system data fields or field identifiers from the resulting record template.
Under the Functions tab for most of the field types, you can set the Formula Expression. Using this formula, the system will give a calculated value to a field. A detailed and systematic explanation on how to write formulas is given in Section 7 - Formulas. For now, we will focus on three main groups of formulas that are commonly used in configurations. These are:
You have already seen a simple example of a mathematical formula in the example of calculating the average pH value for 3 measurements (pHResult1 + pHResult2 + pHResult3)/3). This group of formulas is using mathematical operators and are used only in number field types. A detailed list of these operators is given in Section 7.4.4 - Mathematical Operators.
It is important to remember that operators are applied to the field identifiers, and the outcome displayed in the User Portal is the result of the field's numerical values involved in mathematical operations.
Another example that was already shown is setting a formula expression for the record field. Within the example for setting a filter expression, we have used the calculation formula on record field, Related to Work Plan, to give this field a value of the specific record (Record[WorkPlan]
). This is helpful if you need to have a specific record already set, instead of letting the user choose from the drop-down list of all records available on that field.
For example, within a Lab Work process, various records can be created, such as: Work Plan, Formulation Design, Characterization Tests. Wherever you need to address any last created record in the current process, you can do that by creating the record field and referencing the record template of interest. In the Formula Expression of that field write Record[RecordTemplateIdentifier]
. This formula will give this field a value of the last created record in the current process.
The IFS operator checks whether one or more conditions are met and returns the value of the first condition met. It accepts parameters in pairs, but the first parameter in the pair must be a boolean or an error is generated. The second parameter can be a constant, variable, or another expression.
The first parameter is considered an expression before the comma and the second one is after the comma.
In the record, Work Plan, the Chemist can set the target pH, viscosity and density values for each formulation they want to create and test.
You can configure a repeatable row table, determined by the user, where they can add the desired number of formulations and define the target range. Number fields in the table should have identifiers: TargetpHFrom, TargetpHTo, TargetDensityFrom, TargetDensityTo, TargetViscosityFrom and TargetViscosityTo.
Later in the record, Formulation Design, you can configure a table where the Chemist can enter the results measured for that formulation. You can configure the alphanumeric field with two predefined values (‘IN RANGE’ and ‘OUT OF RANGE’). This field should show one of the two predefined values depending on if the result falls in or out of the targeted range defined in the Work Plan.
To achieve this, you need a field where the Chemist will fill in the result of the measured pH (identifier: pH, type: number). Beside that, you need two more number fields with the identifiers: TargetpHFrom and TargetpHTo. Since target values are defined in another record - Work Plan, you can pull the data from that record. A precondition is to have a record field in the Formulation Design record template where you are referencing the record template Work Plan. Note that fields in Work Plan where the Chemist sets target pH range have the same identifiers as fields in Formulation Design where you want to pull the target values.
Pull the data by setting a formula expression, WorkPlan.TargetpHFrom
and WorkPlan.TargetpHTo
in these two fields in Formulation Design. You can hide these two fields because you do not need them displayed but rather to set the IFS condition. Place the following calculation formula in the alphanumeric field where you want the IN RANGE/OUT OF RANGE to be displayed:
IFS(pH >= TargetpHFrom AND pH <=TargetpHTo, 'IN RANGE', true, 'OUT OF RANGE')
A pair of conditions for IFS function are written in parentheses. The first condition ends with a comma, and then if it is met, the field will get the value IN RANGE. If the first condition is not met, the operator goes to the second condition, and after it goes a comma. If the second condition is met, the field will get the value OUT OF RANGE. Since the field is alphanumeric, the value is text.
The first condition is met if both the left and right side of the AND operator are satisfied (i.e. the number entered in the pH field is greater than or equal to the number set as the pH target value, From, and at the same time the number entered in pH is less than or equal to the number set as the pH target value, To). Another operator shown here is the comparison operator >= that compares values of two numbers.
The second condition is simply written with true because IFS functions need a boolean value. This means that in all other cases different from the one set in the first condition, the alphanumeric field gets a value OUT OF RANGE. You can set the same IFS condition on more fields in order to show whether density and viscosity values entered are in or out of range using the appropriate field identifiers for density and viscosity.
The IFS function can be combined with many other operators and functions and are very useful in configuration work.
As previously mentioned in Section 4.5 - Field types, there is a button. Even though buttons are created in the same way as any other type of field, they are not fields and do not have a value. Buttons are created in the record template when you want to allow the user to perform a certain action only when they desire. By clicking a button, the user can create a new record, task, stage or process, recalculate values in fields and many other actions.
In the Configuration Portal, the button is created by left-clicking on the Grid and choosing Button from the list. After setting the field name and identifier, there is a required field, Caption Text, under the Functions tab. The text entered in this field will be displayed in the blue area of the button in the User Portal.
A button can be placed inside a Repeatable Row. This allows a user to click on the button in the row and trigger action to be performed for that specific row. This is done by using the keyword, CurrentRow. You can find an example here: Field Action - On Change Field in a Specific Row.
Under the Functions tab, instead of Formula Expression there is an Action Expression field where a script is written. The following examples will describe the rules Action Expression scripts need to follow.
In the record template, Formulation Design, you are configuring the table using the Repeatable Row option, Defined by User. The user can add as many rows as needed for the formulation that they are composing.
Each row is for one component in the formulation, starting with a record field where the user can choose the desired material from the drop-down list of all available materials in the database. Each row also contains several number fields for the: mass of added material (identifier: AddedMaterialg), density of material (identifier: MaterialDensity) and volume of added material (identifier: AddedMaterialL). The first, AddedMaterialg, is filled in by the user. The second, MaterialDensity, is automatically pulling the information from the selected Material record. The third, AddedMaterialL, is calculated using the formula: AddedMaterialg/MaterialDensity
.
There are two more number fields needed outside of the table. They are: Total Volume (identifier: TotalVolume) and Target Batch Size in liters (identifier: TargetBatchSizeL). See Figure 4.38. To display the fields better a table is shown. Total Volume has the Formula Expression set to sum all volumes added: SUM(AddedMaterialL).
The user sets the desired batch size by filling in the number. Then the table is filled in by adding the rows for different components of formulation. For each material added, the user fills in the mass of added material. Masses are calculated to volumes, and volumes are summed to total volume. If the total volume exceeds the target batch size, or target batch size is changed, clicking the normalize button will automatically recalculate all masses of materials added to have the total volume equal to the target batch size.
The script for this button is very similar to the formula expression from above since that determines the value of a field, but it is triggered only when the user desires (i.e. clicks the button), not automatically:
AddedMaterialg = AddedMaterialL / TotalVolume * TargetBatchSizeL * MaterialDensity
Another important difference is usage of the single sign = instead of ==. The single = should be read as “gets the value of” so in this case, after the button is clicked, a field that had a value entered by the user gets a new value as a result of the triggered calculation. See what happens to the values in the table in the User Portal before and after clicking the Normalize button.
To build up on the previous example, we will create another button. Let’s say the chemist is composing the formulation by adding rows for components, just like in the previous example. The last added material is a solvent and the chemist fills the mass of the solvent in the table. They want to recalculate only the mass of solvent in the formulation to fit in the target batch size. In this case, they need to select the row of the solvent and click the Yield button.
The Action Expression of this button is written with the following script:
RRGroup.Selected.AddedMaterialg = (TargetBatchSizeL - TotalVolume + RRGroup.Selected.AddedMaterialL) * RRGroup.Selected.MaterialDensity
RRGroup is the identifier of the repeatable row used to create the table. The script is similar to the one in the previous example. The difference is that only the field AddedMaterialg in the Selected row of the table is getting the value of the result obtained in the calculation on the right side of =. See what happens to the values in the table in the User Portal before and after clicking the Yield button.
Let’s say a Chemist wants to create a new formulation. In the record template, Work Plan, there is a User Defined table where they can plan the number of formulations. They add a row for each formulation and set the target pH, viscosity and density range for each. See Figure 4.41.
In the Configuration portal, the Repeatable Row group of the table has the identifier ExperimentalFormulaRRGroup. There is also a checkbox field with the identifier FormulaCreated, under label Added. In the Functions tab of this checkbox, Field is Editable should be unchecked. This will prevent the user from filling out the checkbox since it should be filled out by clicking the button.
You need to configure a button that will automatically generate as many records from the record template, Formulation, as there are rows added in the table by the Chemist (Figure 4.41).
Before creating that button you need to create a new record field that will not be cloneable, not reportable, not shown when printed and hidden. This field will not be visible anywhere but in the Configuration Portal record template and it will take part in calculation of a button. In this example, the field's identifier is FormulaHelper and it is referenced to the Formulation record template. The script that needs to be in the Action Expression field of your button is:
for(var i = 1; i <= ExperimentalFormulaRRGroup.RowCount; i = i + 1)
{
if(FormulaCreated[i] == false)
{
FormulaHelper = CREATE_RECORD('FormulationDesign','LabWork',Process,1);
FormulaHelper.FormulationName = LabWorkNumber+' '+ExperimentalFormulaName[i];
FormulaHelper.TargetpHfrom=TargetpHfrom[i];
FormulaHelper.TargetpHto=TargetpHto[i];
FormulaHelper.TargetViscosityFrom=TargetViscosityFrom[i];
FormulaHelper.TargetViscosityTo=TargetViscosityTo[i];
FormulaHelper.TargetDensityFrom=TargetDensityFrom[i];
FormulaHelper.TargetDensityTo=TargetDensityTo[i];
}
FormulaCreated[i] = true;
}
Let’s analyze each part of this script:
for(var i = 1; i <= ExperimentalFormulaRRGroup.RowCount; i = i + 1)
This is a loop that will go through all the rows in a table. A for loop is generally used when you need to do something with the table, such as: automatically add rows, create records based on rows, merge two tables in one, etc.
In the parentheses are the instructions on how and when to start and end the loop through the table. The var is a variable and is the row of the field. The loop starts from the first row, i.e. i = 1;. The middle part, i <= ExperimentalFormulaRRGroup.RowCount, defines when the loop should stop. In this example, as long as i is less than or equal to the number of rows in the table (RowCount is part that achieves this), go through the table with the given increment (last part in the parentheses). The last part i = i + 1, is an increment for how to go through the table. In this case each row, i = i + 1 will check every row.
When the for loop is defined, the block of script which will be executed in one loop step must always be in curly brackets { }. These sections can be long and complex, and can contain several inner sections defined with more curly brackets. Semicolons in the for loop are dividing segments of the loop.
if(FormulaCreated[i] == false)
The first operation inside the loop is a condition. The if operator is a function which checks a condition defined in the parentheses. As previously stated, FormulaCreated is the identifier of the checkbox field and by default is not checked, so it has the value of false. The row in the table is defined by an index [i] and is used to avoid writing conditions for each row separately. This line of script checks if the checkbox of each row is empty, and if it is, executes a block of the script defined in the set of curly brackets after the condition.
After the action initiated on the button has finished, and two new Formulation records are created, the checkboxes will be filled automatically. This is done by the last part of the script (last command):
FormulaCreated[i] = true;
Later, the chemist can add more rows, or formulations, in the table and the checkboxes will be empty by default. Clicking the button again will create Formulation records only for those additional rows.
{
FormulaHelper = CREATE_RECORD('FormulationDesign','LabWork',Process,1);
FormulaHelper.FormulationName = LabWorkNumber+' '+ExperimentalFormulaName[i];
FormulaHelper.TargetpHfrom=TargetpHfrom[i];
FormulaHelper.TargetpHto=TargetpHto[i];
FormulaHelper.TargetViscosityFrom=TargetViscosityFrom[i];
FormulaHelper.TargetViscosityTo=TargetViscosityTo[i];
FormulaHelper.TargetDensityFrom=TargetDensityFrom[i];
FormulaHelper.TargetDensityTo=TargetDensityTo[i];
}
This section consists of several commands. Each command line must end with the semicolon.
FormulaHelper = CREATE_RECORD('Formulation', 'LabWork', Process, 1);
The first command will assign a value to the record field with the identifier FormulaHelper. This field will get the value (=) of the calculation on the right side of the = sign.
CREATE_RECORD is a function that creates a new record. This new record is further defined in the parentheses: 'Formulation' is the identifier of the record template from which new record will be created. 'LabWork' is the stage in which the new record will be created. Process will put the new record in the current process and 1 is the number of records that need to be created (one for each row in the table).
FormulaHelper.FormulationName = LabWorkNumber + ' ' + ExperimentalFormulaName[i];
The second command will define the name of the new record created from the previous command. FormulaHelper.FormulationName stands for accessing the Formulation Name field (identifier FormulationName) which exists in the record template, Formulation. Through the record field (identifier FormulaHelper), using a dot, you are accessing a field on that record (identifier FormulationName). That name will get the value of (=) the calculation on the right side of = sign.
LabWorkNumber is the identifier of an alphanumeric field located in the record template, Work Plan, and serves to track a Notebook process by giving each a unique number.
The empty space between single quotes ‘ ‘ acts as text and serves to divide two values. Without it, two values will appear stuck together).
ExperimentalFormulaName[i] is the value of the alphanumeric field in a certain row of a table. This field is filled by the user and its value is used to give a name to the new record that the button is creating.
FormulaHelper.TargetpHfrom=TargetpHfrom;
The third command is similar to all remaining commands in this section of the script. They serve to fill out the fields in the new record automatically. In the ecord Work Plan there are fields that are used to set the range of pH, viscosity and density. Their identifiers are TargetpHFrom, TargetpHTo, TargetViscosityFrom, TargetViscosityTo, TargetDensityFrom and TargetDensityTo. The chemist will set the target values for each row. These target values pulled from the Work Plan to the Formulation by using field identifiers and dots in these commands. For the sake of simplicity, identifiers are the same in Work Plan and in Formulation.
After all commands are executed in the satisfied conditions, the appropriate new records are created. As previously stated, the last command FormulaCreated[i] = true; will fill in the checkbox FormulaCreated. The script runs through each row in the table and when it is done for all the rows, the loop ends.
In the same way this button is used to create new records, it can also be used to create new tasks, processes, compares, views, etc.
The same actions that can happen by clicking the button in the record template can also be configured in a process to happen during the transition from stage to stage. These scripts are not inside any specific record template but defined as actions on the stage. This kind of script is written in a slightly different way because you need to specify the exact location of a certain field used in a script (which record template, which stage, which process template). More about this will be explained in Section 5 - Process Templates.
In this section, you will see functions that can be utilized to write a proper script.
As previously described in Section 4.4.2 - Alphanumeric, alphanumeric fields can have predefined values. In some cases, you will need to configure the first alphanumeric field with predefined values. Then, depending on the predefined value selected in this field, a specific set of predefined values should be available for selection in the second alphanumeric field. This is known as Conditional Predefined Values and it can be achieved by writing a proper script. See the following example for more information.
You need to configure the Test Instruction record template. This template will be used for the creation of different records - a variety of test instructions in your organization. First, you need to set the type of your Test Instruction. Make an alphanumeric field (name Test Type, identifier TestType) and give it three predefined values: Characterization, Application, Microbiology.
Make a second alphanumeric field (name: Test, identifier Test), where different tests will appear in a dropdown depending on the predefined value selected in the Test Type field. Let’s say these are the values you need to configure:
In the VALUES tab of the field, Test, add all predefined values (pH, Viscosity, Density, Scrub Resistance, Adhesion, Tensile Elongation, Fungal, Bacterial).
Then write the Expression for conditional predefined values, shown in Figure 4.42, where the Values Tab of the field Test is shown with the Expression entered.
See below for the correct Expression:
var a=[];
if(TestType=='Characterization')
{a=['pH','Viscosity', 'Density'];}
else if(TestType=='Application')
{a=['Scrub Resistance', 'Adhesion', 'Tensile Elongation'];}
else if(TestType=='Microbiology')
{a=['Fungal', 'Bacterial'];}
a;
The first line var a=[]; is defining your variable in the code: variable a is given in the square brackets.
When the first if condition if(TestType=='Characterization') is satisfied (i.e., the field with identifier TestType has a value 'Characterization'), variable a can have only these values {a=['pH','Viscosity', 'Density'];}. This means that when the user in the User Portal selects Characterization in the Test Type field, in the dropdown of the field Tests will appear options for pH, Viscosity and Density.
The same goes for the second if condition else if(TestType==’Application’), when variable a can have only one of these values {a=['Scrub Resistance', 'Adhesion', 'Tensile Elongation'];}. The same principle applies for the third if condition as well.
Finally, there is the last part of the expression: a; that will assign the value of variable a to the field Test Type and filter down the list of predefined values based on the satisfied condition.
Another important and powerful functionality that you can use in every field type is Action - On Change. Each time the value of the field is changed, this functionality will execute a specific action. The action is added on the field which will be changed.
Under the ACTIONS tab, you can add a new action by clicking the + New Action button.
In the New Action modal you have to set On* to Changed. In the Action Expression field add the expression that has to happen when a User changes the value of the field. See the following example for more information.
In Section 4.7.4 - Button, there is the example: Button Recalculates all Rows in the Table. In this example you learned how the user can compose the formulation and how they can change the formulation to easily recalculate all amounts in the table using the Normalize button.
Using the On Change action functionality, you can make this recalculation completely automatic. Each time the user changes Target Batch Size [L], all amounts of materials added to the formulation will be recalculated automatically.
In the Actions tab of the field, Target Batch Size L, add a New Action. Set the On* to Changed and under Action Expression write the same calculation that is in the action script of the Normalize button:
AddedMaterialg = AddedMaterialL / TotalVolume * TargetBatchSizeL * MaterialDensity
It is important to note where this functionality is used because each time a value of the field is changed, action will occur automatically. Before implementing this type of solution, consider all possible scenarios that can happen from a user's perspective.
Actions can also be performed on a field in a specific row of a repeatable row. Specifying a row is done by using the keyword CurrentRow. The previous example in Section 4.7.4 - Button with Helper Field, will be expanded upon to explain this functionality.
In the record template, Work Plan, there is a table for defining new formulations: users can add rows, set names and target properties for pH, Density and Viscosity. At the click of a button, Formulation records are created with the names defined in the table.
The Formulation record created with the button action will have a name defined in an alphanumeric field Experimental Formula Name (identifier ExperimentalFormulaName). Let’s say you want to configure the record so the user can change the name of the Formulation record by changing the field Experimental Formula Name in the table.
It was already explained that the Create Formulations button requires an additional record reference helper field, located outside of the repeatable row group. Now, in order to establish a link between each row in the table with the formulation created, you need to place a helper field inside a repeatable row. See Figure 4.44.
Given the fact that the helper field is now inside the repeatable row, each line of the button script should be updated to access value for each row using FormulaHelper[i], therefore the button script needs to be modified, like this:
for(var i = 1; i <= ExperimentalFormulaRRGroup.RowCount; i = i + 1)
{
if(FormulaCreated[i] == false)
{
FormulaHelper[i] = CREATE_RECORD('FormulationDesign','LabWork',Process,1);
FormulaHelper[i].FormulationName = LabWorkNumber+' ' + ExperimentalFormulaName[i];
FormulaHelper[i].TargetpHfrom=TargetpHfrom[i];
FormulaHelper[i].TargetpHto=TargetpHto[i];
FormulaHelper[i].TargetViscosityFrom=TargetViscosityFrom[i];
FormulaHelper[i].TargetViscosityTo=TargetViscosityTo[i];
FormulaHelper[i].TargetDensityFrom=TargetDensityFrom[i];
FormulaHelper[i].TargetDensityTo=TargetDensityTo[i];
}
FormulaCreated[i] = true;
}
Changing the name of the specific Formulation record is done by changing the field Experimental Formula Name in that specific row.
In the field Experimental Formula Name (identifier ExperimentalFormulaName), in the tab Actions, add New Action - On Change with the following script:
if(FormulaHelper[CurrentRow] IS SET)
{
FormulaHelper[CurrentRow].FormulationName = LabWorkNumber + ' ' + ExperimentalFormulaName[CurrentRow];
}
The condition if(FormulaHelper[CurrentRow] IS SET) must be placed in order to apply the On Change Action only for the already created Formulation.
Conditional formatting enables you to change the property of a field using the appropriate Alchemy expression. It can be used on all field types except: Label, Image and Button.
The general form of a Conditional Formatting Expression is:
FieldIdentifier.FieldProperty = PropertyValue;
Where FieldProperty is the keyword to access the specific property of the field defined by the FieldIdentifier. The Specific property is getting the value defined by PropertyValue.
A Conditional Formatting Expression can be placed in fields: Formula Expression, Button Action Expression, Field Action - On Change and Stage Action - Execute Script.
When the Action is triggered, the script will be executed and the field property is changed. If you change the Conditional Formatting Expression in the Configuration Portal and back propagate, the field property will not be affected. It will remain as defined by the previous Conditional Formatting Expression.
Field Dimensions (Width and Height, and Margins) CANNOT be changed using conditional formatting.
Below is a list of field properties that CAN be changed using conditional formatting. A property is defined by its keyword which should be used in the Conditional Formatting Expression. In the list of available field properties below, for each property there is an output type and possible values in parentheses:
The field property, Hidden, can only be used on a field that is not placed inside a repeatable row or repeatable column. If you need to target a specific row inside a table, use Current Row Functionality in the form:
FieldIdentifier[CurrentRow].FieldProperty = PropertyValue;
Let’s build on an already existing example: IFS conditions. In this example we have already explained how an alphanumeric field can show text IN RANGE or OUT OF RANGE depending on the entered value for pH, Density or Viscosity and defined target values.
To make it more visually appealing, let’s say you need to configure the same alphanumeric field to be green when the entered value is in range and red when it is out of range. In the Formula Expression of the alphanumeric field (identifier pHRange) there should be this expression:
var a = ' ';
if(pH>=TargetpHfrom AND pH<=TargetpHto)
{pHRange.InputBackgroundColor='#93C480';
a='IN RANGE';
a;}
else
{pHRange.InputBackgroundColor='#DF6969';
a='OUT OF RANGE';
a;}
In the first condition we are checking the if entered number for pH value is greater than defined start range limit (identifier TargetpHfrom) and lower than defined end range limit (identifier TargetpHto). If that condition is satisfied, the Conditional Formatting Expression will be executed by changing the field property InputBackgroundColor to green ('#93C480'). Also, the field will show the provided text: 'IN RANGE'. In the case that this condition is not met, the field property will be red ('#DF6969') and the field will get the value 'OUT OF RANGE'.
A process is a series of actions necessary for completing an assignment.
In Alchemy, every process is built from stages, completed in a particular order until the expected result is achieved (Figure 5.1).
Each stage in a process requires data input via a user or software integration. The outcome from one stage serves as an input for the next one. This mechanism is repeated until the end goal is reached.
As an Admin in Alchemy, you will design various processes by creating stages and setting actions and privileges for users on each stage.
The Lab Work Startup process is used by Alchemy Laboratory Inc. when a customer asks for an analysis or new formulation. It starts by recording the customer's request (Stage: Lab Work Request). Then the Lab Manager reviews the request (Stage: Request Approval). If the request is approved, Stage: Lab Work becomes active. In this stage, chemists or technicians are making formulations and testing them out. When done, the last stage is the LW Report where the Lab Manager needs to approve all the benchwork done.
The Process Templates landing page has the following features and information:
In this section, we will provide step-by-step instructions on how to create your own process template using the Lab Work process example that we will follow throughout this portion of the manual.
From the Process Templates landing page, create a new process template by clicking the + NEW PROCESS TEMPLATE button. In the modal, fill in fields for:
Both the Name and the Identifier must be unique to the system. No two processes can have the same name or same identifier. However, the Name and Identifier can have the same value.
The Name can contain any characters or numbers. This is how your process template will be displayed in the User portal.
The Identifier is used to reference your template in formula expressions. It must start with a letter and may contain only English alphabet letters, numbers and underscores. In the modal presented in Figure 5.3, you can enter the desired name of the new process template. After you click on the identifier field the identifier value will be suggested automatically. You can change the suggested value if you wish, but make sure that your process identifier always starts with a letter.
There are some words and phrases that cannot be used as identifiers for Process Templates and Process field types. They are reserved by the system to be used in different formulas and include:
After you click the Save button, you will go to the Process Template configuration page as seen in Figure 5.4.
On the right-hand side a process template menu is displayed. It is divided into two tabs, PROPERTIES and PRIVILEGES. Under the Properties tab, you can see the name, identifier, and description fields of your process. The name of the process is editable while the identifier cannot be changed.
Under the Privileges tab, you will set which users can create a process from the template, which users can set priority, hold the process or void the process. Process privileges are written using User Tags.
You can return to the process template menu at any time by clicking the edit icon to the right of the process name.
Process mapping is often used to communicate process flows to clients and colleagues.
A process template is a roadmap with the stages that have to be completed in order to achieve a certain goal, e.g. develop a new product and analyze it. To be effective, processes must be formally designed, structured, documented and communicated. It is important to capture all critical details while creating a process template. By doing so, all individuals and groups using it will be able to understand it better and more easily achieve the desired results.
In Alchemy, you can map out and design as many process templates as you need.
The configuration page of a process template includes the following features and information:
The process title in the User Portal is defined by the system following a pre-set naming pattern.
The process title is defined and set by the Name field. There must be an alphanumeric field with an identifier: Name placed in the first record of the first stage of the process. This field must be an alphanumeric field, with or without a calculation.
In the system, all processes created from the same process template must have a unique title. The process title value is always pulled from the alphanumeric field with identifier Name, that has to be placed in the first record of the first stage in the process template.
When you create a new process template, it is not empty. The system automatically creates one Stage (Stage 1, see Figure 5.5) and one Record Template in it (Process Record). Inside the Process Record there is a naming field automatically created within (type: alphanumeric, identifier: Name). You can decide whether you will keep the Process Record with the naming field, or you can place the naming field inside the record template you design. In the second case you do not need the process record anymore.
It is important to note: the Process Record record template should not be deleted, but rather removed from the process template where it is not needed.
For example, if you are configuring the process template Lab Work, it starts with the first stage: Lab Work Request. In this stage, the first record that is created is called LW Request. In this record template you should configure an alphanumeric field with identifier: Name (naming field) and it should be a required field. What the user fills in this field will be used as the title of the newly created process in the User Portal.
Since users in the User Portal will create many processes from one Process Template, these can be titled in various and inconsistent ways. Due to that, it is highly recommended to define a pattern. Placing a pattern in the formula expression of the naming field, the process title will be created for each new process in the User Portal in a logical and defined manner. You can define a pattern using any of these options:
You can also set whether this field can be edited by the user and whether it needs to be unique. If you leave Field has unique value unchecked, that field will be automatically unique on the process level - meaning that in the process no other field can have the same value. When you check the Field has unique value checkbox, you can choose on which level the field is unique. This will help users realize if the process with the same name already exists in the system.
In Alchemy Laboratory each Lab Work process is registered by a unique predefined pattern. It is done by defining a calculation formula in the naming field (Identifier: Name) with the following expression:
'LW-' + PATTERN(YYYY-MM-NNN)
When creating a new process, it will automatically be titled LW-2021-09-001 (for the first process in September). The following one will be named LW-2021-09-002, etc.
Similarly, you can use the PATTERN function when you want to have consistent names for records that can be created outside of the process (solo records). These record templates must have an alphanumeric field that the system uses for naming (identifier: RecordName).
If you do not use the PATTERN function that will automatically give a name to created processes or records created outside of the process, there is one rule that needs to be followed. If you configure a calculation on Name or RecordName field that uses a value of alphanumeric field, there can be a problem in creating a Process. The process will not be created because it needs to have a name, but the value that is setting a name is not yet given to the field. A record without a name will be created, but if the user does not populate any of the fields from which the record name should be created, it will be ‘nameless’ and the user will not be able to find it later.
In Alchemy Laboratory each Contact is a record created from a solo record template. The Record Name field determines a name of the record that will be created in the User Portal. We want to use two alphanumeric fields to give a name to the record: First Name (identifier FirstName) and Last Name (identifier LastName). You cannot put a calculation on RecordName: FirstName + LastName.
The reason is that a new record created needs to have a name, but a name is not given since values for fields First Name and Last Name are still not set. You can use an “empty string” (one space between identifiers): FirstName + ’ ‘ + LastName. The more straightforward solution is to use the following calculation:
IFS(FirstName IS SET OR LastName IS SET, FirstName + ’ ‘ + LastName, true, ‘Untitled’)
This way, a new Contact record will be created and will have a name, Untitled, until the user fills in First Name and/or Last Name.
A calculation with alphanumeric fields on fields, Name and Record Name, should have the following form:
IFS(Field1 IS SET OR Field2 IS SET, Field1 + ’ ‘ + Field2, true, ‘Untitled’)
Privileges in Alchemy define who is able to view, edit and create processes. They allow multiple teams to work on the same project without interfering with one another. This is very useful in complex organizations. You will configure privileges using User Tag Expressions. For each privilege you can set when certain conditions should be applied.
In the Lab Work process, the Lab Manager, Chemists and Lab Technicians are able to create the Lab Work process and fill in the Request stage.
In the following stage, Request Approval, everyone can view the decision, while only the Lab Manager may approve or deny the request, i.e. edit it.
Lab Work and LW Report stages are filled out by the Lab Manager, Chemists or Lab Technicians, while Sales and C-Level can only view to keep track of the process.
There are three distinct Privilege sets:
1) Process Privileges are given for the process level. Process privileges define who can:
2) Stage Privileges are defined for each stage separately and define which users can:
3) Record Privileges are set for record templates that are not placed in any process template. Based on these privileges, users can work on records without starting the process. Privileges include:
In the record template, under the Privileges tab you can set the User Tag Expressions under each of these fields. Clicking the icon in the field, a small pop-up window will appear, providing more space for writing and better overview.
If during configuration you set the privileges on the record template i.e. Record Privileges, it will be used for creating records outside of the process. If you design a process template you will set the Process Privileges. You can still add a record template with configured privileges and use it inside the process template, but Record Privileges are no longer valid. Process Privileges will overwrite Record Privileges on the record template.
When back propagating changes made on your record template with the Record Privileges set, changes will be effective on all records created with that record template, no matter if it was used in or outside of a process.
Process privileges are added by:
As previously mentioned, only one user tag can receive the ability to set priority privileges.
When creating a process template, you need to have separate privilege for can set priority. Without this privilege, users in the User Portal will not be able to create processes from the process template.
When setting priority privilege, you must specify only one tag by writing its exact name. You cannot use an expression (i.e. HAS_ANY_TAG).
Create a special tag used only for priority setting, separately from other organizational tags you have already created. This way, you will manage more efficiently multiple priority groups inside your organization if needed.
Only a Lab Manager can prioritize work for the Lab Work Startup processes. You can achieve This by adjusting Set Priority Privilege at the process level. In the process template panel, under the Privileges tab, add a new privilege and choose can set priority. You need to assign it by writing only an exact tag name in the To: field: Tag[LabManager].
Another way is to create a special tag only for priority, for example: Tag[LWPrioritySetter]. Assign it only to one person and then in the "To:" field write Tag[LWPrioritySetter].
Other process privileges are added by clicking on the + ADD PRIVILEGE button from the Privileges tab. In the pop-up window, you can:
Can Void and Can Put On Hold privileges can be set together, if you choose, by checking the corresponding checkboxes.
Stage privileges are added in the same manner as process privileges.
Select the stage where you want to add a privilege. Choose Privileges from the right-side panel. Click the + NEW PRIVILEGE button from the Privileges tab. In the pop-up window, you can:
All privileges can be added to users under a certain condition, using the same principle as for actions.
While editing processes, all changes are saved automatically. However, users in the User Portal will not see the changes made to the existing process template immediately. Similar to changes made in record templates, process templates need to be verified and published in order to make the changes available in the user portal.
The first step is to click the VERIFY button in the top right corner of the process template. Verify is used by Alchemy to check the configured data. Alchemy is checking if all the steps of configuration are written correctly (calculation formulas, tag expressions, etc). If something is not correct, a window pops up to notify you to adjust the configuration.
After a successful verification, you can Publish your changes. On the Home Page of Configuration Portal, in the New Changes section will be a list of process and record templates that need to be published. By pressing the PUBLISH button you will publish all templates from the list.
Once published, process templates will appear in the Back Propagate section and the PUBLISH button will be inactive. Publishing the process template will create a new version. In the Process Templates landing page, you can see the latest published version. When you create a process from a template in the User Portal, the newest version will be used.
Pressing the BACK PROPAGATE button will apply the change to all processes created in the system. As previously explained, this can take some time depending on the amount of data in the system but you can track the progress by hovering over the Tenant Status.
In order to enable creating a process in a User Portal, you need to make sure the following items are done:
When creating and testing a new process, set all privileges to yourself as an Administrator using: Tag[Admin]. Once you are sure your process is valid, you can add users and tags in the system and then set the appropriate privileges for them.
If you want to delete a process template, you can do so by going to the process template configuration page of the desired process, then:
You may only delete a process template if no process was created from it in the User Portal, nor was it referenced in any other processes.
A process in Alchemy is constructed from stages that function as a crossroads for flow and to separate and/or group different kinds of tasks. The most common way to map out processes at your company is to define each stage as a task, or set of tasks, for each group of users to perform in a particular order. Tasks in the Alchemy User Portal will be assigned pieces of work, to be finished within a certain time.
Every stage is completed separately. Upon completion of one stage, the process transitions to another stage. A stage is completed when all the tasks of that stage are done, meaning all required work is finished and records are filled with data, including filling in all required fields.
In the Lab Work process, like in many other processes, the first stage is Request. The Request record can be filled out by the Lab Manager, Sales person, Customer, etc. Once all the required information is filled in, the first stage ends and the process proceeds to the second stage.
The second stage is Request Approval where the Request from the first stage is being assessed by the Lab Manager and either approved (process goes to the third stage: Lab Work) or rejected (process goes back to the first stage: Request, where more information is needed).
After you have created a new process, you will need to map out the stages of your flow. To create a stage, click on the + New Stage button at the top left of the process template configuration page. You will need to provide a name and identifier for the stage, following the same logic and restrictions that have been previously explained.
There are some words and phrases that cannot be used as identifiers for Stages. They are reserved by the system and you will be using them in different formulas and include:
Once you create a Stage, you will be able to see it on the Process Template Page as a box with the stage name. Note that Stages in Figure 5.10 do not have any connecting arrows between them. Stages become connected when you add Actions to each stage which is explained in Section 5.7 - Actions.
After clicking on a stage, the right-side panel has four tabs:
When you create a new stage in the process template, Stage Order will be set with the next chronological number. If you reorder your stages in the process afterward, the Stage Order number will stay the same as on creation until you change it manually. Make sure that your stages are all set with the right Stage Order number, because that will be the order by which they will be activated in the User Portal.
Expected Stage Duration is in hours, and by default is set to 8. If the stage is not completed by the user within 8 hours, the user will receive a notification in app or email, depending on how User has managed their notifications in Alchemy.
For each stage, users in the Alchemy User Portal can keep track of the effort involved to complete it. This is done by entering effort spent for each task of that stage. Effort spent is a per-stage setting. By default, that entry is optional. You can set it to be mandatory by checking the box at the bottom of the Properties tab of a stage. That way, a user will not be able to complete a Task on that stage in the User Portal without entering the effort spent.
Records in Alchemy are digital forms in which users are entering data in the User Portal. They allow traceability and a structured flow of information.
Most of the work in the User Portal will consist of writing information in these records. They are explained in detail in Section 4 - Record Templates.
Adding record templates to a stage defines which set of information is needed in order to complete said stage.
In the process, Lab Work Startup, there is a stage, Lab Work. On this stage, a Chemist can plan the experimental work, create formulations or perform characterization tests. They will be able to capture all data in Alchemy through the appropriate record templates added to the stage: Work Plan, Formulation Design, Characterization Testing.
To add a record template to a stage, complete the following steps:
This will open a modal (Figure 5.12) where you need to define the:
When allowing more than one record to be created from the same template, you need to define the Record Naming Pattern and can use the PATTERN function which is explained in detail in Section 7.6 - Functions. It is important to note that the pattern function returns text, auto-incremented by each new iteration.
In the Lab Work process template, after stage Lab Work Request comes the stage Request Approval. If approved, the next stage is Lab Work. If not approved, the flow goes back to the first Stage: Lab Work Request, where additional information is needed or to be changed. This loop: Lab Work Request - Request Approval - Lab Work Request, can repeat but each time Request Approval becomes active, a new Request Approval record will be created.
You need to set the pattern in the naming of LWR Approval record template so each record created gets a unique name. You can do that by writing the following function in the Record Naming Pattern field when adding the template to the stage:
'LWR Approval ' + PATTERN('NN')
Created records will have names: LWR Approval 1, LWR Approval 2, etc. When number 99 is reached, it will start again with 1. If you need 100 or beyond you will use PATTERN (‘NNN’). The same logic is for one digit numbers - PATTERN(‘N’).
When adding a record template to a stage you can specify the minimum and maximum number of records that a user can create. Both can be defined with a number or a formula. Some examples of min and max number of records with a number are:
You are able to use any number for defining min and max in any combination. Make sure that the minimum number is not higher than the maximum.
In the Lab work Request stage, the person who starts a process needs a record, Lab Work Requirements, in order to fill in all the necessary data for the Lab Manager to approve the work needed later in the LWR Approval stage. The person who starts the process needs only one form and that needs to be opened when the Lab Work Request stage is started. You will achieve that by writing the number one, both in the Minimum Records field and Maximum Records field. That is how one record will be automatically created while preventing the user from adding more since the maximum number is also one.
Any of these numbers can be a mathematical formula result. The types of formulas that could be used are explained in Section 7 - Formulas.
Formulas allow you to define the number of records that will show up in the User Portal based on a field value in another record.
In the LWR Approval stage, the Lab Manager needs a LWR Approval record. Each time the process loops back to the LWR Approval stage, the Lab Manager needs a new LWR Approval Record to fill in. That is how Alchemy Laboratory Inc. will be able to trace parts of the Lab Work process about approving the requested lab work. You will achieve that by setting up this formula for Minimum Records and Maximum Records on the LWR Approval stage:
Stage[RequestApproval].Run
Stage is a system field that calls the current stage of the process.
[RequestApproval] is an identifier of the stage, but given in square brackets, it gives only the last activated stage. As the process loops between stages, the Request Approval stage can be activated several times.
Run is also a system field that is counting how many times the stage is initiated. So this expression will create the LWR Approval record each time the current stage is being activated. Since you will place this formula in the Maximum Records as well, no records besides the one created are allowed.
It is important to understand that the number of records set is evaluated on stage activation and completion. This means that if the min/max number of records changes while the stage is active, the user may end up with a number of records lower than the minimum or higher than the maximum. (i.e. if the Lab Manager changes the Number of Samples from 5 to 3, after 5 formulation records are already created, we will have 2 records more than the new maximum). In order to complete the stage, the user will have to remove the excess records or add the missing ones (an error message will be shown otherwise).
After you have added multiple record templates to the stage, you can easily reorder them with the drag-and-drop method. This will enable you to define the order under which the record templates will be displayed in the User Portal.
You can click on any of the record templates on the right-side stage menu to expand its properties, where you will be able to change any of the settings you have made when adding it.
Once you add a stage, you are also able to delete it at any time
You can delete the stage by following the steps below:
Deleting the stage will also delete all actions in that stage.
Alchemy will delete everything that is on the stage you wish to remove. However, you need to delete everything that is related to the deleted stage (i.e. if the deleted stage is used in some conditions on other existing stages, you need to reset those conditions).
Actions define the outcomes of an event. When an event takes place, the system evaluates if all the conditions are met for an outcome to happen.
Every stage has its own life cycle, or series of events that the stage goes through.
In Alchemy, those events are:
The Actions tab defines all actions that could happen in a particular stage. In every individual action, the condition for an outcome is set.
On Activation Attempt actions:
This is mostly used when there are parallel stages transitioning to one stage and you want to make sure all of the previous stages are complete.
On Activated actions:
It is recommended that you always create at least one task on each stage. This is necessary in order to be able to progress through stages and/or complete the process. How to create a Task is described in Section 5.8.5 - Adding Create Task Action.
On Completed actions:
Use this action when completing the last stage of the process (i.e. stage Lab Work Report ) or at certain gates in the process (i.e. after the Request Approval was rejected and the process should be finished).
To connect stages, transitions need to be added between them. The transitions are added in the following way:
This will open a modal where you will define your action in the following steps:
After saving the transition, the two stages are now connected. This means that after the user completes the request, they will transition to the Approval stage. Since you did not choose any condition for the transition, this will happen on each completion of the Request.
Stage dependencies can be different based on your flow sequences. In Figure 5.19 there is example of more complex Lab Work process flow where you can see three types of sequences:
Be careful when adding conditions to a transition. If you do so, you need to account for all possibilities and not leave any loose ends. If all possibilities are not covered, you will get stuck in a process where all stages are complete with no stage activated.
When defining actions, you are able to define a condition under which the action will happen. This is done by setting an appropriate expression on the Action, in the WHEN field.
The condition can be any formula that outputs a boolean value (true or false) or if no condition is defined, the action will be executed every time it is triggered.
When setting a transition, you define where the process should go. You can also define conditions under which it should happen. This is done in the When field. Leaving this field empty means that transition will always happen, without any restrictions. The following is an example of sequential progress through a flow.
After the Lab Manager reviews the request, they receive a task to fill out the LWR Approval record on the stage, Request Approval. In this form, they need to fill a field, Request Approved? (Identifier LWApproval, type: Yes/No) by choosing Yes or No (saved as true or false in the system).
You can make the transition from the Request Approval stage to the Lab Work stage (Action: on: completed, do: transition to). Write the condition (When field) under which this should happen:
Record[LWApproval].LWApproval==true
In the second case, when the request is not approved, this means that the Lab Manager decided the work is not needed and the initiated process should be completed (terminated). To achieve this, in the Request Approval Stage set the Action On: Completed, Do: Complete Process. For the condition (When) write:
Record[LWApproval].LWApproval==false
The Lab Manager did not approve the request because they need more information. This should loop back from the Request Approval stage back to the Lab Work Request stage instead of completing the process like in the previous example.
To configure this, in the Request Approval stage set the Action On: Completed, Do: Transition To, and choose stage Lab Work Request. For the condition (When) write
Record[LWApproval].LWApproval==false
This way, if the Lab Manager does not approve the request, stage Lab Work Request is activated again allowing the person who started the request to change it and/or add more information.
It is possible to activate one stage multiple times if there are multiple transitions coming (or returning) to it (i.e., if there is a loop).
Each time a stage is activated, it initiates a new run. Each run goes through all of the events of a stage life cycle and just like in the first run, activates all actions that are defined for that stage.
For example, Request Approval loops back to the Lab Work Request stage, marking its second run. It will create a record, LW Requirements 2, and when completed, goes again to the Request Approval stage. If there is still some information needed and the request is not approved, it loops back to the Lab Work Request (third run) and on its completion goes to Request Approval, etc.
All of these runs are done and edited in the same stage(s), i.e. the flow loops back and forth without creating new stages. However, the system does not automatically overwrite or modify any of the records from previous runs (unless the user does so). Below is the previous example expanded:
When the Lab Manager is approving the request, besides yes or no, there can be a third possibility: more information needed. Choosing this will re-initiate the first stage: Lab Work Request, where the person who filled out the first request will need to do that for the second time (second run of the stage) and provide more information. Instead of a yes/no type field, you can configure this by using a field Request Approved? (Identifier LWApproval, type: alphanumeric), with three predefined values: ‘yes’, ‘no’, ‘more information needed’.
In the Request Approval Stage set the Action On: Completed, Do: Transition To, and choose Lab Work Request Stage. For the condition (When) write:
Record[LWApproval].LWApproval == ’more info needed’
For each stage, you can define what tasks are automatically created in the User Portal when the stage is activated. Go to the Actions tab and click on the + NEW ACTION button for the stage you need to add the actions. Adding a Create Task Action is accomplished using the following steps:
Subject and Description must be text values (written under single quotes, i.e., 'text value') or formulas that output a text value. More details about formulas is explained in Section 7 - Formulas.
The Subject field is limited to 80 characters, including spaces and quotes, while the Description field can contain up to 2048 characters, spaces and quotes included.
At least one task must be created per stage. If there is no created task per stage the user will not be able to move through the process to go to the next stage.
If you want to copy any text from Word or any other type of document, please make sure that you select the Paste As Plain Text option for pasting. If you do not, the system might not recognize your text as a string value and an issue may occur.
You should assign a task to only one person whenever possible.
A Lab Manager needs to review and approve a request for lab work. The Lab Manager needs to get a task to review the Lab Work Requirements record filled out at the initial Lab Work Request stage. You will configure this by adding a Create Task action. In the task Subject you can write 'Review ' + Process.Name + ' Request'.
Our Lab Manager will receive a task. In its subject they will see which Lab Work needs to be reviewed. If there is nothing to be added in the task Description you can enter ' ', an empty string, since this field is mandatory and you cannot leave it empty.
A task subject should be as unique as possible to ensure the user will have enough meaningful information to know what the task is about. This is important when a user is looking at the tasks outside the process page.
A person who has started the new Lab Work process has finished the Lab Work Request stage. The next stage, Request Approval, is being reviewed by the Lab Manager. If the request is approved, the process will continue to the Lab Work stage and beyond. The Lab Manager wants to delegate the LW Report stage to the person who created the process but there are multiple chemists and lab technicians with the tag HAS_ANY_TAG(Tag[Chemist]) and HAS_ANY_TAG(Tag[LabTechnician]).
In the stage LW Report, you can configure the task action using the expression Process.CreatedBy in the Assign To part of the task action set up. This expression will automatically assign the task to the person who created the Lab Work process.
For each stage you can define notifications that are created in the User Portal when the stage is activated or completed. Go to the Actions tab and click the + NEW ACTION button for the stage you need to add the actions. Adding a Notify Action is done in the following steps:
Subject and Description must be text values (written under single quotes, i.e., 'text value') or formulas that output a text value. More details about formulas is explained in Section 7 - Formulas.
The Subject field is limited to 80 characters, including spaces and quotes, while the Description field can contain up to 2048 characters, spaces and quotes included.
You can configure the system to automatically create records on stage activation when certain criteria are met by adding Create Record actions. Note that the stage will already have the minimum number of records that you have defined when adding records to the stage.
Go to the Actions tab and click on the + NEW ACTION button for the stage you need to create the record and follow the steps below:
Make sure that the record template is added, in the Records tab of the stage, to the stage before adding a Create Record action. If the record template is not added to the particular stage you will not be able to choose that record template in the Create Record action. In the Appendix A of this Manual you can find schemes where all Record Templates are added to adequate stages.
Records in the User Portal can be added automatically or by the user. Use the Create Record action when you want records to be created automatically when a condition is met.
In the Alchemy Lab, after the Lab Work Request stage has been completed, the flow goes to the Request Approval stage.
On the stage, Request Approval, the Lab Manager has to receive a record, LWR Approval, automatically. You can configure this by setting the minimum number of records when adding a record template to the stage.
Another way of configuring this is to create a new action on stage Request Approval, on: Activated, do: Create Record, and choose LWR Approval record template.
For each stage, you can define Emails that are created in the User Portal when the stage is activated or completed. Go to the Actions tab and click on the + NEW ACTION button for the stage you want to send an email. Adding Send Email Action is done in the following steps:
As previously stated, transitions between stages in a process can be sequential, looping and/or parallel. In the following example you will see how to configure a process with parallel stages and how an action On Activation Attempt is used.
In the Lab Work flow there are two parallel stages - Characterization and Application Testing (identifiers Characterization and ApplicationTesting). See Figure 2 in Appendix A to see the flow of this process. Only when both stages are completed will stage, Lab Work Review, be activated and the Lab Manager will receive the task to review the results from them.
You can make this possible setting action On to the Activation Attempt on the Lab Work Review stage and in the Do field you will choose Activate Stage.
In the When field you will write:
Stage[Characterization].Completed AND Stage[ApplicationTesting].Completed
Both conditions needed are combined using the operator AND.
Stage and Completed are system data. Stage with the stage identifier given in square brackets will check the status of the last run of the stage. Completed is the current status of the stage run and returns true if it is completed.
The expression used in the When field sets the condition(s) needed in order to execute the desired action. It is useful in many different cases. Here are two examples: how to set View and Edit privilege for users in different locations of the same company, or how to create a “gate” for the process depending on the decision of the approval.
You need to add privileges for Process and Stages to certain workgroups. Company has a plant in North America and in Europe. In each of the locations there are users with tags Lab Manager, Chemist, Lab Technician. Processes created by people from Europe should not be visible to people from North America, and vice versa.
You can configure this by setting process privileges for Can Void and Can Put On Hold using a When condition:
CREATED_BY(Tag[NorthAmerica])
CREATED_BY is a function that determines if the process has been created by the supplied user(s), in this case, a user with the tag North America. If this is true, than Can Void and Can Put On Hold privileges should be given To:
UNION(HAS_ALL_TAGS(Tag[LabManager],Tag[NorthAmerica]), HAS_ALL_TAGS(Tag[Chemist],Tag[NorthAmerica]),HAS_ALL_TAGS(Tag[LabTechnician], Tag[NorthAmerica]))
You have to add the same for the Europe plant and repeat it on each process and stage privilege that needs to be separated between users in Europe and users in North America.
It was said before that writing privileges for records will make them available for creation outside of the process. In this case, the function from the previous example (CREATED_BY) can not be used, you must use Record.CreatedBy instead of it. To build on the previous example, let’s say you need to distinguish view privilege for different work groups on record outside of the process. You can use the following expression for setting view privileges:
IFS(Record.CreatedBy IN HAS_ANY_TAG(Tag[NorthAMerica]), HAS_ANY_TAG(Tag[NorthAmerica]), Record.CreatedBy IN HAS_ANY_TAG(Tag[Europe]), HAS_ANY_TAG(Tag[Europe]))
Record.CreatedBy will calculate a single value - a specific user who created the record. Since the expression HAS_ANY_TAG returns a list of users, operator IN must be used, to check if the user who created the record is in that list. Function IFS will check the first condition: if the user from North America has created the record, view privilege will be given to users from North America. If this is not true, function IFS will check the second condition: if the user from Europe has created the record, view privilege will be given to users from Europe.
View Templates serve as blueprints for making Views in the User Portal. A View is the determined way of presenting various data in Alchemy. Although Views can be created directly in the User Portal by the User, a need for View Templates exists. For example, all Sales people working for the company need to see Companies, Contacts, Locations. You can design a View Template where you will include all relevant data in the system that will present Sales Data and configure it to be available to Sales people.
In the left-hand side menu of the Alchemy Configuration Portal, accessed by
icon, go to the Section View Templates. View Templates Page is opened (Figure 6.1). At the beginning this list will be empty, but later on, every View Template that you create will be shown here:
1 - Template Name - the name of the view template. Clicking on it will open that View Template Page where you can edit it.
2 - Template Identifier - a unique identifier of the view template
3 - Menu Group - determines where the View belongs - in which section of the Blue Menu in User Portal
4 - Order - determines the place of the View in the Group in User Portal
5 - Last Published Version - an ordinal number of the last published version of the template
6 - Description - quick info about the view (e.g., in order to distinguish 2 similar templates at a glance) not visible in User Portal
7 - Additional options (Edit and Duplicate)
8 - Sorting options available for each column on hover
9 - + NEW VIEW TEMPLATE button - for creating new view template
To configure a meaningful View for the Users you should be familiar with the User Data, i.e. data stored in the system by users (Materials, Formulations, Test Results, Companies, Contacts, etc.). Also, while configuring record and process templates, aim to interconnect the data as much as possible (where it has sense). This means to create record and process fields in order to have access to different records and processes. Doing so will allow you to make efficient Views for users.
1 - Template Name - the name of the view template
2 - Verify - a button to check if there are errors in the configuration of View Template
3 - View Template Menu - where Name, Description, Tag, View Order and Users that will have the View are shown
4 - Additional options - under three dots View Template can be duplicated or deleted
5 - Update - View Template is updated after introduced changes
6 - Data Composition - you can choose the type of data to be displayed in View
7 - Data - will display data added in the list
8 - + Additional options of displaying the data - such as grid, scatter, bars, etc.
9 - Search in the View - searches the data in the View results list
10 - Advanced Search - additional filters available for search
11 - Number Results - a total number of desired results in the system displayed in View
12 - Add/remove columns - here you can choose the columns to be displayed in the View
A precondition to start creating a new View Template is to create a Tag which will be used to define the Menu category for that View Template. Menu category is a subsection of the left-side menu in the User Portal. Created Views can be organized in the left-side menu in various Menu categories. All the Views with the same Tag will be grouped together in one subsection of the left-side menu in User Portal. Subsection will have the title of the Tag, so the Tag name should represent the data displayed in the Views belonging to the section.
Before you start configuring a new view template, first create a Tag. Think about the type of data that the View will contain. In User Portal Views will be organised in sections and Tags will be titles of the sections.
Navigate to the View Templates Page by selecting it from the Navigation Bar on the left side. From this page, you can create a new View Template by clicking on the + NEW VIEW TEMPLATE button on the top left part of the screen. You need to provide:
1 - a name
2 - an identifier
3 - a Tag to define the Menu category (previously created)
for your new view template (Figure 6.3).
After choosing a name, identifier and a Tag for your new View Template, it will be created as shown in figure 6.4.
As already seen, number 3 in Figure 6.2 is the View Template Menu. It contains the name of your View Template, View Template Identifier, View Template Description, View Template Term, Tag and a View Template Order.
Name and Identifier and a Tag are set upon creation of a new View Template. As already said, giving a Tag to the View Template will locate the View created from it in a group together with other Views with the same Tag. In the blue menu of the User Portal, a group of Views will be divided in subsections (Menu categories) with a title given by Tag.
You can write View Template Description which will be seen in the View Template Overview Page (not in the User Portal). It serves to easily distinguish between two view templates with the similar name.
Under View Template Term you will write user tag expression (for example HAS_ANY_TAG(Tag[LabManager]). Here you define which users will have this View available in the blue menu in the User Portal. Views in the User Portal can not be filtered using Advanced Search, only basic search through the View is available. Also, users are not able to add or remove columns from the View. For Views created directly by the Users in User Portal (not using the View Template) Advanced Search and adding/removing columns will be available.
Under View Template Order you are setting the order of the View in blue menu section in the User Portal. Setting View Template Order other than default (zero is filled in by default) will shift the View in the section. If left on zero, Views will show up in the section in the order of creation. Setting it to 1 will shift the View to be on the first position, just after the title of the section.
In the newly created View Template there is no added data to be viewed. Data section contains only instructions on how to start adding them (Figure 6.4). Configuring View Templates from now on has the same interface as in Alchemy User Portal.
On the additional options under the three dots icon choose Data Composition. A new screen will appear (Figure 6.5):
You have four available options:
1 - Portfolio - if you choose this node, your View will display a list of all processes in the system. Further you will apply filters and pull only specific data. The data that can be displayed here are process related: who started the process, when, what is the status of the process, when it was completed, by who.
2 - Records - if you choose this node, your View will display a list of records. You have to choose which type of records by selecting the Record Template from the drop-down list. Also here, you can further filter and adjust the way of displaying the data. The data available are system related (like in portfolio node) and all the field values from records.
3 - Tasks - if you choose this node, your View will display a list of all tasks in the system. Tasks can be further filtered. Data available is valuable for example for Lab Managers so they can track the tasks performed by chemists (effort spent, status of the task, etc.)
4 - Activity - if you choose this node, your View will display a list of all activities of users. This option is seldomly used. It can be set to show detailed activity of users in the system, for example when something was filled in, edited, opened, etc.
Upon selection of one of these 4 options a new screen will appear showing the selected node in respectable colour (blue for process, turquoise for records, purple for tasks and indigo for activity). In Figure 6.6 a portfolio node is chosen.
You can easily remove the selected node by closing it on “x”.
Pop-up window warning will appear asking you to confirm that you want to delete a node permanently.
Deleting a node will return you to the starting Data Composition screen (Figure 6.5) where you can start the selection again. Upon selecting the desired node, clicking on the CLOSE button, your selected data will be added in the View Template. Majority of View Templates that you will configure will be composed using only one node.
If you want to add more nodes, select the first added node (it will get a darker shade of color) and nodes available for adding will appear connected to the first node in dashed line (Figure 6.7). You will see an example in the ADVANCED part of this chapter how to create a View Template with multiple nodes.
Let’s make a View Template for records Formulation Coatings. First create a new View Template on + NEW VIEW TEMPLATE button and for Data Composition choose Records. A drop-down menu will appear with a list of all Record Templates (Figure 6.8). Select Formulation Coatings (a Record Template name will appear in the node) and click CLOSE.
All records in the system created from the Record Template Formulation Coatings will appear listed in the View Template in the first column on the left. Selected Record Template Formulation Coatings appears visible as a filter applied and you can see it as an advanced filter element above the columns (Record Template: Is equal: Formulation Coatings, Figure 6.9). You can access each record by clicking on its name (blue link) - it will open in a pop-up window.
The rest of the columns are showing the fields in the Formulation Coatings Record Template. All the fields that were set to “Reportable - Yes by default” (in the Advance Setting of the field properties) will show up as separate columns (Figure 6.9). When you click on a Columns icon (number 12 in Figure 6.2) a list of all available fields from the Record Template Formulation Coatings will appear. Fields shown in the list are those where in Advanced Setting a “Reportable'' option is set either to “Yes” or to “Yes by default”. Now you can select/deselect the columns that you want/don’t want to be displayed in your View Template. Order of columns can be rearranged by drag-and-drop a column header to the left or right. Once you set up the position of your columns and click on Verify-Publish, the same appearance of columns in the View will be available to the User in the User Portal. A User can rearrange the position of columns in the same way (drag-and-drop) but (s)he will not be able to add or remove columns in the View.
Clearly, you will not need to display all the existing Formulation Coatings records in the View. You can narrow down the list of records that you want using the Advanced Search (number 12 in Figure 6.2). Using Advanced Search allows you to filter not only on different records, but also on all the existing columns (their values, ranges, etc.). Choosing Advanced Search opens a separate window (Figure 6.10):
1 - Available Fields - fields from Record Template chosen in the node and its system fields. Below field name you can see the field type and the Record Template name where it is located
2 - Selected Field - field added from the list of fields on the left side. This field is used in search as a filter. In the top left corner on hover you can delete the field or add another filter criteria for the same field (on “+” icon). Below the field name you can see the field type and its location.
3 - Filter Criteria - Drop-down list of predefined set of criteria which is different for each field type. You can add more of them for each added field
4 - Filter Criteria Value - Here you can type in the value (or range of values) for the selected criteria.
Let’s apply Advanced Search to our example. We want to narrow down the list of Formulation Coatings records to those containing water. Click on the Advanced Search and the window for setting the filters will pop-up. There is one filter that can not be removed, and you have set it up when choosing the Data Composition to Records, selecting Formulation Coatings. In the list of available fields on the left find Material and click on the arrow to add it to the right side (Figure 6.11 A). When you add it to the right side, set filter criteria from the drop down to “Is any of” and then for the value choose “water” (Figure 6.11 B).
You can click on APPLY and the list of formulations in the View Template will be shorter, showing only those Formulation Coatings where one of added materials is water (Figure 6.12).
This way you can add more filters and each time the filter applied will show up as an advanced filter element of respectable color above the columns. Combinations of filters are endless. You can easily remove unwanted filter(s) by closing filter elements on the “x”.
Once you make the View Template available for users as a View in the User Portal, Advanced Search is no longer available for users. If still needed, User can click on the Clone icon and the cloned view will show up in the My Views section of the blue menu. In the cloned view Advanced Search and adding/removing columns in the View will be available.
There are other ways of displaying the data in the View. Next to the tab Data (number 7 in Figure 6.2) which will show the data in the list, there is a “+” icon. Clicking on it will show a list of available options for visualisation of the data in the View. Available data visualisations are grid, board, scatter, bar, boxplot and heatmap. Choosing one of them will open an additional tab, next to the Data tab. When you double click on the name in the tab, you can rename it. We will give a short information about each of the visualisations options available and an example.
Grid is a way of sorting the desired (i.e. filtered) data in the form of groups and subgroups. Each group is a branch which can be expanded to show subgroups.
Let’s select all the formulations where materials used are of the type “pigment”. Go to the Advanced Search and on the left side find the filter “Material Type”. When you add it to the right side, choose the criteria “contains” and write the value “pigment” (similar to the Figure 6.11). After clicking on APPLY, your data listed are all formulations containing pigment type of material as one of the materials added (Figure 6.13).
Click on the “+” icon next to the Data tab and from a dropdown of visualisation methods choose Grid. It will show up in the new tab named “Grid 1” and clicking on it you can rename it. Formulations are still sorted in the form of a list. On the right side click on the sorting icon
and an additional menu for sorting the data will appear (Figure 6.14).
In the right side menu go to the Material field and drag-and-drop it down to the Row Groups section below. Formulations will be grouped by the material (Figure 6.15 - left screen). You can close the right side menu clicking again on the sorting icon
Expand the group to see a list of formulations containing one specific material (Figure 6.15 A - right screen). Keep in mind how your branches are expanded (or not) before doing the Verify-Publish step. Exactly the same appearance will be a starting View for the User in the User Portal.
In Figure 6.15 you can see that there are six formulations (number in the parentheses next to the material name) created in the system using the material KRONOS 2310. Expanding the group will show all six formulations and you can open each of them directly by clicking the link. You can add more subgroups if you drag-and-drop the desired field from the list to the Row Groups.
Board is another way of showing the data in the View. Data will be displayed grouped according to the chosen criteria, i.e. field value. Groups are displayed in a form of scroll-through boards. Within a board, data can be sorted by fields.
We will use the previous example: all formulations filtered to those containing material type “pigment” (Figure 6.13). On the “+” icon, select the Board from the drop-down and it will create a new tab “Board 1” next to the Data tab. There will be an additional menu on the right side where you can choose by which field value formulations will be grouped. You can choose the Material from the drop-down list of available fields (Figure 6.16).
So all the formulations containing the same material will be displayed on the same board. Board is titled by the name of the material and the number in parentheses shows how many formulations are done using the same material (Figure 6.17). Scrolling down through each board is available on the right side of the board. Sorting the formulations in one board is available by choosing the desired field in the section “Sort by”. For example if you choose “pH at 25 degrees” it will sort formulations in the board starting with the one that has the lowest pH.
Scatter can show how the data depend on each other in a regression line. For example, you want to check how viscosity will change while changing the percent of added material. When you have your Data tab ready with the formulations filtered to those you want to chart, click on the “+” icon and choose Scatter. On X Axis choose Material weight percent in Formulation Coatings and for Y Axis choose viscosity at 25 degrees Celsius. You can add more series if you need and choose to show a regression line (Figure 6.18). By default it is showing Best fit, but you can change it to the linear or polynomial.
Under MORE OPTIONS you can set labels for axis, minimum and maximum values for axis, size, color and shape of the points in the chart and a style of the line. When you are finished setting up your plot, you can close the Chart Settings.
Using a Bar chart you can present values of the same category (for example density or viscosity) in different instances (for example formulations). To demonstrate this in an example, filter all Formulations to only those containing material Alchemy Additive 1. Go to the Advanced Search, add the filter “Material”, choose the criteria “is any of” and select value “Alchemy Additive 1”. Now in the Data tab you have a list of all formulations made using Alchemy Additive 1. Click on the “+” icon and select Bar. Chart Settings will appear where you have to choose data for X axis and Y axis. Under MORE OPTIONS you can label the axis, choose the orientation and stacking, choose aggregation of data and change the color of bars.
Box plot can show where the majority of your data is and visualize median value, lowest and highest value and the outliers. For example, you want to check the pH values at 25 degrees Celsius of your formulations. You need to filter the formulations using the Advanced Search to have in the Data tab only those you want to present in a box plot (like in previous examples). On the “+” icon, choose Boxplot. On the right side there is a Chart Settings where you have to choose the parameter for data in Series 1. Choose “pH at 25 degrees Celsius” (Figure 6.20) and a Boxplot will appear.
You can add more Series if you want or remove unwanted series. Close the Chart Settings on “X” to have a nice view of your box plot(s). In Figure 6.21 there are box plots for pH and density at 25 degrees Celsius. You can add as many Boxplot tabs as wanted and also rename them by double clicking on the tab name.
On hover over the “box” you can see which series are in the plot, minimum value, maximum value, median value and Q1 and Q3 values (first and third quartiles). Outliers are displayed as dots.
Heatmap serves to correlate the data in the View. For example you can use it to see how the weight percentage of material added impacts on pH and viscosity of the formulation. For a start, filter the formulations using the Advanced Search to a couple of materials of interest. On the “+” icon select the Heatmap from the drop-down. You can add the series of data that you want to correlate. In this example, pH and viscosity at 25 degrees Celsius as Series 1 and Series 2 (Figure 6.22 A). For Series 3 Material Formulation Coatings is selected. As a Transform Field is chosen Material weight percent, Group By: Name Formulation Coatings (Figure 6.22 B). Make sure that all the desired columns are included in the Data tab, in order to have them available for adding in the Series. Upon adding the Series, correlations show up.
You can close Chart Settings on “x” to have a nice view on your heatmap. On the right side there is legend. Value equals to 1 means direct positive correlation, while 0 is no correlation at all (no impact of added material to the pH or viscosity of formulation). Values close to +1 are indicating strong correlation (i.e. adding this material will affect the pH or viscosity value the most). Values close to -1 are indicating strong negative correlation. Empty fields indicate that weight percent for that material was not changed in the formulations.
From the Heatmap in Figure 6.23 you can conclude that addition of 30% n-butanol will decrease the pH of formulation more than any other material from the heatmap (correlation with pH is -0.65). Adding the same material will increase the viscosity of the formulation significantly, with respect to other materials from heatmap (correlation with viscosity is 0.54).
Just like when configuring Record or Process Template, View Template needs to be verified and published in the same way. The difference is that there is no UPGRADE button for View Templates. Reason for this is that there is no change in configuration but only how existing data is seen in the View.
Note that how you set up a View Template before doing Verify and Publish, that way the User will see the data in the User Portal. For example, if you are displaying the data in a Grid, and you leave some branches expanded and some not, the same setup will be a starting position for the User in the View.
In the upper right corner of the View Template Menu there are available options under three dots. Here you can delete the View Template or Duplicate it.
If you choose to Delete the View Template, a warning pop-up window will appear to confirm that action.
If you choose to Duplicate the View Template, a pop-up window will appear where you need to provide a name and an identifier for the Duplicated View Template. This is required since the name and identifier of the View Template must be unique. Once you change the name and identifier, click the DUPLICATE button and a duplicate View Template will be created.
As mentioned in the BASIC section, we will give an example of a View Template with Data Composition made of more than one node.This is useful when you need to combine different types of data in one View Template.
In Figure 6.7 there is a Portfolio node added and selected in order to add more nodes to it. Dashed lines are connected to other types of nodes available for adding to the portfolio. You can add Tasks, Records and/or Activity nodes to the Portfolio node. For this example, select the Records node, and from the drop-down list of Record Templates choose Work Plan (Figure 6.24). These two nodes are now connected. As a consequence, this will filter down all processes and show only those containing record Work Plan.
In this example, we want to display the status of the tasks of the processes containing a record Work Plan. To achieve this, click on the portfolio node and other available nodes connected with dashed lines will appear. Select the Task node and click close. Data composition is as shown in Figure 6.25.
In the Data tab a list of processes containing a record Work Plan is available. Clicking on the columns icon in the upper right corner of the Data tab opens a list of all columns available. Below the name of each field (that can be added as a column to the View) you can see from which node it is pulled (Work Plan, Process, Task). You can add fields pulling the system data in order to sort the View according to them. For example fields: Created by, Created on, Total Effort Spent (from Process), Formula Type (from Work Plan) and Assignees (from Task). Look at Figure 6.26 for the list of added columns. It is important to select all columns needed in order to sort You can apply additional filters in Advanced Filter if needed.
Now we will use a Grid to organize the list of notebooks. On the “+” icon select the Grid. In the Grid tab open the additional menu for sorting (explained in the Basic part of this chapter). Notice how available fields (i.e. columns) are divided by the node where they belong. Here you can choose Status (from Process) and Assignees (from Task) and drag-and-drop them down (one by one) to the Row Groups section (Figure 6.27).
You can see there are 38 processes Notebooks with the status In Progress, and when you expand the In Progress group, you see how many of them are assigned to which person. Expanding further shows the exact list of processes for each person. In the similar way, you can group the processes according to any of the fields in the record template attached in node.
In the case you want to track the Effort Spent on each Notebook process, click on the ”+” icon and select Bar. In the Bar tab, select the Total Effort Spent Process on X axis and Process Name (Notebook) on Y axis. See Figure 6.28 how the Bar chart looks like.
You can set the Bar chart to show Effort Spent per Person. In our example, the process Notebook can be initiated and completed by different Chemists. Chemists enter their Effort Spent hours doing the work related to that process in the tasks. It is important to remember - when you want to show Effort Spent hours per person: Instead of Assignees, choose Effort Created by Task for the Y Axis. If you choose Assignees, effort hours logged in are going to be duplicated (hours logged in by user plus hours calculated by the system).
If you start making your View Template using a Record node, available nodes for adding are: Stages, Portfolio and Records. You will not have the Task node since there is no connection between Tasks and Records. Instead, you can connect a Record node with another Record node. Choose Formulation Coatings in the first Record node and further connect another Record node. A drop-down list of available Record Templates will appear. This list will contain only those Record Templates that have the connection to the Formulation Coatings, i.e. Record Templates that have record field type referenced to the Formulation Coatings Record Template. So, an important thing to keep in mind while configuring Record Templates is to make reference type fields and try to connect Record Templates as much as possible where it makes sense.
Throughout the previous chapters, you had the chance to see different formula expressions in examples and explanations.
Before we see how to write formulas, we need to define the types of data to be used in formulas:
Elements of formula expressions can be:
Possible elements of the formula expressions are graphically represented in Figure 7.1.
Variables are different fields inside record templates or system fields. System evaluates variables every time the calculation is triggered. Field identifiers are used as variables in formulas, and field values are treated as variable’s values.
Field types are treated as supported data types following the next pattern:
To use fields from a record in the same record:
In the record Request, a requestor fills in the number of samples needed in the Lab Work. This is configured using a field named Number of Samples (type: number, identifier: NumberOfSamples). Each sample needs to be tested three times. In the same record template create a field Number of Tests (type: number, identifier: NumberOfTests). In the calculation formula of this field write the formula:
NumberOfSamples * 3
This will pull the number entered in the field Number of Samples, multiply it by 3 and the resulting value of the field Number of Tests will be automatically calculated.
When you want to use a variable (a field value), from one record, in a formula placed in a different record, you will need to access them through record references. In general, you can access the field using the following expression:
RecordReference.VariableFieldIdentifier
In the Request record template there is a field name Number of Samples (type: number, identifier: NumberOfSamples). Person who fills in the Request sets how many samples are needed. In the record template Test Results, a Chemist who performs the tests and enters the results needs to have the same value of number of samples needed. You need to pull that value from record Request to record Test Results. To achieve this you need to:
- In the record template Test Results, create a record type field (identifier RelatedToRequest) and for record reference choose record template Request. This field serves as a “door” to enter the record Request from the record Test Results.
- Create a number type field where you will pull the data. In the calculation formula of this field write:
RelatedToRequest.NumberOfSamples
You can further use this expression in calculation formulas like in the previous example (not just pulling the data, but calculate further with the pulled data).
You can access all records created in the scope of the current process template using Record[RecordTemplateIdentifier] as your record reference:
Record[RecordTemplateIdentifier].VariableFieldIdentifier
Record - This parameter represents which concrete record should be accessed. Records are aligned by the time of their creation. It is not a required part of the syntax. Writing [RecordTemplateIdentifier], Alchemy will search for and take into account the last created record in that process.
If the field that is a variable is in the record template that is used in multiple stages, you need to specify which stage is meaningful for you by adding the Stage[StageName] part to your expression as below:
Stage[StageName].Record[RecordTemplateIdentifier ].VariableFieldIdentifier
In the Characterization stage you made a field for the number of samples that are needed. Name of the field is Number Of Samples, identifier is NumberOfSamples. This is a number field type. According to the number of samples, only that many rows will be available in the characterization table to fill out. To do this, make a repeatable row group and put it on top of input fields as already explained in chapter How to make a table in Alchemy. In the Repeatable Option field of the group advanced settings, select Determined by Formula. In the Calculation Formula write the expression NumberOfSamples.
The second possibility is that you defined the number of samples at the beginning in the stage Request in the record Request Form. In that case in the Calculation Formula field write the expression: Stage[Request].Record[RequestForm].NumberOfSamples.
To access and perform calculations with fields located in record in another process you will need to configure a field where the users can select either the record reference directly (record type field), or a process reference from where you want to access the record (process type field).
In case you configure the record field, it's identifier will be used as the record reference in your expressions:
RecordFieldIdentifier.VariableFieldIdentifier
To access the pH (identifier ProductpH) entered in QC Profile in process Register Product (marked with star in scheme) you need to configure the following two fields in record QC Result of process Quality Control:
1 - record type field (marked with 1) with identifier FromQCProfile
2 - number type field (marked with 2) with calculation FromQCProfile.ProductpH
In case you configure a process field, you must add it's identifier in form of the expressions with the Record[RecordIdentifier]
ProcessField.Record[RecordIdentifier].VariableFieldIdentifier
This expression behaves the same as explained earlier, with the difference that the records will be pulled from the process selected in the ProcessField field. See the examples below.
In the Alchemy Lab, Chemists are using the process template Register Product to input all details about lab products they get from their formulation outcomes.The Lab Manager is using the process template Sample to prepare samples of products, finish the administration work and send them out to customers. Inside a Sample process, the Lab Manager needs to pull some data from a Register Product process. Schemes of both process templates are shown in the figure below. In the process template Register Product there are multiple stages and records, but the field from which the Lab Manager needs to pull data from is called pH (Name: pH, Identifier: pH). It is located in stage Product Information and record template Chemical Characteristics. In both, the process template and record template need to be referenced in Lab Manager's Sample in order for the system to recognize from where to copy the data, especially because the record template Chemical Characteristics is used across the organization in multiple process templates (NPD, ARM).
Fields that are needed in the Sample process template are:
This field also needs to have a Calculation Formula:
ChooseProduct.Record[ChemicalCharacteristics].pH
These fields are in the Sample process template, stage Request, record template Request Form as seen in scheme below.
In case that there may be multiple records of the same template in the process you are referencing, it is advisable to create a new record field, where the user can choose which record to pull the data from.
With the same example as above, when there may be multiple Chemical Characterization Records in the Register Product Process, it is advisable to have an intermediate field where the user can select which of the characterization records to pull the data from.
Fields that are needed in the Sample process template are:
A field which has the same field type as the field from which we are copying data. Field pH is a number field type so this field also needs to be a number field type. The field where the data will be copied has the Name: Product pH and identifier: ProductpH. This field also needs to have a Calculation Formula: CharacteristicType.pH
As you have seen already, it is possible to "connect" multiple record and process references in one expression. For example, it is possible to access the system information about the process where the record was created using the expression:
RecordVariable.Process
Where RecordVariable is the identifier of your record field. This can further be expanded to access the process system fields, for example:
RecordVariable.Process.Status
will return the string representing the status of the process in which this record is created. This could be a useful filter criteria, i.e. when we only want to be able to select formulation records in ongoing lab work processes.
While the multiple "dot expressions" are useful, they should be used sparingly, as more complex expressions may impact performance, and it is advised to use intermediate (possibly hidden) fields when possible.
Data generated by the system operation is available to be used in formulas. There are some system fields in place that can also be used in formula expressions. They can provide more information about a process, record, stage run or user. They can be activated by using specific keywords listed in further chapters.
You can get any of the data about the process from the system fields listed below using the word Process or the process template identifier. In order to get process data you need to create a field (alphanumeric, number, datetime or user field, based on the type of data from the system field that you want) in which you will write the expression in the Calculation Formula field. The process data that you want can be related to the current process or some other process in the system:
1. If you want the system data from the current process, you will write Process.SystemFieldIdentifier in the Calculation Formula of the created field, where Process is the keyword for the current process template.
If you make an alphanumeric field and write in the Calculation Formula: Process.Status as an output you will get one of the four available statuses of the current process (In Progress, On Hold, Completed, Void) as a string.
2. If you want the system data from another process, you need to create a process field type where the User on the User Portal will choose the exact process. Then you need to create the field (alphanumeric, number, datetime or user field, based on the type of data from the system field that you want) in which you will write ProcessTypeFieldIdentifier.SystemFieldIdentifier
in Calculation Formula, where ProcessTypeFieldIdentifier is the identifier of the process field type.
To build on the previous example, before the alphanumeric field, you would need to make a process field type (identifier ChooseProduct) where you can choose the other process from which you would like system data information. Then, in the alphanumeric field you have made, in the Calculation formula write: ChooseProduct.Status, as a result you will get the status of the process you have chosen in a string.
System fields that could be placed in the Calculation Formula of the alphanumeric field - their output is a string:
System fields that could be placed in the Calculation Formula of the number field - their output is a number
System fields that could be placed in the Calculation Formula of the datetime field - their output is date and time:
System fields that could be placed in the Calculation Formula of the user field - their output is the user's first and last name:
You can get any of the data about the stage run from the system fields listed below using the stage identifier. You need to create a field (alphanumeric, number, date/time or user field, based on the type of data from the system field that you want) in which you will write the expression in the Calculation Formula field.
System fields that could be placed in the Calculation Formula of the alphanumeric field - their output is a string:
System fields that could be placed in the Calculation Formula of the yes/no and checkbox fields, their output is a boolean:
System fields that could be placed in the Calculation Formula of the number field - their output is a number:
System fields that could be placed in the Calculation Formula of the datetime field - their output is date and time:
System fields that could be placed in the Calculation Formula of the user field - their output is user's first and last name:
In the Lab Work Process after the Application Testing the flow is continuing to Lab Work Review. In the Lab Work Review you may want to know the effort spent in the previous stage, the Application Testing (identifier: ApplicationTesting). In the Lab Work Review you can make a field, number type, with the Calculation Formula: Stage[ApplicationTesting].TotalEffortSpent. This formula will output the total effort spent on the stage in hours.
You can get any data about the record from the system fields listed below using the record field identifier or record template identifier. You need to create a field (alphanumeric, number, date/time or user field, based on the type of the data from the system field that you want) in which you will write the expression in the Calculation Formula field. You can access the record data that you want if the record is in the current process or if the record is from another process:
System fields that could be placed in the Calculation Formula of the alphanumeric field - their output is a string:
System field that could be placed in the Calculation Formula of the datetime field - its output is date and time:
System field that could be placed in the Calculation Formula of the user field - its output is the user's first and last name:
System field that could be placed in the Calculation Formula of the process field - its output is the process reference:
System field that could be placed in the Calculation Formula of the number field - its output is the number:
In the stage Formulation, there are multiple records: Formulation 1, Formulation 2, Formulation 3. Their record template identifier is FormulationRecord, and they are created respectively. In the stage Lab Work Review you may want to access system data for the record Formulation 2. Make a datetime field type in the Lab Work Review stage, in the Calculation Formula write: Stage[Formulation].Record[FormulationTemplate, 2].CompletedOn, this gives you the information about the date and time when this record was completed.
You can get any of the data about the users from the system fields listed below using the user field type identifier. First, create a user field type. In order to get user data, you need to create an alphanumeric field in which you will write the expression in the Calculation Formula field: UserFieldTypeIdentifier.SystemFieldIdentifier
System fields that could be placed in the Calculation Formula of the alphanumeric field type:
You can combine multiple system data information. In the Request Review stage you can have a field that will give you the information who completed the stage Technical Call. Make a user field type (identifier: TechnicalCallResponsible) in the Request Review stage (Approval record), in the Calculation Formula write: Stage[TechnicalCall].CompletedBy, according to the information from that stage and the field TechnicalCallResponsible, you can get the information about the user's email. Make an alphanumeric field type in the Request Review stage, in the Approval record and in the Calculation Formula write: TechnicalCallResponsible.Email.
Use square brackets when you want to access the record from the current process the user is in, and you know exactly which record they need (i.e., if there is more than one record, you know which one you need - first, second, last, etc.). When you want that user to have a dropdown list in the User Portal and to choose a record that they need from the process where they are at that moment, you need to make a link between them, using the record reference field. Complex expressions are possible by "dotting" record and process variables together, allowing you to access data from different processes and records. However, overly complex expressions should be avoided.
To summarize - accessing system data can be done by following the logic below:
- Process data can be accessed as:
This approach can be used for all the Process data.
- Stage run data can be accessed as:
To access a specific stage run:
- Record data can be accessed as:
When you are trying to access data from a record that is in the current process you are in, make sure that the record template of that record is added to the process template of the process you are currently in. This is the case when you are using square brackets in the formula expressions.
Constants are values (not fields) that are entered directly into the formula and do not change when the context is changed. They can be only the following types:
Note that other data types (mainly references) cannot be used as constants, as such data always depends on the context in the user portal.
Item keyword is used to access the specific item from the resultset used in formulas in repeatable rows or columns (Item.FieldIdentifier). Namely, they are helping you narrow down the options in the Filter Criteria and enabling the creation of bound tables, as explained in Chapter "Repeatable Options".
Item keyword is used as a record reference variable, to access a specific item from the resultset of fields in repeatable rows or columns. Item is used in the Calculation Formula of fields in repeatable rows or columns where the repeatable option is set to Determined by Record Reference or Determined by Filter.
In our example on how to make a bound table in Alchemy we configured a bound table in the record Work Plan that is determined by the Literature Search record reference. In this case, the Item keyword will act as a record reference variable, for the Literature Search record.
Since the Item is a record variable, all other options explained in the Chapter Variables are available, as long as they are used inside the repeatable row group. Some use cases are:
Operators are symbols or expressions that use two inputs, one on each (left and right) side of the operator. Spaces are allowed between the inputs and the operators. If an operation is defined in a formula on an unsupported type, an error is generated. Below you can find the lists of operators.
AND - performs logical conjunction of two operands. Returns true if both left and right operands are true, false otherwise.
Examples:
a AND b
a AND b NOT SET
NOT a AND b
The Lab Manager wants to continue from the Lab Work to the Report stage. In the Lab Work Review stage there are two questions at the end. One question is: More formulations needed? (field type Yes/No, identifier: MoreFormulations) and the other is: Is the review finished? (field type Yes/No, identifier: ReviewFinished). The first question needs to be false and the second question true to transition to Report. The transition condition set up in the When field of the Actions for the stage will be:
MoreFormulations = false AND ReviewFinished = true
OR - performs logical disjunction of two operands. Returns true if the left or right operand is true, false otherwise. Note that if the left operand is true, right operand is not evaluated
Examples:
a OR b
a OR b NOT SET
NOT a OR b
When using the logical operator OR, if the left operand is true, the right operand is not evaluated.
In the chapter 4.6.1 Formulas in Visibility Conditions there is an example of operator OR already given.
NOT - performs logical negation of one operand. Returns true if the operand is false, false otherwise.
Example:
NOT a
IN - Checks whether all the values of the left operand are all contained in the right operand. Returns true if all the values present in the left operand are contained (are a subset) of all the values in the right operand. Otherwise, false is returned. Left and right operand can be a single constant, enumerated constants in brackets, single field, a single field with multiple values (multiple, column or multiple columns) or enumerated field in brackets.
- If the left and right operands are of different types, a warning is generated.
- If the left operand is empty, returns true. If the right operand is empty, it returns false.
In the chapter 4.6.1 Formulas in Visibility Conditions there is an example of operator IN already given.
NOT IN - Negation of IN. Returns true if all the values present in the left operand are not contained (are not a subset) of all the values in the right operand. Otherwise, false is returned. Left and right operands can be a single constant, enumerated constants in brackets, single field, single field with multiple values (multiple, column or multiple column) or enumerated field in brackets.
- If left and right operands are of different types, a warning is generated
- If left operand is empty, returns false
- If right operand is empty, returns true
In the Formulation stage there is a list of formulations that needs to be made. That list is in the table (repeatable row group). Second column is Status (alphanumeric field with the predefined values, identifier: Status) - status of making a formulation can be ‘Done,’ ‘In Progress’ or ‘Pending’. Below that table there is a checkbox that says: "All formulations are done". Chemists are able to go to the Characterization stage only when all formulations are done and the checkbox is checked.
You will make that possible by writing this expression in the Calculation Formula of the checkbox "All formulations are done":
IFS(('In Progress' NOT IN Status AND 'Pending' NOT IN Status), true, true, false).
This calculation formula will check the checkbox only when In Progress and Pending are not in the column labeled Status, and leave it unchecked if opposite. IFS function will be explained below.
IS SET - Checks whether a value of a field is set. Returns true if the supplied operand contains at least a single value, false otherwise.
- If defined to be used on a constant it always returns true and generates a warning during configuration.
In the chapter 4.6.1 Formulas in Visibility Conditions there is an example of operator IS SET already given.
NOT SET - Checks whether a value of a field is set. Returns false if the supplied operand contains at least a single value, true otherwise.
- If defined to be used on a constant it always returns false and generates a warning during configuration.
- Examples:
FieldIdentifier NOT SET
IS VALID - Checks if there is any value error at the field template. Returns true if there is no value error, false otherwise.
FieldIdentifier IS VALID
NOT VALID - Checks if there is any value error at the field template. Returns true if there is a value error, false otherwise.
FieldIdentifier NOT VALID
Greater Than - Denotes inequality between two operands, namely checks if the left operand is greater than the right operand. Returns true if the left operand is greater than the right operand, false otherwise (null value is treated as 0).
- Examples:
a > b
Greater or Equal - Checks if the left operand is greater than or equal to the right operand. Returns true if the left operand is greater or equal to the right operand, false otherwise.
- Examples:
a >= b
Lesser Than - Denotes inequality between two operands, namely checks if the left operand is lesser than the right operand. Returns true if the left operand is lesser than the right operand, false otherwise.
- Examples:
a < b
Less or Equal - Checks if the left operand is lesser or equal to the right operand. Returns true if the left operand is lesser or equal to the right operand, false otherwise.
- Examples:
a <= b
Equal - Compares two operands for equality. Returns true if the left operand is equal to the right operand, false otherwise.
- Text fields are equal if all the characters are the same (comparison is case sensitive) and the text is of the same length. If the value of both operands is null value or an empty string, equals returns true.
- Numbers are equal if numeric value is the same, regardless of the precision. (i.e. 1 == 1.000 will return true).
- Boolean is equal if both operands have the same value (true and true, false and false).
- Date comparison returns true if every part of the date is the same. Namely, equals returns true if the day, month and year part of the date is the same for both operands, false otherwise (comparison is done in UTC - Coordinated Universal Time).
- Link comparison works the same as text comparison.
- File comparison (when attachment field types are compared) returns true if both operands contain the same file path, false otherwise.
- Process reference comparison returns true if both operands contain the same process ID, false otherwise.
- Stage reference comparison returns true if both operands contain the same stage name, false otherwise.
- User reference comparison returns true if both operands contain the same user ID, false otherwise.
- If empty fields are compared (Null values - no value present) comparison returns true.
- Comparison between two operands of different types always returns false, validation error is generated.
- Example:
a == b
Not Equal - compares two operands for inequality. Works like the exact opposite of equals operator.
- Example:
a != b
In the chapter 4.6.2 Formulas in Filter Expressions there is an example of operator != already given.
Assignment operator - it is used to assign value from right side to the variable to left side
- Examples:
Addition/Concatenation - Performs numeric addition or string concatenation, depending on operand type.
- If two numbers are added together, the resulting number is the sum of the operands with the precision of the number with the highest precision.
- If two string values are added together, the result is a string value formed by concatenating the two operands.
When you concatenate two alphanumeric fields as a result you will see values of those fields glued together. In order to avoid that add empty string in the Calculation formula (i.e. FieldIdentifier1 + ' ' + FieldIdentifier2).
- If a number and string value are added together, the resulting value is a string that is made by concatenating the string and the string representation of the number (decimal places format is conserved in string conversion).
- If the addition results in a number that is higher/lower than the target field defined max/min, an error will be shown by the frontend validator (i.e. if you adjust min and max for the pH field as 1 and 14. An error will be shown in case that pH1 + pH2 = 14.2 since it is greater than 14)
- If the addition results in a number greater than 2,147,483,647 an out-of-range error is shown.
- If the addition result is a number smaller than 2,147,483,647 an out-of-range error is shown.
- Same principle for strings; error is shown if string is too long, otherwise if it is longer than string it is shortened with “...” appended.
- If any of the other operand supported types is used with this operator, the values are converted to their string representation and concatenation of string values is performed.
- Examples:
a + b,a + ' : ' + bRecordIdentifier.FieldThatWantToAddIdentifier + 3.5
Subtraction - performs numeric subtraction of two operands.
- If two numbers are subtracted, the resulting number is the result of subtraction of the second operand from the first operand. Result is a number with the precision of the operand with the highest precision.
- If subtraction results in a number that is higher/lower than the target field defined max/min, an error will be shown by the frontend validator.
- If subtraction results in a number greater than 2,147,483,647, an out-of-range error is shown.
- If subtraction results in a number smaller than -2,147,483,648, an out-of-range error is shown.
- Examples:
a - b
1 - a
EndDate-StartDate (the subtraction must happen in a number type field)
Multiplication - performs numeric multiplication of two operands.
- If two numbers are multiplied, the resulting number is the result of multiplication of the two operands. Result is a number with the precision of the operand with the highest precision.
- If multiplication results in a number that is higher/lower than the target field defined max/min, an error will be shown.
- If multiplication results in a number greater than 2,147,483,647, an out-of-range error is shown.
- If multiplication results in a number smaller than -2,147,483,648, an out-of-range error is shown.
- Examples:
a * b,
a * 3
Division - Performs numeric division of two operands.
- If two numbers are divided, the resulting number is the result of dividing the left operand with the right operand. Result is a number with the precision of the operand with the highest precision.
- If division results in a number that is higher/lower than the target field defined max/min, an error is shown.
- If division results in a number greater than 2,147,483,647, an out-of-range error is shown.
- If division results in a number smaller than -2,147,483,648, an out-of-range error is shown.
- If the right operand is 0, a divide by zero result is returned.
- Examples:
a / b,
a / 3
Negation - Changes the sign of the number. Transfers it from negative to positive or vice versa.
- Examples:
#n
MOD - calculates the remainder after the number is divided by divisor. The result has the same sign as the divisor. Number a is dividend, number b is divisor.
Example:
MOD(10%3)
As already mentioned, we use tags to define which users will be assigned certain privileges, tasks or notifications. This can be done by using User Tag Expressions. The available User Tag expression formulas are:
In the Alchemy Laboratory, Beth Cooper is a lab manager and has the LabManager tag. Chad Ravenal, Tom Dalberg and Dan Perry are chemists and the three have the Chemist tag.
To assign edit privileges on a particular stage, you will add the user tag expression in the To field:
HAS_ANY_TAG(Tag[Chemist])
This allows all three chemists to edit rights. To include the lab manager as well, expand the formula to include:
HAS_ANY_TAG(Tag[Chemist], Tag[LabManager])
You can further combine user tag expressions HAS_ANY_TAG and HAS_ALL_TAGS with functions. Functions and formulas are explained in detail in Chapter 7. Formulas. Two functions are applicable for use with user tags and user tag expressions:
Please note: all the Alchemy functions that will be listed in the following pages are available, but not applicable in all cases. Some of the functions are generated in order to help solve specific problems and use cases, and their application at the moment is not wide.
Functions are expressions in Alchemy that can use one or more inputs, given in brackets (), and perform complex calculations before returning the output.
Functions that are the most frequently used are explained below together with examples highlighted in blue. Detailed list and explanations of Functions used in action scripts, Trigonometric functions, Miscellaneous mathematical functions, String functions, Statistical functions, Date and Time functions and Array functions are given in Alchemy Script User Manual.
IFS - Checks whether one or more conditions are met and returns the value that corresponds to the first true condition. Accepts parameters in pairs, first parameter in pair must evaluate to a boolean or an error is generated. Second parameter can be a constant, variable or another expression. First parameter is considered an expression before the comma, and the second one is after the comma.
- If the first parameter in a pair evaluates to true, returns the second parameter of the pair.
- If IFS is defined with an odd number of parameters, an error is generated.
- If IFS is defined without parameters, an error is generated.
- Examples:
IFS ( a < b, a, a> b, b),
IFS ( f <=5, d * 3, (c +2 < c), IFS (f < c, 4, e>=d, d), a = b, c, f >= 250, d + 1)
In the chapter 4.6.3 Formulas in Calculations there is an example of function IFS already given.
SQRT - A function that calculates the square root of the operand. When performed on an operand, it finds the square root of the number.
- If the operand is negative, it returns an error.
- If performed on an empty value, returns 0.
- If square root is used on a negative constant, a warning is shown.
- If square root is used on a number whose minimum is less than 0, a warning is shown.
- Examples:
SQRT(n),
SQRT(a + b),
SQRT(144)
POW - A function that calculates the result of a number raised to a power. Returns the value of the first operand (before the comma) being raised to the power of the second operand (after the comma). The second operand needs to be an integer.
- Examples:
POW(a, 2)
POW(3*n, 3)
POW(10, 10)
ABS - Returns the absolute value of a number or the operand (value without the sign).
- Examples:
ABS(n),
ABS(-15)
SUM - Returns the sum of all the values of a multiple value property or all the values in a column. Adds all the values of the specified field or constant.
- If used on a constant number, the result is that number. If used on a single value field that belongs to a simple type group, a warning is issued during configuration. In that case, SUM will return the value of that field. If used on a constant, a warning is issued.
- If used on a field that is marked as multiple, all the values are added together and returned.
- If used on a single value field in a table (repeatable row or repeatable column group) all the values in all the rows are added together.
- If used on a multiple value field in a table, all the values in all the rows and all the multiple values within a single cell are added.
- Examples:
SUM(15),
SUM(n)
LOG - calculates the logarithm (base 10) of the value in argument.
- Examples:
LOG(100)
LOG(n)
LOG(a/b)
COUNT - Counts all the values of a multiple value property or all the values in a column. This function counts all the values of the specified field or constant.
- If used on a single value field that belongs to a simple type group, a warning is issued during configuration. It will return 1 if there is value, 0 otherwise. If used on a constant, a warning is issued.
- If used on a field that is marked as multiple all the values are counted.
- If used on a single value field in a table (repeatable row or repeatable column group) all the values in all the rows are counted.
- If used on a multiple value field in a table, all the values in all the rows and all the multiple values within a single cell are counted together.
- Examples:
COUNT(15)
COUNT(n)
ROW_COUNT - Counts rows or columns of a certain field.
- If it is used on a constant, the result is 1. If it is used on a single value field (multiple=false) that belongs to a group that is a single type, a warning is issued during configuration. It will return 1 if there is value, 0 otherwise.
- If it is used on a field that is marked as multiple (multiple=true, groupType=SINGLE) the result is 1.
- If it is used on a single value field in a table (multiple=false, groupType!=SINGLE) the result is the number of rows or columns.
- If used on a multiple value field in a table (multiple=true, groupType!=SINGLE) the result is the number of rows or columns.
- Examples:
ROW_COUNT(FieldIdentifier)
AVERAGE - Calculates the average (arithmetic mean) of all the values of a multiple value property or all the values in a column. This function works by adding together all the values and then dividing it by the number of values. Calculates the average of the specified field or constant.
- If used on a constant number, the result is that number. If used on a single value field that belongs to a simple type group, a warning is issued during configuration. It will return that number as a result. If used on a constant, a warning is issued.
- If used on a field that is marked as multiple, all the values are added together and divided.
- If used on a single value field in a table (repeatable row or repeatable column group) all the values in all the rows are added together and divided.
- If used on a multiple value field in a table, all the values in all the rows and all the multiple values within a single cell are added together and divided by the total count of all the values.
- It is identical to SUM(n)/COUNT(n).
- Examples:
AVERAGE(15),
AVERAGE(n)
TODAY - Function that returns current date, in UTC, can be parameterized optionally.
- When defined without parameters, it returns the current timestamp without seconds.
- When defined with parameters, the first parameter represents offset in days, the second represents hours and the third represents minutes (i.e. TODAY(2, 0 , 0 ) will return a UTC date that is two days from now. TODAY(0, -1, 0) will return a UTC date that is one hour in the past.).
- If a parameter is not supplied, it is assumed to be 0.
- When a non-integer number is supplied as a parameter, a warning is generated.
- Examples:
TODAY,
TODAY(2),
TODAY(2, 6),
TODAY(2, 0, -1),
TODAY(-14, 0, 0)
Whenever you need a date&time type of field to be filled in by today's date you can use this function. Write TODAY in the Calculation Formula of the field type date&time. You should check the Editable checkbox “Editable” in the Properties tab of that field, so if needed, the user in the User Portal can change the date of today to some other date.
DATE FORMAT - Function that returns a text representation of a date input based on the supplied format.
- First parameter is the Date and Time variable
- Second parameter is the format, provided as a string. You can use any of the formats available as explained in the section 4.4.4 Field Types, Date and Time Field.
- Examples:
DATE_FORMAT(ProjectStartDate, 'YY-MM-DD')
DATE_FORMAT(Process.CreatedOn, 'EEEE, MMMM d, y')
ROUND - Rounds the number to given precision. It is rounded using half-up mode (i.e. everything above 12.5 will be shown as 13, and everything below 12.5 will be shown as 11. If the number that is rounded is 12.5, 13 will be shown).
- Rounds the first operand to the number of digits supplied in the second operand (i.e. ROUND(12.5, 0) 13 will be shown; ROUND(12.54, 1) 12.5 will be shown).
- If the second operand is less than 0, 0 is returned as a result.
- When the rounding has more digits than the source number (first operand), the result number has its precision increased.
- Examples:
ROUND(12, 2),
ROUND(12.5, 0),
ROUND(a, 4),
ROUND(a, b)
TRANSITION_FROM - Checks whether the activation path is coming from the selected stage. Returns true if stage activation is coming from the specified stage, false otherwise. Can only be used in process template rules (i.e., in conditions for actions), an error is generated if used in other types of formulas.
- Example:
TRANSITION_FROM(Stage[Requirements])
Request Review in the Lab Work can be done after Request stage or after Technical Call stage. The Lab Manager needs to get the task with different subject for reviewing. One subject should be when the task is created after the Request stage and the other subject when the task is created after Technical Call.
In order to set up those tasks you need to add two Create Task actions on the Request Review stage. In the first one in the When you will write TRANSITION_FROM(Stage[Request]) and the Task Subject you will fill in with the 'Review the Lab Work Request for ' + Process.Name. In the second one in the When you will write TRANSITION_FROM(Stage[TechnicalCall]) and the Task Subject you will fill in with the 'Review the Lab Work Request for ' + Process.Name + ' - technical call is done'.
HAS_ANY_TAG - Returns a list of users that have any of the supplied tags.
- If no tags are supplied a warning is generated.
- If the same tag is passed multiple times a warning is generated.
- Example:
HAS_ANY_TAG(Tag[SalesDirector], Tag[President])
HAS_ALL_TAGS - Returns a list of users that have all of the supplied tags.
- If no tags are supplied a warning is generated.
- If the same tag is passed multiple times a warning is generated.
- Example:
HAS_ALL_TAGS(Tag[SalesDirector], Tag[VPMarketing])
INTERSECT - Calculates the intersection between multiple lists of the same type. Only the values that are found in all the supplied lists are returned.
- Examples:
INTERSECT(HAS_ALL_TAGS(Tag[Thermosets], Tag[TechnicalService]), HAS_ANY_TAG(Tag[Manager], Tag[Representative]))
UNION - Calculates the union between multiple lists of the same type. All the values that are found in all the supplied lists are returned. List members are not repeated, if found multiple times.
- Examples:
UNION(HAS_ANY_TAG(Tag[Chemist], Tag[SynthesisLab]),HAS_ALL_TAGS(Tag[LabManager]))
CREATED_BY - Determines if the process has been created by supplied users. Returns true if one of the supplied users has created the process, false otherwise.
- Example:
CREATED_BY(Tag[SalesDirector]) OR CREATED_BY(Tag[LabManager])
PATTERN - Returns an auto-incremented pattern based on the supplied pattern in the operand. Defined pattern supports letters (acbd, etc.), digits (1234, etc.) and date and time. The Maximum length of this field is 255 characters. We support single pattern definition; if multiple patterns are defined in a formula, an error is generated. If you need a pattern to start from the specific number you can use the following expression: PATTERN('NN','41'), where 41 can be any two digits number.
• Keyword: PATTERN
• Pattern:
Each time you reach the "end" of the pattern, the pattern will restart from the beginning. So if you use N for single digits, when N reaches 9, it will start from the 1 again; the same thing applies for letters. This does not apply for the time-based pattern values, since their values are dependent on the current date and time, but changes of these values influence the resetting of the values from there (i.e., if you are counting Lab Works per date, pattern would start from the beginning with the new day). Date values are calculated in the time zone from which the request is coming from.
- Examples:
'Sample ' + PATTERN('ANN'),
'Shipment ' + PATTERN('YYYY-MM-DD-NN')
In Alchemy Laboratory each Lab Work process is registered by a unique predefined pattern. It is done by defining a calculation formula in the naming field (a field that gives name to the process started, located in the first record of the first stage of the process; Identifier: Name) with the following expression:
‘LW-’ + LWNumber + ' ' + LWDescription
LWNumber is the identifier of an alphanumeric field where the pattern function is used under the calculation formula: PATTERN('YYYY-MM-NNN').
LWDescription is the identifier of an alphanumeric field where the user can enter a short description of the process started.
When creating a new process, it will automatically be titled “LW-2021-09-001 ‘description entered’ “ (for the first process in september). The following one will be named “LW-2021-09-002 ‘description entered’ “, etc. If by the end of September there are 999 Lab Works, counting will start again from 001. The first Lab Work in October will be titled as “LW-2021-10-001 ‘description entered’ “.
You cannot have more than one PATTERN() formula in one expression. i.e. PATTERN('YYYY') + PATTERN('NNN') is not a valid expression. If you need to join two patterns, write the expression in two separate fields, and concatenate the strings in a third.
KEY_PATTERN - Returns an auto incremented pattern based on the supplied pattern in the operand
- First parameter defines the prefix (in further text KEY) for the pattern, and the prefix can be constant or field value.
- Second parameter is the pattern value and the same rule can be applied as for the PATTERN function.
- Third parameter is optional. It defines which value is the starting point from which pattern should count, can be constant or field value.
- Examples:
The value of KEY_PATTERN will reset with the change of KEY. If the configurator decides to return the previous KEY in the calculation, the pattern will continue to calculate from the last value that KEY returned before change is made.
One formulation can be tested multiple times. In order to distinguish between these different test results, you can use the KEY_PATTERN function to name different Characterization Tests records. In Characterization Tests record template there is a field Related To Formulation (identifier RelatedToFormulation), where formulations displayed are filtered only to those created in the current process. You need to add an alphanumeric field, identifier CharacterizationKeyNumber.This field should be hidden because it helps you to name Characterization Tests records in the process and serves only for that. Calculation of this field should be:
RelatedToFormulation + KEY_PATTERN(RelatedToFormulation + ' ', 'N.N')
Under Lab Work Stage, under the Records tab, choose the Characterization Tests and in the Naming Pattern use the value of the field CharacterizationKeyNumber. This way, if you have more Characterization Tests records created for the same RelatedToFormulation field value, they will have different names. The difference will be in the number given by the KEY_PATTERN function: 0.1, 0.2, 0.3, etc.
KEY_PATTERN function is a powerful tool. You can change the KEY, and reset the counting. If you change the KEY back to the previous value, it will not reset the counting again, but continue from the value when it was changed for the first time. See the following example.
In Alchemy Lab final Products receive a number based on the Product Type. Product Number is an alphanumeric field with calculation ProductType + KEY_PATTERN(ProductType, 'NNN'). However, the new R&D director decided that Product should receive a number based on the Industry Type where it is applied. In that case the new calculation in the Product Number field will be IndustryType + KEY_PATTERN(IndustryType,'NNN'). The first new product will have number 001 for a certain Industry Type no matter if it is from the Product Type where the next number would be 029. The reason is that KEY is changed.
Getting back previous KEY in calculation
After a while the new R&D director realized that the previous product naming convention was more efficient. He asked a configurator to change Product Numbers so they again depend on the Product Type. After a calculation in Product Number is returned to ProductType + KEY_PATTERN(ProductType, 'NNN') numbers will count from the number where they stopped before the change was made (the product from the certain type will have number 030).
STAGE COMPLETED BY - Determines if the stage has been completed by supplied users. Returns true if one of the supplied users has completed the stage, false otherwise.
- Example:
STAGE_COMPLETED_BY(Tag[SalesDirector])
RUN COUNT - Returns the number of runs the given Stage has
- Examples:
RUN_COUNT(Stage[Stage_1])
CONVERT UNIT - Convert provided number value in the desired unit
var a = { “unitType”: { “value”: unitTypeValueVariable, “unit”:
unitTypeUnitVariable } }
CONVERT_UNIT (ValueToConvertField, UnitField, UnitFieldToConvert, a);
- Examples:
CONVERT_UNIT(ValueToConvertField, UnitField, UnitFieldToConvert);
var a = { "density": { "value": DensityValueVariable, "unit": DensityUnitVariable } }
CONVERT_UNIT(100, ‘g’,’ml’, a);
The accepted abbreviations for some of the units are given below. The details on the units’ abbreviations were based on this Source.
Abbreviations:'mg','g','kg','gr','lb','dr','oz','t','ton','ml','dl','cl','l','m3','gal','hl','tsp','tbsp','fl oz','cup','pt','qt','g/ml','g/dl','g/cl','g/l','g/m3','kg/ml','kg/dl','kg/cl','kg/l','kg/m3','lb/gal','lb/pt','lb/qt','oz/gal','oz/pt','oz/qt',
Once you have collected information from your co-workers about the process and record templates that your organization needs, you can start designing.
In order to make sure that you covered all process and record information that you need, we recommend having everything structured before you start with configuring in the Configuration Portal. You can do this easily using Alchemy's sheets.
In Process Template Design you have two sheets to begin with. In the Process Template sheet you can:
In the Stage 1 sheet you can define:
You can Duplicate Stage 1 sheet and enter information about the next stage. You can name the sheet with the stage name.
In Record Template Design you have two sheets. In the Record Data sheet you will add fields and define everything that you can define in Alchemy (name, identifier, should value be unique, field type, calculation formula, visibility condition, group etc.). Use the Overview sheet for organizing fields. There you have a grid that looks like the Alchemy grid - where you may see fields in the form. For the purpose of organizing you can also use other tools for drawings, or with paper and pen.
Usage of these templates is simply our advice, before you start to configure templates in Alchemy.
Good luck!
In this appendix you can find the contents of the processes templates that were mentioned throughout the Manual. You can see the structure of the process templates and which records are placed in which stage. Next to the schemes you can see a representation of the process flow from the Configuration Portal.
In this appendix you will find a list of all examples shown throughout the Configuration Manual divided by Chapters. Next to each title of example, you will find a link to the subchapter where the example is.
Using tag expressions to assign privileges (3.2.1 User Tag Expressions)
Fields with and without margins (4.2.2 Creating a New Field in the Record Template)
Hidden Fields - Project Scoring (4.3 Field’s Function Tab)
Calculation Formula Example - average value of three measurements (4.3 Field’s Function Tab)
Uniqueness on the system level (4.4.2 Alphanumeric)
Choosing the Material in the Formulation (4.4.9 Record)
Show only the list of Lot numbers from a chosen material (4.4.9 Record)
Show only the list of finished goods from all products available (4.4.9 Record)
Process Filter Criteria according to process status (4.4.10 Process)
Assigning the Sample Preparation to a specific Chemist (4.4.11 User)
Simple Group - fields related to the same topic and visibility condition (4.5.1 Simple Group)
Visibility Conditions - selection of the pH test (4.5.1 Simple Group)
Visibility condition - test selected on another record (4.5.1 Simple Group)
A horizontal table in Alchemy (Repeatable Row option - defined by User)
Number of rows determined by number of samples (Repeatable Row option - determined by formula)
Number of rows automatically determined by number of tests created (Repeatable Row option - determined by Filter)
Operator AND (4.6.1 Formulas in Visibility Conditions)
Operator OR (4.6.1 Formulas in Visibility Conditions)
Combination of operators AND, IN and OR (4.6.1 Formulas in Visibility Conditions)
Operator IS SET (4.6.1 Formulas in Visibility Conditions)
System field in Filter Expression (4.6.2 Formulas in Filter Expressions)
Operator in Filter Expression (4.6.2 Formulas in Filter Expressions)
Use of Operator and SystemFiled in Filter Expression (4.6.2 Formulas in Filter Expressions)
Filter the Formulation records according to status (4.6.2 Formulas in Filter Expressions)
Filter the Formulation selection according to the batch size (4.6.2 Formulas in Filter Expressions)
Filter records based on alphanumeric fields (4.6.2 Formulas in Filter Expressions)
Lab Work Startup Process (5. Process Templates)
Lab Work Title in the User Portal (5.2.2 Process Title in the User Portal)
Stage: Request (5.7 Stages)
Stage Duration (5.7.2 Editing Stage Properties)
Record Templates in Lab Work stage (5.7.3 Adding Record Templates to a Stage)
Request Approval 1 - making a pattern for the Approval Record Template (5.7.4 Using Patterns for Record Names)
Setting up a minimum and maximum number of records in the Lab Work Request stage (5.7.5 Number of Records)
Setting up a minimum and maximum number of records in the LWR Approval stage (5.7.5 Number of Records)
Sequencial progress from LWR Approval to Lab Work Stage (5.8.4 Action Conditions)
Loop between stage Request and Request Approval (5.8.4 Action Conditions)
Looping from Request Approval to Request (5.8.4 Action Conditions)
Writing Subject and Description for a task on the Request Approval stage (5.8.5 Adding Create Task Action)
Task assignment to the person who has created the process (5.8.5 Adding Create Task Action)
Creating a record LWR Approval as action on activated Request Approval Stage (5.8.7 Adding Create Record Action)
Privileges for Process Lab Work Startup and its Stages (5.3 Privileges)
Setting Priority for Lab Work (5.3.2 Set Priority Privileges)
Transition from two parallel stages in the next stage (Advanced part of 5. Process Templates)
Privileges for different workgroups (Advanced part of 5. Process Templates)
Privileges on record created outside of the process (Advanced part of 5. Process Templates)
Field value used in calculation in same record (7.1 Variables)
Accessing a field through record reference (7.1.1 Reference Variables)
Number of rows determined by number of samples (7.1.1 Reference Variables)
Record field to use data from another process (7.1.1 Reference Variables)
Process field to use data from another process (7.1.1 Reference Variables)
Multiple record of the same record template (7.1.1 Reference Variables)
System data from the current process (7.1.2 System Data Variables)
System data from another process (7.1.2 System Data Variables)
Effort spent for Application Testing visible in Lab Work Review (7.1.2 System Data Variables)
Record Formulation 2 completion date (7.1.2 System Data Variables)
Email of the responsible person for the Technical Call (7.1.2 System Data Variables)
Transition condition with logical operator AND (7.4.1 Logical Operators)
Calculation Formula based on Status of the Formulation (7.4.1 Logical Operators)
Today’s date (7.5 Functions)
Request Review task subject based on TRANSITION_FROM (7.5 Functions)
Lab Work Title in the User Portal (7.5 Functions)
Naming Characterization Tests record (7.5 Functions)
Changing KEY will reset the KEY_PATTERN (7.5 Functions)
These are some general guidelines on how to set up different field types when composing a Record Template. Best Practice is to set up a Theme (section 4.4.15) according to the following guidelines. When adding new fields to the grid you will have fields already adjusted to the desired setting.
*Adjust field width according to the length of your content.
**Margin values depend on the type of field being created. Refer to the Field Property Guidelines - Use Cases for more information.
Best practice: Use Label Type Field to create Title on record template. If the record template is complex and contains a great number of fields, it is best to divide the record template in subsections using subtitles. Labels are used to give names to columns in a Table.
Code 128
It has support for all 128 ASCII characters (numbers, letters and special characters)
Code 39
It has support for numbers, letters and some special characters (- . $ / + %) and space
UPC
It has support for only numbers, 11 digits
EAN13
It has support for only numbers, 12 digits
EAN8
It has support for only numbers, 7 digits
EAN5
It has support for only numbers, 5 digits
EAN2
It has support for only numbers, 2 digits
MSI
It has support for only numbers
Codabar
It has support for: numbers and some special characters (– $ : / + .)
QR Code
It has support for any character.
Limitations: 7,089 numeric characters or 4,269 alphanumeric ones
If you would like to keep the values from the field you are deleting, please read the Section “Deleting a field from the record”.
In this case you will have only the information for the first value (other fields in the table will be empty since they do not have the values).
BE CAREFUL: If you are adding a Single Field into an already existing Repeatable Row, it should not cause any problems. On the other hand, if you are adding a Repeatable Row itself at this point, then the value of the Single field will be lost (Repeatable Row will by default have 0 Rows). Consequently, you should follow these steps:
BE CAREFUL: If you are adding a new field that you want to pull to a bound table, make sure you connect it to the table immediately. If the values are entered before the connection is made, those values will not be pulled into the bound table once the field is connected to it.
If you are making a new bound Table in one Record that needs to pull the data from a certain field in some other Record, follow these steps:
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Block quote
Ordered list
Unordered list
Bold text
Emphasis
Superscript
Subscript
The Hex Code can be used as a property value by providing it as a string (under single quotes). The list of Hex Codes for the default Alchemy Colors available in any color Picker is:
Additional hex codes are available by selecting “Custom” in the Color Picker. Choosing the desired color will display its Hex Code. You can copy and paste it from there in the Conditional Formatting Expression.