** It is not recommended to read Manual on phones and smaller screen tablets, since you may not enjoy full user experience.
In this manual you will find all explanations for using the Configuration Portal of the Alchemy app. The document has structured chapters with important parts of text highlighted in different colors. At the end, there is an Appendix with schemes of process templates mentioned throughout the Manual.
Red highlights are the use cases that should always be implemented.
The Name and Identifier of a template have to be unique. The Identifier is used to reference your template in formulas and for Alchemy to distinguish different templates.
Purple highlights represent the best practices that we recommend.
If you need a border between the label and the input field you can hide the field name and add a label separately using a Label field type. You can then adjust the borders for each.
Blue highlights represent examples.
To demonstrate how the fields look with or without margins, see the examples in Figure 3.9 A and B. In Figure 3.9 A fields are separated only by blank rows and columns; see the difference between the Configuration and User Portal. In Figure 3.9 B, fields will have margins.
There are different kinds of screenshots that will help you understand the text better. Page Overview screenshots represent the whole web page of a certain section with an explanation of each element.
Specific "How To" screenshots explain different functionalities with numbered items explained.
Comparison screenshots show how the configured templates and fields look in the Configuration Portal...
...and in the User Portal.
Every chapter starts with a BASIC section (highlighted in green). At the beginning, you will find the Input requirements (information, skills, experience) needed in order to fully understand the content. At the end of the section, you will find Output recapitulation of the content presented in that section.
Some chapters have the ADVANCED section (highlighted in yellow) after the BASIC section. Also here you will find the Input requirements (usually Output from the Basic section) and Output recapitulation.
Division of chapters into BASIC and ADVANCED is based on the level of complexity of the content. It is introduced for the reader’s easier understanding and mastering configuration of Alchemy.
Administrator Training Plan
It is expected that before starting reading this manual, you have experience using Alchemy as a User. To achieve that, it is recommended that you practice using Alchemy as a User on Alchemy Startup Configuration tenant for a week. In this tenant you will find most of the examples from this Manual configured and you can gain the User’s perspective of the Configuration. In order to be a successful User and get the best out of Alchemy app, use our How To guidelines.
Once you are comfortable with Alchemy as a User, you should read this entire document. You can try to recreate the same Configuration from Alchemy Startup on another tenant where you are Administrator. Follow examples, rules and best practices from this document and combine them with the gained Alchemy User experience.
Good luck!
BASIC
⇨Input requirements:
• Basic computer knowledge
• Experience in Alchemy as User
Welcome to Alchemy Configuration Portal User Manual!
This document will be your personal guide through the Alchemy Configuration Portal, a tool that enables you to configure processes reflected in the Alchemy User Portal.
As a Configuration Administrator (Admin), you will configure custom process and record templates to fit the needs of your organization using the Configuration Portal. In the User Portal, configured templates will allow members of your organization (Users) to capture their work in a structured and predetermined way.
This manual will help you navigate around the Configuration Portal, set up your workspace, and learn all the best practices.
After receiving an email from Alchemy you can choose one of the Single Sign in options (Google Sign In, 365 Sign In, etc.) or you can sign in using an email. By choosing this option, you will receive another email where you need to set your password. In case you forgot your password, you will be able to request a reset password link to be sent to your email, by using the "Forgot Password" button on the Sign In page. That link is active for 120 hours and can be used only once.
After signing in you will be on the Alchemy Home Page in the User Portal. In the upper left corner choose the 4UAT tenant from the drop-down. In the 4UAT tenant, in the lower left corner, click on the profile icon with your initials (or image) and choose Configuration. This will take you to the Configuration Portal, on its Home Page. Left-hand side menu can be expanded by clicking on
icon. The Alchemy Configuration Portal is divided into seven sections:
You will use these configuration portal sections to define custom content, and manage general settings, users and user group identifiers (tags).
The Home Page section is showing the status of your configuration work. Here you will see if you have anything wrongly configured. You can see how changes made in the configuration are connected to other instances. From here you will push the changes made and apply them on all historical data in the system.
"Process Templates" and "Record Templates" sections contain the data elements that are common across the organization, such as standardized flows, entry forms, test methods, evaluations, documents and databases.
The "View Templates" section is a place where you can create Views (an organized way of displaying the existing data in the system) and share them with a certain user or group of users.
"Tags" and "Users" sections are tools for managing the users, how they interact with each other and with the portal across different organization groups.
In the "Company" section you can set basic information of the company such as name or logo that will be shown in the User Portal. Also in this section you can set the Theme which will save your time during configuration.
Your Alchemy Configuration data should be based on your documents, forms, work patterns, templates, how you record your lab test results, people who will use the system and their organizational chart.
Configuration data contains:
This set of templates and privileges makes your Configuration Data. The configuration data is then accessible by the users in the User Portal. Based on tags and privileges, the user will be able to see or edit data.
Configured templates and inputs from all users in the User Portal together make the System Data. The system stores:
⇦ Output recapitulation:
• Signing In
• Sections of Configuration Manual
• Configuration Data, User Data, System and User Activity Data
BASIC
⇨Input requirements:
• Basic computer knowledge
• Experience in Alchemy as a User
• List of users for your company and their emails
Users are all the people who will have access to the system in the User Portal.
1 and 2 - First and Last name
3 - Email
4 - Role - information about users’s access to the portal (User only or User and Configuration Portals)
5 - Sorting options available for each column on hover
Clicking on the user name will open the User Menu on the right side (Figure 2.2):
1 - User’s first and last name
2 - Properties - edit User information
3 - User Tags - edit (add/remove) tags assigned to the User
4 - Alchemy Beta User - making user’s access to Alchemy Beta version default
5 - Promote to Admin - enabling user’s access into the configuration portal
6 - Remove Access - remove User's access from the system. If you did not invite your user yet, "Invite User" will appear instead
Click on the +NEW USER and a window will pop up (Figure 2.3).
After filling in an Email you will be able to save the new user.
Make sure that the Email address is unique for each user.
The new user will get an activation email from Alchemy.
The activation email contains a temporary access link. The link is active for 7 days (168 hours). By clicking the link, the user will be redirected to the Sign In Page. One user can be invited multiple times in case the link expires.
From the Sign In Page, the user can choose:
Once the user receives the invitation email, the user's email address will be displayed in the list of users (Fig 2.4). When the user signs in for the first time in Alchemy, (s)he is asked to set the First and Last Name. When you see that First and Last Name are set in the list of users, it indicates that user’s sign in for the first time.
If someone is no longer working in your organization, you need to remove access for that user. Users cannot be deleted from Alchemy; instead, you can remove access for them and disable them from viewing or editing data.
User Tag is a mark of a broader group that the user belongs to. It can be a function, location, expertise, seniority, knowledge area, etc. Multiple tags can be assigned to one user and more users can have the same tag(s). More about Tags will be explained in Chapter 3. Tags.
By added tag, Alchemy will recognize privileges (Chapter 5.3 Privileges) for that user.
To assign a tag, follow the next steps (Figure 2.4):
1 - Choose the user to whom you want to assign tags
2 - Click on the User Tags tab. All Tags already assigned to the chosen User will be listed here.
3 - Click on the + ASSIGN TAGS
After the third step, a window will pop up (Figure 2.5). You can then assign appropriate tags from the list. There is no limit to the number of tags a user may have.
New users will have access to the User Portal by default. To enable access to the Customization portal for that user, click on "PROMOTE TO ADMIN" in the Properties tab (Marked with number 5 in Figure 2.2).
If you want a User to work in the Alchemy Beta version, you need to check the box “Alchemy Beta User” (marked with number 4 in Figure 2.2). This way User will be working in the Alchemy Beta version by default. Users working in Alchemy Beta can test upcoming new features of Alchemy. User can leave the Beta version of Alchemy anytime (s)he wants from the User portal, clicking on Profile icon and choosing “Leave Alchemy Beta”.
⇦ Output recapitulation:
• User Menu
• Adding Tag to a User
• Inviting a user
• User's access to the portals: User or/and Configuration
BASIC
⇨Input requirements:
• Basic computer knowledge
• Experience in Alchemy as a User
• Knowing of roles, locations and business groups of users across your company
• How to add users
In Alchemy, tags are used to describe users in a way relevant to your organization. As already mentioned in the previous chapter, it can be a function, location, expertise, seniority, knowledge area, etc. Tags are a very powerful and flexible tool used to define the user privileges and actions, and in turn how the users will interact with the system in the User Portal.
One tag can be applied to several users, and one user can have more than one tag.
1 - Tag name - is created by you. Tags can be sorted both from A to Z and from Z to A, by clicking an arrow near the column name.
2 - Selected tag`s name
3 - Users - list of Users having the selected tag
4 - Delete - deleting the selected tag on three dots
A tag can be based on function, location, department, product, process or anything else that can be used for organizing users into groups. You can create as many user tags as you need from the Tags section. Click on the + NEW TAG on the top left of the page, and a menu will appear where you can write the tag name. The Tag Name can be anything as long as you follow the rules (alphanumeric, CamelCase, starts with a letter).
Tag Names must be written using only alphanumeric characters (English alphabet letters and numbers) and underscores. Furthermore, they must start with a letter.
Write the names in CamelCase, which is capitalizing each word and removing the spaces between them (e.g. LabManager, OhioLab, FloridaHQ, TechServiceDept).
After you fill in the Tag Name, there is a required field that needs to be filled: Tag Identifier. It will be automatically populated by clicking on the field, based on the Tag Name that you choose. Tag Identifiers cannot contain space between words nor special characters. To that point, those characters are excluded from Tag Identifier. You can also choose to have a different Tag Identifier than the Tag Name, but we highly recommend to have these two the same or similar.
Concept of Identifier is very important in Alchemy’s Configuration. You will see later that every process, record, field, or group of fields has its own and unique Identifier. The system uses 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.
After you have created a tag, you can assign it to a user(s). Click on the tag name from the list on the main page (Figure 3.2 Number 1) and click on +TAG USERS (Figure 3.2 Number 2).
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.
• Tags for functions
Attached to users based on their function in your company. They are named according to the job titles of the employees. Examples are Chemists, LabManager, Sales, etc.
• Tags for departments
Attached to users based on the department of your company they belong to. They are named after the departments in your company. Examples are SynthesisLab, ApplicationLab, RnD, Production, etc.
• Tags for geographies
Attached to users based on the location where they are working. These are named according to how your company views these geographies. Examples are: Americas, EMEA, NewYork, London, etc.
Even if these are the best practices, do not limit yourself to only the above. The possibilities are endless, and by defining the right tags and privileges, you can make the user's job easier.
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:
HAS_ANY_TAG - returns a list of users that have at least one (or more) of the tags under the expression. Tags are added using the word Tag and Tag Name inside the [ ], with multiple entries separated by a comma. Examples:
HAS_ALL_TAGS - returns a list of users that have all of the tags under the expression. Tags are added using the word Tag and Tag Name inside the [ ], with multiple entries separated by a comma. Examples:
In the Alchemy Laboratory, Beth Cooper is a lab manager (has the LabManager tag). Chad Ravenal, Tom Dalberg and Dan Perry are chemists and the three have the "Chemist" tag. You want to assign an “edit” privilege to them on the lab work stage.
When adding the privilege, you will add the user tag expression HAS_ANY_TAG(Tag[Chemist]) in the "To" field.
This will allow only the three of them to edit, and not to Beth Cooper. If we want to include her as well, we need to expand the formula: HAS_ANY_TAG(Tag[Chemist], Tag[LabManager])
⇦ Output recapitulation:
• Concept of a Tag
• Creating a Tag
• Tag Identifier
• Assigning Tag to a User
• Tag Expressions
ADVANCED
⇨Input requirements:
• Concept of Tag
• Understanding of User Tag Expressions
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:
UNION - creates a list of users by adding all the users given under the all user tag expressions. In the following example, resulting users will be: a user who has tag [Chemist] or tag [SynthesisLab] plus the Lab Manager. Example:
UNION(HAS_ANY_TAG(Tag[Chemist], Tag[SynthesisLab]),HAS_ALL_TAGS(Tag[LabManager]))
INTERSECT - returns a list of users that are contained in each user tag expression. In the following example, the resulting users are only Chemists who are located in North America and work in Synthesis Lab (i.e. users who have all three tags). Example:
INTERSECT(HAS_ALL_TAGS(Tag[Chemists], Tag[SynthesisLab]),HAS_ALL_TAGS(Tag[NorthAmerica])
⇦ Output recapitulation:
• User Tag Expressions
• Formulas in User Tag Expressions
BASIC
⇨Input requirements:
• Basic computer knowledge
• Experience in Alchemy as a User
• Understanding Alchemy concepts of fields, values and records
• Concept of Identifier
Records are digital models of documents, spreadsheets, data input forms and images that the user needs to fill out in his/her natural flow of work. In a record, information is stored in a structured way, within a certain context.
Record Templates are the blueprints that are used to create Records in the User Portal. In Alchemy, you will design a different Record Template for each set of data your company needs to collect.
Records will be filled out by the user(s) in the User Portal based on the design of the Record Template in the Configuration Portal.
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 (left-hand side menu, accessed by Record icon).
1 - + NEW RECORD TEMPLATE button - for creating new template from scratch
2 - IMPORT RECORD TEMPLATE button - to import a record template from .json file
3 - Record Template Name - the name of the record template. Clicking on it will take you
to a specific record template where you can edit it.
4 - Record Template Identifier - a unique identifier of the template, used in formulas
5 - Published Version - is an ordinal number of the last published record version
6 - Record Template Description - quick info about the record (e.g., in order to distinguish 2 similar templates)
7 - The three dots - additional options (Edit, Duplicate and Export Record Template)
8 - Sorting options - (Ascending or descending) - every column has a sorting option, visible when hovered over the column label
1 - Record Template Name and Edit Button - a pen for opening the right-hand side menu
2 - Verify - Alchemy is checking if there are any errors in the configuration
3 - Grid - the working space for creating digital forms
4 - Record Template Menu - details about the Record Template
5 - The three dots, Delete - option for deleting the Record Template
6 - Record Template Identifier - an identifier which is used for referencing the Record Template
7 - Record Template Description - short info about the Record Template
To create a new record template click on the + NEW RECORD TEMPLATE. Enter a name and an identifier in the pop-up window. The Name can contain any characters and alphabets (i.e. Lab Work, New Product Development, Quote $, etc.). The Identifier must start with a letter and may contain only English alphabet letters, numbers and underscores, without spaces (i.e. LabWork, New_Product_Development, Quote etc.). As it is already explained in chapter 3. Tags, Record Template Identifier follows the same creation rules as Tag Identifier. Record Template Identifier is used by the system to reference your record template within the process, to create it or access the data from it.
1 - Record Template Name
2 - Record Template Identifier (automatically suggested after the name is typed in)
The Name and Identifier of a record template have to be unique. The Identifier is used to reference your record template in formulas and for Alchemy to distinguish different record templates.
There are some words and phrases that cannot be used as identifiers for Record Templates and Record field types. They are reserved by the system and you will be using them in different formulas. They are:
• Name
• Status
• Template
• Stage
• Process
• CreatedOn
• CreatedBy
• Id
• ParentProcess
When you choose a Name and Identifier of the Record Template and click SAVE, it will be created (Figure 4.4).
On the right-side menu, there are available options:
1 - PROPERTIES tab - Record Template name, identifier and description
2 - PRIVILEGES tab - to define which users can create, edit, view or share the records created from the Record Template
3 - Three dots - for deleting the Record Template
Under PRIVILEGES, you can define which User(s) in the User Portal will have the privilege to create, edit, share or only view Records created from this Record Template. If you choose to set the privileges, you can place your Record Template outside of the process, allowing the user(s) in the User Portal to create a 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 use this kind of Record Template (outside of the process) in the User Portal to create and view records. More about setting the privileges will be in chapter 5.3 Privileges.
Setting the privileges on the Record Template, allows users in User Portal to create records without starting a process. For this type of Record Templates there must be one alphanumeric field with the identifier RecordName. Without this field you are not able to continue with configuration of your Record Template outside of the process.
If you leave the PRIVILEGES empty on the Record Template, this implies you will later place your Record Template inside some Process Template. The Process Template consists of Stage(s). Record Templates are placed inside those Stages. In the User Portal, users will follow stages and fill out records inside of them. Later in chapter 5. Process Templates there will be a detailed explanation on how processes are created and configured.
You can start composing your record template in a grid. This grid is the working space for creating digital forms (in our case Record Templates). Each Record Template is built by placing fields on the grid. Fields are basic building blocks. There are different field types having different properties. Each field type will be explained in Chapter 4.4 Field Types. Fields, just as Record Templates, Tags, Process Templates, etc. have their Name and Identifier.
At the beginning of creating a record, think about what fields will make up the contents of the Record Template. In that phase, you can use pen and paper, excel sheets or any other kind of visualisation method you prefer. We recommend using our template from Chapter 8. Design Templates. Once you have a list of fields, you can start adding them.
To add a new field on a record template, you need to:
1. Click on the grid where you would like to add a field as seen in Figure 4.5
2. Select the field type you want to create from the list e.g., Alphanumeric
3. New Data Field will pop-up (Figure 4.6) where you need to enter a Name (1) and Identifier (2). The Name and Identifier need to be unique on the Record Template level. If you try to create two fields with the same Name or Identifier, it will not be possible: Alchemy will warn you and your changes will not be automatically saved. However, different Record Templates can have a field with the same Name and Identifier.
When you provide a valid Name and Identifier to the field, it will be created. In the right-side menu, there are different tabs available where you can configure the field as you want (See Figure 4.7. There are three different tabs available for the alphanumeric field: Functions, Values, Design). There are different tabs and options for different field types and they will be explained in the next pages.
The record template fields can be rearranged by dragging and dropping on the grid. Selecting one or multiple fields can be done by selecting the area of the grid where the desired field(s) is from any direction (left or right).
Select the field you would like to move, drag it on the grid and place it where you find it suitable. For more precise positioning of the field, you can move the selected field using arrows on your keyboard. When moving a field, it will always snap to the upper left corner of the target position on the grid. Moving the 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:
Red areas around the field types are their 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 “glued” 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(s) go(es) left and then up if there is empty space that is not occupied with 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 needed direction and size.
Blank rows and columns on the grid appear to separate fields in the Configuration Portal but, in the User Portal fields will appear “glued” together. To avoid this, add margins around the fields if you want to separate them.
To demonstrate how the fields look with or without margins, see the examples in Figure 4.10 and in Figure 4.11. In Figure 4.10, fields are separated only by blank rows and columns, there are 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 in the Configuration Portal; see how fields are separated in the User portal as due to the added margin..
Margins can be adjusted on the right-side menu in the "Design" tab. In the example shown in Figure 4.11, the bottom margin of the field Formulation Name is set to 5.
The same principle applies to fields that are placed next to each other: fields in the User Portal will be stacked next to each other if not separated by left or/and right margins. When adding margins to fields in the right-hand side 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 only 4 blank rows of the grid on the left side of the field, but you added 5 left margins on the field, the field will be stuck in the grid and on the User Portal the field will appear with only 4 margins of space. This is applicable for margins in every direction. Avoid this to be sure you have the right margins in the User Portal.
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 right-side Design tab.
In Figure 4.12, there is an Alphanumeric field type displayed (this field type will be later explained in detail). Width and Height of the field are set to 9 and 4, respectively. In Figure 4.13, Width and Height are 41 and 6, respectively.
In the gray area, the name of the field is displayed, while the white area represents the input section. In the User Portal, user(s) are filling text in the input section of this field.
When adjusting the size of the field in the Configuration Portal, the field will expand first to fit the entire name of the field (text in gray area) and then the input section (white area) will expand. The size of gray and white areas will be preserved on the User Portal. If the user enters text that needs more space than what is set for the input section, a scroller will appear, while the size of the field remains the same.
The gray area with the Field Name is the Label of the input field in the User Portal. You can choose if you want to be displayed or not in the User Portal.
You can format how the field name will be shown in the User portal. In the right-side Design tab, under the "Label Properties" you can set (Figure 4.14):
You can change the Name Size to be any number of squares (lower than the size of the entire field). If left blank, the field name will autosize to fit the name text, as seen in Figure 4.15 A and 4.15 B.
If Name Size is set to a specific number, the Name of the field will occupy the area defined by that number - see figure 4.16 A and 4.16 B.
You can change the label orientation to "Left," "Right," "Top" or "Bottom" as seen in Figure 4.17.
In Figure 4.18 A and 4.18 B, an example of the field is shown in the Configuration and User Portals. Label orientation is left.
In Figure 4.19 A and 4.19 B, an example of the field is shown in the Configuration and User Portals. Label orientation is right.
You can define if the field name is shown in the User Portal by selecting the checkbox "Show Field Name as Label" in the Design tab. If it is not checked, only the input section will be visible without a label (i.e. without a name of the field). See Figure 4.20.
Changes to the font and styles will only be visible in the User Portal and not in the Configuration Portal.
You can set Borders and Text Format for the field in the Design tab - Input Properties.
Borders are shown around both the field and the label in the Configuration Portal, while in the User Portal borders are shown only around the input field.
Text format options (Horizontal and Vertical alignment) define how text entered by the user will be aligned in the User Portal. This can be adjusted under the Design tab - Input Properties, and is the same as the Name Properties.
In the Appendix - Configuration Styling Guidelines are given rules regarding field layout for each field type.
While configuring, all changes to record, process and/or view templates are actually made in the 4UAT tenant. In order to see these changes on the User Portal, they should be pushed from the 4UAT to the main tenant. This is enabled by Integrated Configuration Environment (ICE). Changes made to record, process and/or view templates in the 4UAT tenants are automatically saved. There will be information in the right-side Properties tab that “All changes have been saved”. Even so, 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:
1 - Verify - check if your Record, Process or View Template contains any errors
2 - Publish - make the changes effective in all Record, Process and View Template(s) where change has been made
3 - Backpropagate - apply the published changes to all records and processes created in the User portal historically, not applicable to view templates
Steps 2 and 3 are done from the Home Page of the Configuration Portal in the 4UAT tenant, marked with numbers 2 and 3 in Figure 4.22.
1 - Invalid Templates section - listed Record, View and Process Templates that contain error(s) will be displayed here
2 - New Changes section - listed Record, View and Process Templates without errors that need to be published to the new version
3 - Back Propagate section - here are listed Record and Process Templates that are published and change needs to be applied to records and processes already created in User Portal (even long time ago)
4 - PUBLISH button - to publish all Record, View and Process templates from the New Changes list
5 - BACK PROPAGATE button - to apply changes made to all existing Records and Processes in the system
6 - Tenant Status - an indication on availability of your working space. If Busy, it will be orange and on hover you can track how many entities (records and processes) are left to be back propagated
Verify - First, you need to verify your configured work, by clicking the button button
in the upper right corner of your Record, Process or View Template. This way Alchemy is checking all expressions for the errors. If there are any errors, you will not be able to verify your template successfully, and there will be a pop-up message about the type of error(s) so you can easily correct them. Record, Process or View Templates that contain errors will be shown in Invalid Templates Section of the Home Page of the Configuration Portal. You can go to the Record, Process or View Template from this list and press the VERIFY button to check and fix the errors. Once you have fixed all errors and Invalid Templates section list is empty, you can continue with publishing your changes. Next steps Publish and Back Propagate will not be available (buttons are gray) until you fix all Invalid Templates.
Publish - All the changes made to the Record, Process or View Templates need to be Published in order to be applied. All unpublished Record, Process and View Templates will appear in the New Changes section of the Home Page of Configuration Portal (number 2 on Figure 4.22). Here will be listed all Record, Process and View Templates that are affected by a change.
When you create a Record or Process Template for the first time, it will be visible on the Record or Process Templates Page. It will not have a Last Published Version until you Publish it - then it gets a Version 1. Each time you make a change to Record or Process Template and you verify and publish the template, it will get a new version number. All Record and Process Templates that are not published (after the changes 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 a button
After you have successfully Published all Record and Process Templates from the New Changes section, they will appear in the Back Propagate Section (number 3 in Figure 4.22). Also, the PUBLISH button will be gray. If you create a new Record or/and Process in the User Portal, it will have changes implemented.
Back Propagate - You can implement the changes on records and processes that are already existing in the User Portal. In order to do that, you need to press the button
This way, the system will start applying changes to all records and processes existing in the system that are created using templates listed in the Back Propagate section of Home Page. This action may take time, depending on the amount of the existing data in the system (number of records and processes). You can track the progress of Back Propagation on the Tenant Status (number 4 in Figure 4.22). On hover, you will see indication about how many records and processes are left to be upgraded.
During the Back Propagation, your tenant will show status “Busy”. While the tenant is Busy, you can still work on Record and Process Templates but you can not add new Users or Tags, nor do another Publish and/or Back Propagate.
It is a good practice to Verify, Publish and Back Propagate changes you make in the Record and Process Templates frequently while configuring, and afterwards, check the effect of change from the User’s perspective, i.e. in the User Portal.
Good practice in the configuration work is to verify, publish and back propagate your record/process template after a couple of steps made in progress and then to check how it works 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 and Back Propagating them. This process can be complex and sometimes requires to be executed in phases. Some guidelines, rules and examples are given in the 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 tenant, follow the steps given below:
1 - On the Home page go to the Actions Log tab - see the list of actions that need to be pushed to the main tenant
2 - Press Push to Production button
3 - Go to Production History - see the list of all actions that have been pushed to production
Steps 1, 2 and 3 are done from the Home Page of the Configuration Portal in the 4UAT tenant, shown in Figure 4.23.
1 - ACTIONS LOG - listed Actions that need to be pushed from 4UAT to main tenant
2 - Info - clicking on the Info icon gives an information about a specific action in the pop up
3 - Undo to this action - clicking will refresh data from the main tenant to the 4uat tenant and undo all the actions prior to this one
4 - UNDO ALL ACTIONS - clicking will refresh data from the main tenant to the 4uat tenant and remove all actions from the list in the Actions Log
5 - PUSH TO PRODUCTION - applying all the configuration changes from the 4uat tenant to the main tenant (making them visible in the User Portal)
6 - PRODUCTION HISTORY - listed all actions that have been pushed to production
7 - REFRESH DATA - clicking will pull the fresh data from the main tenant to the 4UAT
After all actions have been successfully pushed to production (main tenant), the Actions Log will be empty and changes will be visible in the User Portal.
Apart from changes made on Record, Process and/or View template, there are changes that include addition of new users, creation of users’ tags and assignment of relevant tags to users. All these changes are automatically saved both on 4UAT and on production.
To delete a Record Template, go to the Record Template page of the record you wish to delete, then (Figure 4.23):
1 - Click on the edit button next to the record name(pen icon)
2 - Click on the three dots on the right-side record menu
3 - Click "Delete" button
You may only delete a Record Template if in the User Portal there are no created record instances from this template, in a process or as a solo record.
In the additional options (three dots) on the Record Templates Page Overview (Figure 4.1 - option 7) you have the option to Export a configured record template. This will export the template in a .json file that you can save on your computer, or modify using any text editor.
To import a record template from a .json file you previously downloaded, on the Record Template Page Overview select the Import Record Template option, and copy the "text" from the .json file into the dialog shown in Figure 4.25. This will create a new record template in your configuration.
Keep in mind that if you're trying to import a record template you previously exported, you should change the template name and the identifier by editing the .json file first. Also, if you are copying/pasting all characters from the .json file, keep in mind that it should be as a plain text. Conversion can change some special characters and in that case, you can not import your template.
Fields in the Record Template can be deleted by:
• Selecting the field that needs to be deleted and pressing the key "Delete" on your keyboard.
• Selecting the field that needs to be deleted, right clicking and choosing “Delete”
Fields can be copied and pasted into another record even across different configuration environments. Just select the field, do a right click and select “Copy” and go to the record where you'd like to paste it. Click the right click and select “Paste” (left image of Figure 4.26). The copied field will get the Name “Copy of Field Name” and the Identifier "Copy of Field Identifier"(right image of Figure 4.26). On the right-side Functions tab you can change the name and identifier of the field. After the record is published only the field name can be changed (as it was always possible) but the field identifier can't be changed anymore.
In the right-side field type menu, there is a tab FUNCTIONS. Most of the settings in this tab are the same for each field type. The common ones will be explained in this chapter; in further chapters the specific differences for each field type, if applicable, will be explained.
Required - checking this box will make the input for this field required in the User Portal. The user will not be able to make progress through the process in the User Portal if (s)he did not fill in all of the required fields of the record. Visually, this field in the User Portal will have a red star, and the input will be framed red to indicate that the input is required as seen in Figure 4.27 B. Also, below the record title, there will be a red indication “INVALID” and upon filling in all the required fields, the indication becomes “VALID”.
Allow Multiple Values - checking this box will allow a user in the User Portal to select multiple values. Selected values will show in the User Portal separated by commas. This is applicable to the values of Alphanumeric, Number, Attachment, User reference, Process reference, and Record Reference types of fields. Each field type will be described in detail later in the text.
Printable - This box is checked by default, and determines whether the field will be shown when printing the record or not. If you uncheck “Printable”, the field will be visible in the User Portal but will not be not printed, a blank space will be shown (see Printing Dialogue in Figure 4.28 C).
Hidden - Checking this box will not show the field on the User Portal. Hidden fields will still have values. This is useful when you do not need the user to see the value of the field, but you need it for intermediate calculations or filtering (these two will be explained on the next pages).
In the NPD Request Form (a record used in process New Product Development), the user might be asked to assess the complexity of the 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 (i.e. Low = 1, Medium = 2, High = 3). This field will not be visible in the User Portal, but you can further use the numerical values to calculate an end score or risks, etc.
Cloneable - When a user in the User Portal clones the record, if this box is checked, the value of the field will be copied in the cloned record. You should uncheck this box in the case when the user clones the record and needs to change the value of the field. Unchecked box will clone the empty field in the cloned record.
When you are configuring record templates for entering test results, formulations where lot numbers are filled in, checkboxes used in calculations, etc. make sure to have these fields not cloneable. This way, when a user clones a record, there is no risk that relevant data is going to be cloned as well. Instead of that, the user will have an empty place where to fill in specific values.
Reportable - under this field there are 3 available options:
Visibility Expression - a field can be shown or not shown in the User Portal under specific conditions. For example, a field to write pH value can become visible when a pH test is selected. When the pH test is not selected, the field is not shown. Field Visibility Expression is written in a form of formula and it returns a boolean value (true or false), which makes the field visible or not visible in the User Portal. After you get familiar with all field types available and their properties, setting a Visibility Expression will be explained in chapter 4.5.1. Simple Group.
When a field becomes visible, it will be available for the user to enter the value. If the user makes the field invisible, previously entered value will be deleted.
Field Helper Text - Any text entered here will be visible in the User Portal when a user hovers over the field. An example is shown in Figure 4.29. In the record Template called Formulation Coatings, a field Formulation Description should be filled out. When the user in the User Portal hovers over that field, a helper text will appear explaining the details about different priority statuses.
Formula Expression - to give the field a calculated value, you can write a formula in this field by following the rules from Chapter 7. Formulas. More examples are given in chapter 4.6.3. Formulas in Calculations and chapter 7. Formulas.
In the Characterization Tests record chemists are doing three measurements for pH values of a solution and at the end they need to calculate the average of those three results. The fields to input results have identifiers pHResult1, pHResult2, pHResult3. In the Calculation section of the field for the final result (with identifier FinalResult) you will write (pHResult1 + pHResult2 + pHResult3)/3. See this demonstrated in Figure 4.30.
Field is Editable - To enable the user to edit the value in the User Portal, check the "Field is Editable" checkbox. If the checkbox is unchecked, the field will not be editable in the User Portal and it will have the value given by calculation.
A field type defines what kind of input will be required in the User Portal and how it will be saved in the system. It is not the same whether you are entering a text, a number or a date; they are treated differently by the system, so a distinction must be made in the Configuration Portal. There are 14 different field types: Label, Alphanumeric, Number, Date and Time, Yes/No, Checkbox, Rich Text, Attachment, Process, Record, User, Link, Image and Button.
Each field type has additional properties you can define, other than the Name and Identifier. All field types except Buttons are explained in detail in the following pages; Buttons are explained in the Advanced part of this Chapter.
The label field type is the only one that does not have a corresponding input field in the User Portal. When this field is selected for creation from the list, a New Data Field window pops-up where you can type in and format the desired text to be shown on the Label. (Figure 4.31). The Label field type does not have an Identifier; it does not have to be unique; 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 labels when making tables in Alchemy, and sometimes for the label of checkbox fields. One label can be duplicated without any changes as many times as needed.
Labels are not visible in Views, because they do not contain any User entered information. If you put a Label that will better describe the field, and uncheck the box “Show field name as label” keep in mind that the field name will actually be the one used for filtering in Views and therefore, set one that will make the most sense.
If the name of your field is an interrogative sentence , it is better to uncheck the "Show Field Name as Label" checkbox and add a label with this question you would like to add. This is usually the case when you are creating a Yes/No or a Checkbox field type. This way you can have a shorter Name of the field because the limitation for the Name of the field is 40 characters. Furthermore, labels can be formatted and manipulated easier than a field Name.
Label fields have additional formatting options (related to field names) and can be formatted as a rich text. Labels can contain bulleted or numbered lists, headings etc. Formatting a label will reflect the changes both in the configuration and the user portal as shown in Figure 4.32.
If you need a border between the label and the input field you can hide the field name and add a label separately using a Label field type. You can then adjust the borders for each.
This type of field is one of the most frequently used. What the user enters in the Alphanumeric field type 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.
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. See Figure 4.33.
The levels in which the field must be unique are:
You are configuring a Record Template Company, which is used to create a record Company. A Sales person will fill out this record when (s)he needs to have info about the new company in the system. You will create a required alphanumeric field named “Company Name” where the user will fill out the name of the company that (s)he is adding. You should mark the value of this field to be unique so only one company with that name (value of that field) exists in the system.
On the contrary, you will add 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, instead of having input in the free-form, you can limit input to a list of predefined values. It will be shown in the User Portal as a drop-down list of these values and users have to choose one or more of them.
Under the tab "Values," you can add the values clicking on the +NEW VALUE. A sidebar will open where you can enter the predefined value you wish to have (limited to 80 characters per item). After you add the value, you will see it in the list under the Values tab (Figure 4.34).
If you want to allow users in the User Portal to choose more than one value from the drop-down list, make sure that checkbox “Allow multiple values” is checked.
Alphanumeric type of field can be used to create Barcode on your Record Templates. You need to create an alphanumeric type of field and in the field’s Functions tab, set the desired Barcode Type from “Not a Barcode” value to the one you need to configure (Figure 4.35). There are several types of Barcodes supported in the alphanumeric field and these are listed in Appendix D- Barcode Types together with types of characters needed and limitations.
Once you set a Barcode Type on an alphanumeric field, you need to set the Formula Expression that will generate a visible and scannable barcode in the User Portal.
When an alphanumeric type of field is used for Barcode, it can not have predefined values.
In a number field (e.g. Volume, Weight, pH) users can enter any number in the User Portal. Decimal places are divided by a dot, not by comma. Also in the User Portal, users must enter a decimal number using dot.
In the Configuration Portal you can define the number of decimal places that will be visible in the User Portal. You can set this in the right-side Field Properties tab, under the Decimal Places Format.
The system will save the full number entered or calculated, preserving all the decimal places and using them in further calculations.
However, if the entered or calculated value has more decimal places than defined, only the defined number of decimal places will be displayed in the User Portal (rounded). While entering the data, the user is able to enter and see an unlimited number of decimal places. Once the user clicks elsewhere, the number of decimal places entered in the field will be rounded to the defined number.
The Number field type, like the Alphanumeric, can have a defined uniqueness on the System, Process or Record level.
In the Properties tab of the number field you can fill in the scientific notation checkbox. Use this if you need 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.)
Similarly to the Alphanumeric field, you can add a dropdown menu with predefined values under the "Values" tab.
Note that some inputs may appear as a number, but are actually meant to be alphanumeric. For example a phone number, a request number, or a lot number - should be filled in alphanumeric fields, and thus you cannot perform mathematical operations with them.
Some best practices for numbers input in the Alphanumeric field type are: LOT number, Request No., Phone, ID number, SAP material code, Zip Code.
For the Number field type that can be used in different calculations are: pH test result, sample mass, viscosity, batch size.
Date & Time is a field in which the user can select the date and the time in the User Portal (e.g. , Shipping Date, Sample Received Date). This type of field can't have multiple values, and it can't have a predefined value list selection.
You can change the format the date is displayed in. By default, it is MMM DD YYYY hh:mm (Feb 23 2019 13:45). To change it, write one of the corresponding formats in the Advanced Settings section under Date & Time Format. See different options for Date and Time formats in Table 4.1.
The Date and Time fields can also be subtracted, for example ProjectDuration=EndDate-StartDate. But the field for ProjectDuration needs to be the Number type in order for this subtraction to happen. The result will be presented in milliseconds but it can easily be converted to hours or days by using the appropriate mathematical formulas.
You can use the DATE_FORMAT() function on these types of fields in order to convert them to an alphanumeric value using the same formats as in Table 4.1. The function is further explained in Chapter 7.
It is common to use 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. More about this function is explained in Chapter Formulas.
This field type is represented as a radio button in the User Portal where the user can select either "yes" or "no," and the value is saved in the system as boolean (true or false). If neither "yes" or "no" is selected, the system evaluates it as "false."
As Admin you can pre-set the value of the yes/no field by writing true or false in the Advanced Settings, under the Calculation Formula. You can also opt to make this default formula editable.
After the Users select one of the options (yes or no), they cannot unselect both again.
The yes/no fields are most commonly used as a gate where further transitions depend on the value of this field (e.g. Lab Work Approved?). Also they are good for dictating some visibility conditions (Is the pH test needed? If Yes a field for entering the result will become visible, as seen in Figure 4.36).
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. That means that in the User Portal, it will be unchecked and could be updated to checked and the value changed to true.
It is most commonly used as a confirmation field that something is done or needed: Sample sent, pH test needed, Raw material received, Formulation accepted.
If a checkbox is set as a required field, it has to be checked by the user in the User Portal in order to, for example, complete the stage and continue through the process.
As mentioned in Field Type Label, if you are making field names that will contain a question, it is better to use a separate field of type Label for the question and have a checkbox field type with the "Show Field Name as Label" unchecked. This is usually most applicable to Yes/No and Checkbox field types.
Rich Text field type is used to input formatted text in the User Portal (e.g., Description of the Request).
Rich text is different from the alphanumeric field type in the following aspects:
In Figure 4.37 you can see the edit window for Rich Text. There are a couple of additional options for formatting as well as the hyperlink option and image attachment.
Attachment fields are used to enable users to attach files to records in the User Portal (e.g., SDS, Quote, Sample Image, Contract). The file preview size is set by the configured field size. Here are the settings:
The size of one square in the configuration portal grid is 8px x 8px.
Supported attachment file types, displayed as thumbnails are: .pdf, .xls, .xlsx, .png, .doc, .docx, .jpg, and .txt. When you click on the field in the user portal, the attached Images are previewed in a modal window on the same page and 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 should set that in the field properties set up.
To allow the User to have multiple attachments, in the field properties the “Allow Multiple Values” should be checked. As shown in Figure 4.38.
Record field type is a field which you can use to create a connection with another record. It enables the User to access a specific record and its data (values in fields). In the User Portal, it will be shown as a dropdown list with all Records created from the referenced Record Template form (e.g. all Request records for the Lab Work process or all Company records created for the process Opportunity). When choosing a record from the dropdown list it will be shown as a hyperlink to that record.
The creation of the Record field type is shown in Figure 4.39.
Figure 4.40 shows how the Record field type looks in the User Portal.
When creating the formulation (from the Formulation Design Record Template), a Chemist needs to choose desired materials. In the Formulation Design Record Template, there is a field Material. By clicking on that field, a drop-down list of all materials in the database will appear, and a Chemist can choose the desired material.
This field Material is of the type Record, and it 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).
Further, a 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, a Chemist will see a drop-down list of all Lot numbers created for this material. This field is also of the type Record, and it is referenced to Record Template MaterialLot (i.e. connected through this field to all available Lot numbers.
In the Advanced Settings for the field type Record, an additional section is available called Record Filter Criteria. Filling this section, you can filter down the records the user can choose from the dropdown list of the record field in the User Portal. This is done by setting the right Filter Expressions in the Record Filter Criteria.
There is a certain form in which Filter Expressions are written. Filter Criteria can be set for Record field type, Process field type and User field type. The latter two will be explained when Process and User types of field are explained.
Filter expressions for record field type are written in this way:
- Result - a keyword which refers to the referenced Record Template chosen upon field creation.
- .(dot) - is used to bring up the second level of narrowing results of the filter, from the chosen referenced Record Template to its specific field
- Identifier of the field that is located in the referenced Record Template. Selection of the field identifier depends on the purpose of the filter that needs to be set.
- == - a command which “equals” left side with the right side of the filter expression
- another Field Identifier - this field is located in the actual Record Template (the same where the field for which filter expression is set).
Filter Expression is explained in an example:
As seen in the previous example, a Chemist can choose the Lot Number that needs to be used for material in the formulation. First (s)he chooses the desired material (record field type giving list of all materials in the database - referenced Record Template is Main Material). Then (s)he chooses the Lot Number (record field type giving a list of all lot numbers in the database - referenced Record Template is Material Lot). Clearly, a Chemist does not know by heart which Lot Number belongs to which material. In this case, there needs to be a filter applied on the field Lot number, such that it will show only Lot Numbers of the chosen material.
Correct filter expression is: Result.Material==Material
What it does: Shows 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 field identifiers completely match, but that is not always the case.
Besides this, there can be another type filter expression set for the record field type 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 Product Record Template 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 needs a list of products that are of a type finished good. In the pH Test Record Template, there is a field of a record type, with the referenced Record Template Product.
The needed Filter Expression is: Result.ProductType==’Finished good’
What it does: Shows only a list of records Product in which the field Product Type (Result.ProductType) is set to (==) a predefined value ‘Finished good’. Since a predefined value is basically text, it must be written under the single quotes(‘). If not written under single quotes, the system will treat it as an identifier.
More examples for the Record Filter Criteria formulas are explained in chapter 7. Formulas and in the Advanced part of this chapter.
Process field type is a field in which you can reference a process in the same way the record field type is referencing a record. It enables the User to access 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 (e.g., Related Lab Work). You can use this field type if you want to have a hyperlink to the other process, if you want to access data from that process, or if you need a system data for that process (who created that process, what its status is, etc. chapter 7. Formulas, includes the whole list of system data).
While creating it, you have to define which Process Template you are referencing (creating and designing Process Templates will be explained in detail in chapter 5. Process Templates). 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.
See the Process field type creation in Figure 4.41. It is similar to the Record field type creation, but instead of choosing the referenced Record Template(s), you will choose the referenced Process Template(s). In the User Portal, the representation is the same as for the Record field type shown in Figure 4.40.
There are record templates that are standardized across the organization. You can use that kind of record template inside different process templates. If you need only a record from the specific process, you should use the Process field type in order to distinguish from which process you would like to pull that record information.
In the Advanced Settings for the field type Process, an additional section called Process Filter Criteria is available. Similar to the Record Filter Criteria, in this field you can write Filter Expressions to filter the processes which will be available from the drop-down list of the process field type in the User Portal. After a process is selected on the User Portal, it will create a link between processes. Later, you can use that connection to navigate to that process quickly. 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.
Form of Filter Expression is similar to the one for record field type:
- Keyword Result,
- . (dot),
- Expression: Process,
- Command ==,
- Proces field type Identifier
In the process Lab Work, there is a record Work Plan. In this record there is a Process field type with Name: Related New Product Development (identifier RelatedNewProductDevelopment). In this field the Chemist is choosing the process, a previous New Product Development, which is connected to the current Lab Work process on which (s)he is 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 (in this case it's the desired status of the process).
You can define that the user can only choose from Active or Completed Lab Work processes, or only the Lab Work processes that have pH tests. More about FIlter Criteria formulas will be covered in chapter 7. Formulas.
After you've made a Process field type, that field 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 dropdowns. More on this is explained in Chapter 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 “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 the repeatable group.
The User field type is used to reference a User/s in a record (e.g., Technician, Sample Received by, Approved by) , similar to referencing Processes and Records in their field types. In the User Portal, this field is showing the list of Users. In most cases, this list needs to be filtered in order to show only users of interest, depending on the context.
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 User field type follow the form:
- Keyword Result,
- a dot,
- Expression: UserTags
- Command: ==
- Tag expression: Tag[TagIdentifier]
While approving the Lab Work 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 type field with the User Filter Criteria set:
Result.UserTags==Tag[Chemist]
This expression will filter the list of all users and in the User Portal will show only users who have tag Chemist.
In Figure 4.42 the User field type in the User Portal is shown.
There are some words and phrases that cannot be used as Identifiers for User field types. They are reserved by the system and you will be using them in different formulas. These are:
Link field type is used to paste URL links which lead to a new website (intranet or internet) (e.g., Customer Website). In the User Portal, the user can define Link Text and Link URL by clicking on this type of field. Entered link text will be blue, and clicking on it will show three available options: “go to link”, “change” or “remove”. Choosing an 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.43.
Multiple links are enabled by putting this field inside a Repeatable Row group, the same as for the attachment field type. The Repeatable Row group will be explained later in chapter 4.5.2. Repeatable Row.
The Link field type, like the Alphanumeric, can have a defined uniqueness on the System, Process or Record level.
This field enables you 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 image is 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 the company’s logo on records you need to print (i.e. reports, quotes…). You can also attach a PDF file. In the User Portal, it will be displayed as a link. Clicking on a link, User will open a PDF in a new tab. For example, if you want to have a Test Method in the PDF available for the User who is performing the test. In one click, the user can open and check the Test Method.
In addition to the fields and field groups, 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 on the User Portal, and it's function is to move all the fields below to a new page when using the print record option in the User Portal.
Under the section Company of your Configuration Portal, you can set Theme. Here you can pre-set the default layout for all field types. You can expand each field type and set the dimensions, margins, Advanced settings, Name and Input properties, etc. for each field type. Once this is done, each time you create a field in the grid, it will have the settings configured in the Theme. This is saving your time during the Configuration work. In the Appendix C - Configuration Styling Guidelines are given rules regarding field layout for each field type.
Theme can be imported from another tenant or exported to another tenant.
⇦ Output recapitulation:
• Record Template: create, configure, delete, export/import
• Field in a Grid: margin, size, advanced settings
• Field types
• Verify-Publish-Upgrade steps
• Concept of Calculation Formula
• Visibility Conditions
• Filter Expressions
BASIC
⇨Input requirements:
Previous output
Field Groups in Alchemy are used to connect multiple fields in a certain context. You will use them to define how fields are treated in the system. When a group of fields is wrapped in a field group type, 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 chapters.
In the Configuration Portal they are created in a few simple steps (Figure 4.45):
1 - Put your cursor on the grid and click wherever you want to place the group
2 - Select which type of group you would like to create. They are divided by a line from field types.
3 - The group appears as a darker gray field. Place the created group on top of the fields you would like to group
4 - Resize the group so that the darker square is covering all the fields you want in that group. The Design option for the group is on the right-side menu, similar to the field types. The group needs to be selected in order to change the dimensions, margins and advanced settings.
Each group type has a special setting requirements for margins. Those will be explained in the following chapters, for each group type separately.
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, an unexpected behavior might occur in the user portal.
If you need a border between the label and the input field you can hide the field name and add a label separately using a Label field type. You can then adjust the borders for eachWhen you add a 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 also shown in Figure 4.45 - Step 5, under number 5, you can see that 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 Colum 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 and 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:
1 - when fields are related to the same topic
2 - when fields need to have the same visibility condition
3 - when fields need to have the same margins, it is easier to set up the group margin instead of margins for multiple fields
4 - when fields represent labels of a table
On the right-side menu, groups also have different additional options, just like field types have. The first part is for the design elements, 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/calculations to work properly.
In the Functions tab for the Simple group type, you can see the part where you can set the Field Group Visibility Condition (Figure 4.46).
In the User Portal, the evidence of groups is subtle. When the Field Physical Properties Needed (checkbox field type) 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 Physical Characteristics can be grouped together. Properties like pH, Density, 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 Advanced Settings in the Group Visibility Condition write the condition for the visibility (e.g. PhysicalPropertiesNeeded == true). The margins of this group can also be set, so all the fields inside will have the same margin. See how this looks in the Configuration Portal in Figure 4.46.
As already mentioned before, Visibility Conditions can be set for the field, and 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 Condition is written in a form of formula, using Field Identifier, operator (such as ==, IS SET, NOT SET, IN, NOT IN,...) and a field value. Fields (field identifiers) and field values are chosen depending on the desired condition of the visibility. Complete list of available operators is given in chapter 7. Formulas.
Most frequent cases of setting the Field Visibility Conditions are:
Chemist is filling out the Characterization Tests record, and (s)he is 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, not otherwise. See Figure 4.47 B. - only the pH test is selected. The identifier of this checkbox field is pHNeeded. The field where User should write the result for the pH test has the name pH Test Result and identifier pHTestResult. In the advanced settings of this field you will put the Visibility Condition:
phNeeded == true
as seen in Figure 4.47 A. In this case, only when the checkbox pH is selected 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, 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 condition 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 the record type field. The form in which Visibility Condition is written is similar to that of 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 Identifier of the field, expression == and at the end the value of that field required for the visibility.
In the record Work Plan, Chemist chooses the tests to be performed by selecting the checkboxes (identifiers: pHNeeded, DensityNeeded, ViscosityNeeded). Later in the record Formulation Design, (s)he will fill out the results. Fields for entering the results should be visible for those tests which were selected (checkbox) in the record Work Plan. To configure this you need to set the connection between record template Formulation Design and Work Plan. In the record template Formulation Design make a record type field Related To Work Plan (identifier RelatedToWorkPlan) and select record template Work Plan as a referenced record template.
Field for entering pH Results (pH Result) should have the following visibility condition:
RelatedToWorkPlan.pHNeeded == true or
Record[WorkPlan].pHNeeded == true (in this case you don’t need RelatedToWorkPlan field)
The same goes for other fields (Density, Viscosity) using the appropriate identifier.
This way, the field's visibility can depend on the selection in other record template.
There are also various operators available (chapter Formulas) that can be used in the Visibility Conditions and it will be explained in the ADVANCED section of this chapter.
You can delete the group in the same way the field is deleted: selecting the group and pressing “Delete” on your keyboard or selecting the group and after right-clicking choose Delete. Deleting the group will remove the group only, fields inside the group will stay.
You can Copy/Paste a group by selecting it and then right-click, choosing Copy/Paste. This action will paste only the group, not the fields inside the group with all the settings copied: the design elements as well as the visibility condition.
If you want to copy/paste more fields, or fields and group(s) you can do that by selecting all wanted fields/group(s) together and then right-click, copy/paste. Selecting multiple fields and/or groups is done by shift+left click on each desired field/group or selecting the area of the grid where desired fields/group(s) are.
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:
1 - when you want to make horizontal tables
2 - when you want to allow the user to add multiple links under each other
3 - in general, when you need a field or a group of fields to repeat under each other (for example, when you want to have trials and test results in the table it could be a Rich Text field type or an Alphanumeric)
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, explained in Chapter 4.5 Field Groups. The gray square that appears has slightly bigger dimensions, and the Advanced Settings has an additional field called Repeatable Options explained in the next subchapter.
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 behaviour 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 type fields (labels). All labels should be either in a simple group, either outside of any group.
The next set of fields are the input fields that will be placed under the labels on the grid, 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, a box “Show field name as label” should be unchecked. However, the field names will be visible and available in the View Templates (and not the labels), so make sure they are also self-explanatory.
Following are the steps for creating a table in Alchemy:
In the Advanced Settings of each Repeatable Row group, there is a field called "Repeatable Option" where you can choose different options from the dropdown list. Options are:
1 - Defined by User
2 - Determined by Formula
3 - Determined by Record Reference
4 - Determined by Filter
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. User is allowed to add as many rows as (s)he needs, to delete or clone rows using the appropriate icons in each row.These options (delete and clone) are available for multiple rows selected as well. Rows can be rearranged in the table by 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 a Label field for column header. Then create a field(s) 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 the 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. See how it is done in the Configuration Portal (Figure 4.48 A and 4.48 B) and how the user will see it in the User Portal (Figure 4.49 A and Figure 4.49 B).
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 the Appendix C - Configuration Styling Guidelines are given rules regarding field and group layout for each type. Also, some general rules regarding table layout and best practices are 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 number field type. 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. In Figure 4.50 A and Figure 4.50 B you can see how the table looks in the Configuration and User Portals.
When you are making a table, in the Configuration Portal grid, in the first row are label fields inside a simple group, and in the second row are input fields that are repeatable. Borders should be added to the 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 condition 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 conditions 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 group.
⇦ Output recapitulation:
• Concept of Group and Group types
• How to make a table in Alchemy
• Repeatable Row group options: defined by User
ADVANCED
⇨ Input requirements:
• Concept of record template, field types, identifier
• Interconnection of records via record reference
• Accessing the data from other records (dot)
• Repeatable Row Group
• Basic concepts of: Visibility Conditions, Filter Expressions, Calculation Formula
As already mentioned, in this ADVANCED section will be explained other three types of Repeatable Options (other three types of tables in Alchemy). These are: Repeatable Options determined by Formula, determined by Record Reference and determined by Filter. While configuring, most frequently used types of tables are Repeatable Options determined by User and Repeatable Options determined by Record Reference. Evenso, the other two types of tables are extremely useful in certain cases.
If you select Determined by Record Reference, fields Referenced Record Template, Referenced Record Fields and Filter Criteria will appear. With this repeatable option, your goal is to connect two different records and pull the required data (possible options are connecting two records from the same or different processes). To explain this better, imagine you have two records R1 and R2. You are currently in the record R2 making a table where you want data from the record R1 to be copied.
Following the theoretical example in the previous chapter, you can make a table that allows you to pull the information from other records to a table. That table is automatically filled (User can not add or remove the rows in it) and is accessing 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 and related to the Record Template where the table is.
A chemist is making a plan for the experiments. (S)he is doing a lot of literature search 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 and related to one Work Plan. To make a parallel with the theoretical example from the previous chapter, Work Plan is Record Template R1, and Literature Search will be Record Template R2.
In the User Portal, in the record Work Plan, there will be a table with as many rows as Literature Searches related to that Work Plan are created. See Figure 4.52 for the graphical presentation.
Now that the two tables are connected (bound to each other), you can access other fields (of any type) 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 Chemist needs more details, you will add some more fields in the Literature Search Record Template: Literature Link (field of a type link, identifier: LiteratureLink) and Literature Comments (field of a type rich text, identifier: LiteratureComments). In the Work Plan Record Template, next to the Related Work Plan 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.53.
By selecting the Determined by Formula option, another field for the Calculation Formula 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 (s)he 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. Field type is number, name of the field is Number Of Samples, 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 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 (Figure 4.54).
Another important use case for repeatable row determined by formula will be introduced. 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. User composes this table by adding rows in it. Each row is for one material in the formulation. Material is a record type field and users choose from a dropdown which material is (s)he adding in the Formulation. Additional fields are needed in the table, containing information related to the chosen material: material type (pulled from material record), mass of added material to formulation (number field, free entry), volume of material added to formulation (calculated from mass of 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.55. All 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 record Formulation, but you don’t want to allow the user to add rows here. You want the user to see all materials and amounts present in formulation before testing it. This is where you will use a repeatable row option determined by formula.
As for any kind of 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 Formulation record so types must coincide. On the record Characterization Tests there is a record reference field where Formulation Record Template is referenced (identifier FormulationToTest). User will choose here which Formulation is being tested, and the table with materials will be pulled.
Place a repeatable row over the fields and choose a repeatable row option determined by Formula. In the Calculation Formula place the following expression:
FormulationToTest.Group1.Row Count
This formula will count and create the same number of rows found in the Materials table (Figure 4.55, identifier Group1) from the Formulation record that is selected in the field FormulationToTest. Each field in the table needs to have a proper calculation in order to pull the desired value:
FormulationToTest.Material - This will pull the selected Material in the Formulation Table
FormulationToTest.MaterialType - This will pull the type of the material selected
FormulationToTest.AddedMaterial - this will pull the amount of material that user has entered
See the figure 4.56, in the Characterization Test record, a table is created and 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. After that, 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 (similar to those is described in chapter Record Filter Criteria).
A Chemist needs to fill out the LW Report record for the samples tested. Let’s build on the previous example. There is a Characterization Tests record filled out with the results. In the LW Report 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 Record Template LW Report, make the input fields (type number) for pH, Density and Viscosity. You need to make a record field type Testing and make a reference to 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 records Characterization Tests 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.57
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.
Repeatable Column group type is enabling the fields inside the group to repeat next to each other in columns. Use cases for the Repeatable Column groups are:
1 - when you want to make vertical tables
2 - when you want to allow the user to attach multiple files next to each other
3 - in general, when you need a field to repeat next to each other (it could be a Notes field as a Rich Text field type or an Alphanumeric)
The creation steps, rules and logic are the same as for the Repeatable Row, explained in Chapter 4.5.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 (chapter 4.5.1 Simple Group). For this Simple Group in this context the same rules apply, Top margin 4 and Left 9.
If the Repeatable column is determined by any other Repeatable Option, the Top margin also needs to be 4 but the Left margin isn't mandatory.
When you are allowing the user to add multiple attachments, it is a best practice 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.
As already mentioned at the end of chapter 3. Tags, Tag Expressions can be combined using 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 chapter 6. Formulas. There are 4 types of formulas in Alchemy:
It is already said that a field or a group can be visible in the User Portal under certain condition(s) (chapter 4.5.1 Simple Group). Visibility condition is written in a form of expression. More complex visibility conditions are obtained using different operators and/or functions. Most frequently used are:
Following examples are demonstrating use cases and formulas for Visibility Conditions with the use of operators.
You are configuring 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, checkbox with identifier pHNeeded) which can be selected if that test is needed.
Chemists might want to see the step-by-step instructions for experiments they need to perform. Using the Record Template Test Method, Chemists can create records for each standard experimental procedure.
In the record template Characterization Tests, the user chooses which test (s)he needs to perform by selecting the appropriate checkbox. For that you need to configure a checkbox type field (for example identifier pHNeeded). Next to that one, you can create another checkbox which the user can select if (s)he wants to see and choose the experimental procedure (identifier ShowProcedure). Next field needed is a record type 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 a record field for Test Method you need this condition:
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. (S)he can select out of 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 type field: Test Results). In the visibility condition of this label following visibility condition should be applied:
pHNeeded==true OR DensityNeeded==true OR ViscosityNeeded==true
If any of the tests are selected, the label becomes visible pointing where the results can be entered.
In the Characterization Tests record, 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. Chemists 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: one when only liquid samples are chosen, and the other table for cases when solid, or solid and liquid (multiple values) are chosen. The visibility condition 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 condition 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 hence they need to be under single quotes. These values are defined in the field Type Of Sample so 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, Chemists can make some modifications in the test procedure. These modifications need to be noted. You need to configure a field of type yes/no (identifier ModificationsApplied) and a rich text field where modifications can be described. Rich text field needs to be visible only if “yes” is selected in the yes/no field (field will have the value true). Visibility condition for the rich text field is:
ModificationsApplied IS SET AND ModificationsApplied==true
Yes/no field needs to be set so operator IS SET is used. Second part of the visibility condition also needs to be met so operator AND is used.
As already mentioned Filter Criteria are used in fields of type record, process and user, and also in repeatable options of a table determined by 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 and operators can be used in them as well. Here are some examples.
In the process Lab Work, there is a record Work Plan in which the Chemist is planning the formulations and tests (s)he wants. Within the same process, record Characterization Tests can be created to capture test results data.
In the Configuration Portal, 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, 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 chapter 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 (Result) 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 calculation formula set on the field RelatedToWorkPlan).
List of all operators available is given in Chapter 7. Formulas.
Filter Criterias cannot recognize location given in the square brackets [ ].
In the first example, you learned how to set filter criteria to result only the desired records in the current process (example of filter on the record field type). You can set the filter using the system field also on the process field type.
In the Formulation Design record template, the Chemist needs to choose the product. 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’). Operator != is giving all the processes with the status different from ‘Voided’.
Here are general filter criteria (with examples) that can be used:
You may need to reference Formulation Design records but only those ones which have the status Valid. This is a system data and the valid status means that the record is fully completed (correctly according to predefined rules). In the stage where you need this information you will make a record field type (identifier: ValidFormulation). In the Reference Record Template 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 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 - can be used in lookup to access the field with identifier NumberField in the resulting record. You can write the expression Result.NumberField < 1and 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 identifier TargetBatchSize (number type field) where the mass of the formulation is determined.
In the record template Characterization Tests you will make a record field type (identifier: ConnectedToFormulation). In the Reference Record Template you will choose Formulation Design. If you leave the settings like this chemists 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' - can be used to filter (mainly) records based on an 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 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 Calculation Formula, 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.
In the Advanced Properties for most of the field types, you can set the Formula Expression. Using this formula, the system will calculate and give a calculated value to a field. Detailed and systematic explanation on how to write formulas are given in chapter 7. Formulas. For now, we will focus on three main groups of formulas that are commonly used in configurations. These are:
1) Mathematical formulas
2) Calculation formula for the record type field
3) IFS conditions
You have already seen a simple example of a mathematical formula in the example of calculating average pH value of 3 measurements (pHResult1 + pHResult2 + pHResult3)/3). This group of formulas are using mathematical operators and are used only in number field types. Values of number fields are numbers and you can perform mathematical operations with them in Alchemy. Detailed list of these operators is given in chapter 7.4.4 Mathematical Operators. It is important to remember that operators are applied on the field identifiers, and outcome (what the user sees in User Portal) is the result of field values (i.e. numbers) involved in mathematical operations.
Another example that was already shown is setting a calculation formula for the record type 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 handy if you need to have a specific record already set, instead of letting the user choose from the drop-down list of records available on that field. For example, within a Lab Work process, various records can be created: 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 type field, referencing the record template of interest. In the Calculation of that field write Record[RecordTemplateIdentifier]. This formula will give this field a value of the last created record in the current process.
Last, but not the least group of formulas are those with function IFS.
This operator checks whether one (or more) conditions are met and returns the value of the first condition met. It 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. Here is an example:
In the Work Plan, the Chemist can set the target pH, viscosity and density values for each formulation (s)he wants to create and test. You can configure a repeatable row table determined by the user where (s)he can add the desired number of formulations and define the target range. Fields in the table should be of the type number with identifiers TargetpHFrom, TargetpHTo, TargetDensityFrom, TargetDensityTo, TargetViscosityFrom and TargetViscosityTo.
Later in 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 get the value (show one of the two predefined values) 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 type 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 (it does not have to be so, identifiers can differ if you want). Pull the data by setting a calculation formula 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, you need them 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. 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 and hence the single quotes.
First condition is met if both left and right side of the AND operator are satisfied (i.e. number entered in field pH is ≥ than number set as pH target value From and at the same time number entered in pH is ≤ than number set as pH target value To). Another operator shown here is comparison operator >= that compares values of two numbers.
Second condition is simply written with true (because IFS function needs a boolean value). It 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 appropriate field identifiers for density and viscosity.
IFS function can be combined with many other operators and functions and are very useful in configuration work.
As already mentioned at the beginning of the chapter 4.4 Field types, there is a button. Evendough buttons are created in the same way as any type of field, they are not fields and they do not have value. Buttons are created in Record Template when you want to allow the User to perform a certain action only when (s)he desires. Clicking the button, the User can create a new record, task, stage or process, recalculate values in fields and many other actions. In the User Portal, the button is displayed as a blue (by default but color can be changed) area with the text on it, and the User can only click on it, if (s)he wants.
In the Configuration Portal, the button is created by left-clicking on the Grid and choosing “Button” from the Menu. After setting the field name and identifier as for any field type, there is a required field “Caption Text” under the Button Properties. The text entered in this field will be displayed on the blue area in the User Portal.
Button can be placed inside the Repeatable Row. That way, a user can click on a button in the row and trigger action to be performed in that specific row only, by using keyword CurrentRow. You can find an example in Field Action - On Change Field in a specific row.
In the Advanced Settings, instead of Calculation Formula there is a field Action. Under this part, the script is written. Composing the script needs to follow certain rules and it will be best described in the following examples.
In the Record Template Formulation Design you are configuring the table using the Repeatable Row option defined by User. User can add as many rows as needed for the formulation that (s)he is composing. Each row is for one component in the formulation (record field type where user can choose the desired material from the drop-down list of all available materials in database) and each row contains several number type fields for: mass of added material (identifier: AddedMaterialg), density of material (identifier: MaterialDensity) and volume of added material (identifier: AddedMaterialL). First one is filled in by the user, second one is automatically pulling the information from the record of the selected material and third one is calculated using the formula: AddedMaterialg/MaterialDensity.
There are two more fields needed (number type) outside of the table and those are: Total Volume (identifier: TotalVolume) and Target Batch Size in liters (identifier: TargetBatchSizeL). See Figure 4.58 - to display the fields better a table is shown, not a Configuration Portal. Total Volume has the calculation formula 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 button will automatically recalculate all masses of materials added (i.e. normalize) to have the total volume equal to target batch size.
The script for this button is very similar as the calculation formula 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 single sign = instead of ==. Usage of == sign is already explained in the section 4.4.9 Record field type, under Record filter criteria. It should be readed as “gets the value of” so in this case, after the click on button, a field that had a value entered by the user gets a new value of the result in the calculation (right side of =). See what happens to the values in the table in the User Portal before and after clicking the button “Normalize”.
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. Last added material is for example solvent and the chemist fills a mass of solvent in the table. (S)he wants to recalculate only the mass of solvent in the formulation, to fit in the target batch size. In that case, (s)he needs to select the row in which the solvent is and to click on a button “Yield”.
Action on 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 button “Yield”.
Let’s say the chemist wants to create a new formulation. In the Record Template Work Plan there is a user defined table where (s)he can plan the number of formulations: add a row for each formulation and set the target pH, viscosity and density range for it. See figure 4.61. In the Configuration portal, the Repeatable Row Group of this table has the identifier ExperimentalFormulaRRGroup. There is also a checkbox field with the identifier FormulaCreated (under label “Added”) and its role will be explained in the next paragraph. In the Functions tab of this checkbox, “Field is Editable” should be unchecked. This will prevent a user from filling out the checkbox - it should be filled out only by the button.
You need to configure a button that will automatically generate as many records (from Record Template Formulation) as there are rows added in the table by the chemist (Figure 4.61). In this example two. Before creating that button you need to create a new field of a type record that will be not cloneable, not reportable, not printing and hidden. This field will not be visible anywhere but in the Configuration portal 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. Script that needs to be in the Action 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 analyse 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. for loops are generally used always when you need to do something with the table: 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. var is a variable and in our case it is the row of the field. Loop starts from the first row, i.e. i = 1;. Last part i = i + 1; is an increment, i.e. how to go through the table (in this case each row, i = i + 2 will check every second row). Middle part i <= ExperimentalFormulaRRGroup.RowCount; defines when should the loop stop. In this example, as long as i is less 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).
When the for loop is defined, the block of script which will be executed in one loop step must be always 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. We will see later that this is unlike in the line of command when it means end of the command.
if(FormulaCreated[i] == false)
The first operation inside the loop is a condition. if is a function which checks a condition defined in the parentheses. As said at the beginning of the example, FormulaCreated is the identifier of the checkbox field and by default is not checked (i.e. has the value false). Row in the table is defined by index [i], and it 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, this checkbox(es) 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 i.e. formulations in the table and checkboxes are 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 ;.
First of the commands: FormulaHelper = CREATE_RECORD('Formulation', 'LabWork', Process, 1); will assign a value to the record type field with 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 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).
Second command FormulaHelper.FormulationName = LabWorkNumber + ' ' + ExperimentalFormulaName[i]; 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. In this case, through the record type 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 it serves to track a Notebook process by giving each a unique number. Empty space under single quotes ‘ ‘ is basically text and serves to divide two values (without it, two values appear “glued”). 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.
Third command FormulaHelper.TargetpHfrom=TargetpHfrom; 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 Record Template 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, i.e. for each formulation that (s)he wants to make. These target values of pH, viscosity and density are simply 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), appropriate new record(s) are created. As already said, the last command FormulaCreated[i] = true; will fill in the checkbox FormulaCreated (give it value true). Script runs through each row in the table and when it is done for all the rows, the loop ends. See Figure 4.55, two Formulation Design records created after clicking the button.
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse varius enim in eros elementum tristique. Duis cursus, mi quis viverra ornare, eros dolor interdum nulla, ut commodo diam libero vitae erat. Aenean faucibus nibh et justo cursus id rutrum lorem imperdiet. Nunc ut sem vitae risus tristique posuere.
In the same way this button is used to create new records, the button can be used to create new tasks, process, compare, view, etc.
In chapter 7.5.2 are listed some functions that can be used in the script.
Same actions that can happen by clicking the button in the Record Template can also be configured in process to happen on 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 chapter 5. Process Templates.
⇦ Output recapitulation:
• Repeatable Row option: determined by Record Reference
• Repeatable Row option: determined by Formula
• Repeatable Row option: determined by Filter
• Using Formulas in: Visibility Conditions, Filter Expressions and Calculation Formulas
• Buttons
In this section, you will see some functionalities that can be utilized writing a proper script.
As already described in chapter 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 realized by writing a proper script. Here’s an example.
You need to configure the Test Instruction Record Template. This template will be used for 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 the 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:
First, in the VALUES tab of the field Test, add all predefined values to the field Test (pH, Viscosity, Density, Scrub Resistance, Adhesion, Tensile Elongation, Fungal, Bacterial).
Second, write the Expression for conditional predefined values like in figure 4.63 where Values Tab of the field Test is shown with the Expression entered.
Correct Expression is the following:
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;
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., 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, in the dropdown of the field Type will appear only ‘pH’, ‘Viscosity’ and ‘Density’.
It goes the same for the second if condition if(TestType==’Application’), when variable a can have only one of these values {a=['Scrub Resistance', 'Adhesion', 'Tensile Elongation'];}. Same principle is for the third if condition. 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 specific action. The action is added on the field which will be changed.
In the Menu of the field, under tab ACTIONS, you can add a new action on button:
Upon adding new action you have to set On* to “Changed”. Under the Term you write Expression of action that has to happen when a User change the value of the field. Here’s an example.
In the chapter 4.64. Button, there is Example 1 - Button recalculates all rows in the table. In this example you learned how user can compose the formulation, and how (s)he can change the formulation and easily recalculate all amounts in the table on the press of a button “Normalize”.
Thanks to On Change action functionality, you can make this recalculation completely automatic - there is no need for user to press a button “Normalize”. Each time user changes Target Batch Size L, all rows in the table (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 Term write the same calculation that is in the action script of a button “Normalize”:
AddedMaterialg = AddedMaterialL / TotalVolume * TargetBatchSizeL * MaterialDensity
See how it’s done in the Figure 4.64.
It is important where are you setting this functionality. Try to take into account all possible scenarios that can happen from the User’s perspective regarding changing the field’s value because each time the value of the field is changed, action will happen.
As already explained, Action can be added to the field. Each time a field's value is changed, action will be executed.
This action can also be performed on a field in a specific row of the repeatable row. Specifying a row is done by using the keyword CurrentRow. Example 3 - Button with Helper Field will be upgraded 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. On a click of a button, Formulation Records are created with the names defined in the table (Figure 4.61). Formulation Record created on button will have a name defined in an alphanumeric field Experimental Formula Name (identifier ExperimentalFormulaName). Let’s say you want to configure that 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. In Example 3 - Button with Helper Field, the helper field is 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.65.
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];
}
Condition if(FormulaHelper[CurrentRow] IS SET) must be placed in order to apply On Change Action only for the already created Formulation.
This powerful feature enables you to change the property of the field using appropriate Alchemy expression. It can be used on all field types except on Label, Image and Button.
General form of Conditional Formatting Expression is:
FieldIdentifier.FieldProperty = PropertyValue;
Where FieldProperty is the keyword to access specific property of the field defined by the FieldIdentifier. Specific property is getting the value defined by PropertyValue.
Conditional Formatting Expression can be placed on 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 field property is changed. If you change the Conditional Formatting Expression in the Configuration Portal and backpropagate - field property will not be affected. It will remain as defined by previous Conditional Formatting Expression.
Field Dimensions (Width and Height, and Margins) CAN NOT be changed using Conditional Formatting.
Here is a list of Field Properties that CAN be changed using Conditional Formatting. Property is defined by its keyword which should be used in Conditional Formatting Expression. In the list of available field properties below, for each property there is an output type and possible values in parentheses:
Field property Hidden can be used only on a field that is not placed inside a repeatable row or repeatable column. Other properties can be used if the field is inside a repeatable row/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 already have 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 (i.e. range). 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 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;}
Let’s read and explain this script. In the first condition we are checking if entered number for pH value (in the field with identifier pH) is greater than defined start range limit (value defined in the field with identifier TargetpHfrom) and lower than defined end range limit (value defined in the field with identifier TargetpHto). If that condition is satisfied, 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, field property will be red ('#DF6969') and the field will get the value 'OUT OF RANGE'.
⇦ Output recapitulation:
• Repeatable Row option: determined by Record Reference
• Repeatable Row option: determined by Formula
• Repeatable Row option: determined by Filter
• Using Formulas in: Visibility Conditions, Filter Expressions and Calculation Formulas
• Buttons
BASIC
⇨Input requirements:
• Experience in Alchemy as a User
• Understanding concept of Record, Process and Stage in Alchemy
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).
Every stage in the process requires data input. Input can come from a person or third-party software. The outcomes from one stage (results of the work in most cases) serve as inputs for the next one. That mechanism is repeated until the goal is reached.
As an Admin in Alchemy, you will design various processes by creating stages and by setting actions and privileges for users on each stage.
The Lab Work 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.
In the Configuration Portal, when you click on the Process Templates icon in the left menu, Process Templates Page (Figure 5.2) will open. At the beginning this list will be empty, but later on, every Process Template that you create will be shown here.
1 - Template Name - the name of the process template.
Clicking on it will open that Process Template where you can edit it.
2 - Template Identifier - a unique identifier of the template: it is used in formulas and it is very important in the configuration process. It will be explained in 5.2.1 Creating Process Templates
3 - Last Published Version - an ordinal number of the last published version of the template
4 - Description - quick info about the process (e.g., in order to distinguish 2 similar templates at a glance)
5 - Additional options (Edit, Duplicate and Export)
6 - Sorting options available for each column on hover
7 - + NEW PROCESS TEMPLATE button - for creating new process template
8 - IMPORT PROCESS TEMPLATE button - for importing process template from .json file
Note the analogy of the Process Templates Page with the Record Templates Page.
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.
1 - Process Template Name
2 - Flow - process map
3 - Process Template Menu - additional options about your process
4 - Delete - deleting process is possible only if you did not use it in calculation formulas or if you did not create anyony process from that template in User Portal.
5 - Process Template Edit Button - brings up the Process Template Menu
6 - Verify - check if the configuration does not have any errors
In this section, we will provide step-by-step instructions on how to create your own process template using an example (Lab Work) that we will follow throughout the manual.
To start creating your processes, navigate to the Process Templates Page by selecting it from the Navigation Bar on the left side. From this page, you can create a new Process Template by clicking on the + NEW PROCESS TEMPLATE button on the top left part of the screen. You need to provide:
1 - a name
2 - an identifier
for your new process template (Figure 5.4).
Both the Name and the Identifier must be unique in the whole system (No two processes can have the same name or same identifier). Name and Identifier can have the same value.
The Name can contain any characters, numbers and alphabets (i.e. Lab Work, New Product Development, Quote $, 8D Problem Solution). This is how your process template will be represented in the User portal (i.e. for reports, search, etc.).
The Identifier is used to reference your template in calculation formulas, it must start with a letter and may contain only English alphabet letters, numbers and underscores (i.e. LabWork, New_Product_Development, Quote, ProblemSolution8D). In the modal dialog presented in Figure 5.5, 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 easily change the suggested value if you wish, but make sure that your process identifier always starts with a letter (system returns an error otherwise).
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 and you will be using them in different formulas. They are:
After you click the "Save" button, you will go to the Process Template Page as seen in Figure 5.5. 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 and identifier of your process, and write a short description of it that will be shown in the Process Templates page. You can change the name of the process, while the identifier cannot be changed. Under the privileges tab, you will set which users can create a process from that Process Template, which users can set priority, hold the process or void the process. Process privileges are written using User Tags. You can come back to this menu by clicking the edit button
next to the process template name.
On this page, you can modify your process by adding (or removing) Stages and Privileges, which are explained in the following sections.
Process title in the User Portal (Figure 5.6) is defined by the system following a pre-set naming pattern.
The process title is defined and set by the naming 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 an unique title. 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 designed. In the second case you do not need Process Record anymore. Important: Process Record Record Template should not be deleted, but only removed from the Process Template where you don’t need it.
For example, if you are configuring 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 required field. What User fills in this field will be used as a 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 calculation formula 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:
1) Text constant
2) Text formula
3) Pattern formula
You can also set whether this field (therefore the new process title) can be edited by the user, and whether it needs to be unique. If you leave unchecked "Field has unique value", that field will be automatically unique on the process level - meaning that in that 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. That will help users when trying to name the process 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.
More about the pattern formulas is explained later.
In the same way 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 to 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. 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. See the following example. 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 the 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 can not put calculation on RecordName: FirstName + LastName. Reason is that a new record created needs to have a name, but 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. More elegant and 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.
Calculation with alphanumeric fields on field 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 (Chapter 3.2.1). For each privilege you can set under which conditions it can be applied (When).
In the Lab Work process, 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 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. Creation privilege defines which users are able to create the process in the User Portal. Further process privileges define who can:
2) Stage Privileges are defined for each stage separately and define which users can:
And on which conditions they have those privileges.
3) Record Privileges are set for Record Templates that are not placed in any Process Template (record outside of the process). Based on them, users can create records without starting the process.
In the Record Template, under the Privileges Tab you can set the User Tag Expressions under each of these fields. Under the icon
a field will pop-up in a small window where you have 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 (solo), changes will be effective on all records created with that record template, no matter if used in or outside of process.
Process privileges are added by the following steps:
1 - Clicking on the
icon next to the name on the process page
2 - Navigate to the privileges tab on the right-hand side process template menu
All privileges, except Can Set Priority, are defined using the User Tags (explained in Chapter 3. Tags), in the "To:" field.
3 - Once you have written the expression, you can check which users will get this privilege by clicking on the eye icon (Number 3 in Figure 5.7).
As already mentioned, set priority privileges can only be given to one user tag.
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 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 Lab Manager can prioritize work for the Lab Work Startup processes. You can achieve that by adjusting Set Priority Privilege on the level of process. In the process template menu, under tab privileges, 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 privilege tab. In the pop-up window, you can:
1 - Define the condition when the users will receive the privilege. If you leave it empty, privilege will be assigned in each case
2- What the privilege allows them to do (process: set priority, void, put on hold)
3 - User Tag expression defines the users who will be able to Void and/or Put On Hold processes
Can Void and Can Put On Hold privileges can be set together, if the same Tag(s) will have both, by checking the corresponding checkboxes.
In Figure 5.8 adding “void privilege” is shown.
Stage privileges are added in the same manner as the process privileges. Select the stage where you want to add a privilege. Choose Privileges from the right-side menu. Click on the + NEW PRIVILEGE button from the privilege tab. In the pop-up window, you can (Figure 5.9):
1 - Define the condition when the users will receive the privilege, if you leave it empty privilege will be assigned in each case
2 - User Tag expression defines the users who will be able to View and/or Edit
3 - What the privilege allows them to do (can view, can view and edit)
All privileges can be added to users under a certain condition, using the same principle as for actions. This will be explained in the ADVANCED section of this chapter.
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. Same as for 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 next to the side bar
Verify is used for 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 in the same way as explained for Record Templates in chapter 4.2.3 Verify, Publish and Back Propagate 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 button
you will publish all templates from the list. Once published, Process Templates will appear in the Back Propagate section and PUBLISH button will be grayed. Publishing the process template will create a new version. In the Process Templates Overview 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
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 and 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:
1 - Create New Process Template with valid name and identifier
2 - In the first Record Template of the first Stage there needs to be an alphanumeric field unique in the system with identifier Name (used to give a name to the process created in the User portal)
3 - Process Creation privilege needs to be set using a proper User Tag Expression
4 - Priority Set privilege needs to be given to at least one user using special User Tag Expression (Tag[PriorityTagName])
5 - Other Privileges should be set on Process level and on each Stage separately
6 - All Stages should be connected by Transition Actions - for each possible “direction” in a flow there must be a valid action; on the last stage there should be an “Complete Process” Action. More about the Actions is explained in detail in chapter 5.8 Actions.
When creating and testing a new process, set all privileges to yourself as an Administrator using for example Tag[Admin]. Once you are sure your process is valid, you can add users and tags in the system and then set the Privileges for them.
If you want to delete a process template, you can do so by going to the process template page of the process you wish to delete, then (Figure 5.10):
1 - Click on the edit button next to the process name
2 - Click on the three dots on the right-hand side process menu
3 - Click "Delete" button
You may only delete Process Templates if no process was created from it in the User Portal or if not referenced in any other processes.
You can also Edit, Duplicate process templates, and Export it to the .json type of file. In Figure 5.11 you can see three dots, that represent additional options, on the right-hand side of the Processes Template page in line with every process template. By clicking on them you will be able to choose what you want to do next with the template.
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 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, all in a particular order. Tasks in 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, process transitions to another Stage. Stage is completed when all the tasks of that stage are done, meaning all required work is done, 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 the Request. The Request 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 goes to the second stage.
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 stage) or rejected (process goes back to the first stage Request where more info 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 page. Same as when creating a process, you will need to provide a name and identifier for the stage, following the same logic and restrictions.
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. They are:
Once you create a Stage, you will be able to see it on the Process Template Page as a box with the stage name (Figure 5.10). Note that Stages on Figure 5.13 do not have any connections (arrows) between them. Stages are connected when you add Actions on each stage which is explained in chapter 5.8 Actions.
On the right-hand side stage menu, there are four tabs: Properties, Records, Actions and Privileges. As mentioned above, under Actions Tab you can define the flow of the process through the stages. Under Privileges Tab you can define which users can view or view and edit the stage and under which conditions (more about this in the 5.3 Privileges). Under Records Tab you are defining which Record Templates are used to create records on particular Stage (will be explained below). Under the Properties Tab, you can see the name and identifier of your stage. On this tab , you can set the Stage Order, Expected Duration of that stage and if entering Effort Spent is required for that stage.
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 the notification (in app or email, depending on how User has managed his/her notifications in Alchemy).
The Planned Completion date of the stage is calculated based on the Expected Stage Duration and the date when the process is created. All tasks created on this stage will have this Planned Completion by default.
Stage Formulation has the Expected Duration of 48h and is created on Apr-01-2021 at 13:00h. Planned Completion date for this Stage is Apr-03-2021 at 13:00h.
Note that Alchemy will not recognize weekends. Hours of Saturday and Sunday will be calculated in the same way as for any other day of the week.
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" 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 structured flow of information.
Most of the work in Alchemy User Portal will consist of writing your information in these records. They are explained in detail in Chapter 4. Record Templates. In this chapter, we will assume you have already created them and will focus on adding them to the stages of your process.
Adding record templates to a stage defines which set of information is needed in order to complete said stage.
In the Lab Work Startup process, there is a Stage with the name Lab Work. When on this stage, the Chemist can plan the experimental work, create formulations or perform characterization tests. The Chemist will be able to capture all these data in Alchemy if you add Record Templates: Work Plan, Formulation Design, Characterization Testing to the Lab Work Stage.
To add a record template, follow the steps shown in Figure 5.14:
1 - Select the stage you want to add it in
2 - Click on the Records tab on the right-side stage menu (here will be listed all Record Templates already added to the Stage)
3 - Click on the + ADD RECORD
This will open a popup menu (Figure 5.15) where you need to define:
1 - The record template you want to add to the stage. You can select them from a list of templates (Chapter 4. Record Templates).
2 - The Record Naming Pattern, written as string, field identifier (i.e. when you want a value from that field to be a part of the name), naming pattern formula, or any combination of the three. The name of the record has to be unique in the process.
3 - The minimum number of records that will be created when the stage activates. If greater than 0, that many records will be automatically created in the User Portal when the stage is activated. This number of records needs to be created (automatically or manually) in order to complete the stage.
4 - The maximum number of records that can be created on the stage. If not defined, the user will be able to create an unlimited number of records on this stage.
5 - A checkbox if you want to allow users to edit the record after the stage is completed. This field is checked by default. The record will be automatically editable if that stage is reactivated. This checkbox allows the record to be editable even if the stage is not active.
6 - A checkbox if you want to allow users to share the record with a third party. Anyone who has edit privilege on that stage (more about privileges will be in chapter 5.3 Privileges) will be able to share the record from Alchemy User Portal with recipients outside of Alchemy. If you decide to allow the record to be shared, in the User Portal there will be a “share” icon visible in the upper right corner of the record. For the records that can be created outside of the process you can set in Record Privileges which users can share that record using user tag expressions. Upon setting a share privilege, records out of the process will have a “share” icon in the upper right corner and can be shared. When sharing a record, it is sent in an email and the user can also define whether the third party can edit or only view the shared record. The third party User will receive a link in the email and after setting a password, (s)he will have access to Alchemy, but only to the shared record(s).
7 - A checkbox if you want to allow the records created from this record template to be available for COMPARE functionality.
When allowing more than one record to be created from the same template, you need to define the Record Naming Pattern (number 2 in figure 5.15). You can use the PATTERN function which is explained in detail in Chapter 7.5 Functions. Here it is important to note that it returns a 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 the Lab Work. If not approved, the flow goes back to the first Stage: Lab Work Request where additional info is needed to be filled or 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:
'LWR Approval ' + PATTERN('NN')
in the Record Naming Pattern when adding that Record Template to the Stage. Created records will have names: LWR Approval 1, LWR Approval 2, ...When number 99 is reached, it will start again with 1. If you need 100, 101, you will use PATTERN (‘NNN’). The same logic is for one digit numbers - PATTERN(‘N’)
When adding a record template to a stage (+ ADD RECORD) you can specify the minimum (Figure 5.15. number 3) and maximum (Figure 5.15. Number 4) number of records that a user can create. Both can be defined with a number constant (i.e. 1,3,5…) or with a formula. Some examples of “min” and “max” number of records with a number constant are:
You are able to use any number for defining “min” and “max” in any combination. Options are endless. 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. Person who starts the process needs only one form and that form needs to be opened when the Lab Work Request stage is started. You will achieve that by writing number one, both in the Minimum Records field and Maximum Records field. That is how one record will be automatically created and the user will not be able to add one more since the maximum number is one.
Any of these numbers can be a mathematical formula result. Types of formulas that could be used are explained in Chapter 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 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 process loops between stages, 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 to the Maximum Records as well, no records besides that one created are allowed.
It's 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 by 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 (Figure 5.16).
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 (Figure 5.15).
Once you add a stage, you are also able to delete it. It can be deleted in each moment, including after everything is already done - all stages connected, added records and actions, etc.
You can delete the stage by following the next steps (Figure 5.17):
1 - Choose the stage you want to delete
2 - On the right-side menu you will see information about that stage. Click on the three dots in the upper right corner
3 - Choose Delete
After choosing Delete, Alchemy will ask you where you want to transfer records that were on this stage. Deleting the stage will also delete all actions in that stage.
Alchemy will delete everything that is on the stage that you want to remove. However, you need to delete everything that is related to the deleted stage (i.e. if deleted stage is used in some conditions on other existing stages, you need to reset those conditions).
Every stage has its own life cycle, or series of events that the stage goes through.
In Alchemy, those events are:
Actions define the outcomes of each event. When an event takes place, the system evaluates if all the conditions are met for an outcome to happen.
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 either on 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).
You've noticed that after you add multiple stages, they are not automatically connected. To connect them, "transitions" need to be added between them (Figure 5.18). The transitions are added in the following way:
1 - Choose the stage from which a transition will start
2 - Go to the Actions tab
3 - Click on the + NEW ACTION.
This will open a pop-up window where you will define your action in the following steps (Figure 5.19):
1 - Select the event that triggers the action, which for transitions must be On Completed
2 - Define a condition under which the action will happen. Leaving it empty means the transition will always happen if the stage is completed. More about this will be explained in the ADVANCED part of the chapter.
3 - Tell the system what to do (which action to execute). For transition, select "Transition to"
4 - Select the stage that will be activated after current one is completed (e.g., Request Approval)
After saving the transition, the two stages are now connected (Figure 5.20). This means that after the user completes the request, they will transition to the Request 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.21 there is example of more complex Lab Work process flow where you can see three types of sequences: (Numbers 1 and 2 will be explained in the next pages and number 3 will be explained in the ADVANCED part)
1 - Sequential
2 - Looping back
3 - Parallel stages
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 not possibilities are not covered, you will get stuck in a process where all stages are complete, and none is 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 Action, in the field WHEN.
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 that should happen. This is done in the field When. Leaving this field empty means that transition will always happen, without any restrictions. Here is an example of sequential progress through the flow.
After the Lab Manager reviews the request, (s)he receives a Task to fill out the LWR Approval record, on the Stage Request Approval. In this form, (s)he needs 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 that work is not needed and the initiated process should be completed (terminated). To achieve this, in the Request Approval Stage set the ActionOn Completed, Do:Complete Process. For condition (When) write Record[LWApproval].LWApproval==false
Lab Manager did not approve the request because (s)he needs more information. This should loopback from the Request Approval stage back to the Lab Work Request stage (not complete 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 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 info.
More examples of different conditions in the “When” field will be given in the next pages and in the ADVANCED part of this chapter.
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, square number 2 in Figure 5.21). 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, and that is the second run for the Lab Work Request Stage. It will create record LW Requirements 2, and when completed, goes again to the Request Approval Stage, which is the second run for it. If still some info needed and 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), e.i. 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). Here is the previous example expanded:
When the Lab Manager is approving the request, besides yes or no, there can be a third possibility: more info 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 info. 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 info needed’.
In the Request Approval Stage set the Action On Completed, Do: Transition To, and choose Lab Work Request Stage. For condition (When) write
Record[LWApproval].LWApproval == ’more info needed’
For each stage, you can define what task(s) are automatically created in the User Portal when the stage is activated. Go to the Actions tab and click on the + NEW ACTION on the stage you need to add the actions. Adding Create Task Action is done in the following steps (Figure 5.22):
1 - Select the event that triggers the action. For tasks, it must be on Activated.
2 - Define a condition under which the action will happen. Leaving it empty means that the action is always executed when triggered.
3 - Tell the system what to do (which action to execute). Select "Create Task"
4 - Specify which users will get the Task. User tags and expressions are defined in Chapter 3. Tags.
5 - Write the Task Subject
6 - Write the Task Description
Subject and Description must be text constants (written under single quotes, i.e., 'text constant') or formulas that output a text value. More details about formulas is explained in chapter 7. Formulas. Subject is limited to 80 characters, including spaces and quotes, while the Description 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 on through the process (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 Paste As Plain Text option for pasting. If you do not, the system might not recognise your text as a string value, and an issue may occur.
You should assign a task to only one person whenever possible.
Lab Manager needs to review and approve a request for lab work. The Lab Manager needs to get a task to review Lab Work Requirements record filled out at the initial (Lab Work Request) stage. You will configure that by adding Create Task action. In the Task Subject you can write 'Review ' + Process.Name + ' Request'. Our Lab Manager will receive a task. In its subject (s)he will see which Lab Work needs to be reviewed. If there is nothing to be added in the Task Description you can enter ' ' (empty string), since this field is mandatory and you cannot leave it empty.
Task subject should be as unique as possible. This is how 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 (can be any Chemist or Lab Technician) 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 is continuing to the Lab Work stage and further. The Lab Manager wants to delegate the LW Report stage to the person who has 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 has created the Lab Work.
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 on the + NEW ACTION on the stage you need to add the actions. Adding Notify Action is done in the following steps (Figure 5.23):
1 - Select the event that triggers the action. It can be on Activated or on Completed.
2 - Define a condition under which the action will happen. Leaving it empty means that the action is always executed when triggered.
3 - Tell the system what to do (which action to execute). Select "Notify"
4 - Specify which users will get the Notification. User tags and expressions are defined in Chapter 3. Tags.
5 - Write the Subject
6 - Write the Description
Subject and Description can be text constants (written under single quotes, i.e., 'text constant') or formulas that output a text value. More on Formulas in Chapter 7. Formulas.
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 (5.7.3 Adding Record Templates to a Stage).
Go to the Actions tab and click on the + NEW ACTION on the stage you need to create the record and follow the steps (Figure 5.24):
1 - The event that triggers the action, which for Create Records is on Activated.
2 - Define a condition under which the action (creating a record) will happen.
3 - Tell the system what to do (which action to execute). Select "Create Record".
4 - Select the Record Template from which the Record will be created in the User Portal.
5 - Select how many records of the template you selected will be created. This can be a number but also defined by setting a formula field Number of Records..
Make sure that the Record Template is added (in the Records Tab of that Stage) to the Stage before adding an action that will Create Record. 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 of this Manual you can find schemes where all Record Templates are added to adequate stages.
Record in the User Portal can be added automatically or by User. Use Create Record action when you want records to be created automatically when the condition is met.
In the Alchemy Lab, after the Lab Work Request stage has been completed, 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 on the stage you want to send an email. Adding Send Email Action is done in the following steps (Figure 5.25):
1 - Select the event that triggers the action. It can be on Activated or on Completed.
2 - Define a condition under which the action will happen. Leaving it empty means that the action is always executed when triggered.
3 - Tell the system what to do (which action to execute). Select "Send Email"
4 - Specify which recipients will get the Email. You can define the recipients:
5 - Write the Subject
6 - Write the Description
⇦ Output recapitulation:
• Process Templates: create, edit, publish, delete
• Concept of Stage
• Actions
• Privileges
ADVANCED
⇨Input requirements:
• Concept of process template
• Concept of stage, task, action, privilege
• User Tag Expressions
As said in the BASIC part of this chapter, transitions between stages in the process can be sequential, looping and parallel. Under number 3 in figure 5.21 is shown a flow of more complex process for Lab Work that contains two parallel stages: Characterization and Application Testing. 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). Check Figure 2. in Appendix - flow of this process is shown. Only when both are completed, stage Lab Work Review will be activated and 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 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 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. More about System data is given in chapter 7.1.2. System Data Variables.
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.
BASIC
⇨Input requirements:
• Experience in Alchemy as a User
• Understanding concept of Record, Task, Stage and Process in Alchemy
• Knowledge about Tags and user tag expressions
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.
⇦ Output recapitulation:
• View Templates: create, edit, publish, delete
• Concept of Nodes
• Advanced Search
•Data Visualisation methods
ADVANCED
⇨Input requirements:
• Concept of View Template
• Nodes
• Advanced Search
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)
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 Theme (Chapter 4.4.15) according to these rules. When adding new fields to the grid you will have fields already adjusted to the desired setting.
Font size:
Font weight:
Alignment: left align
Width:
Height: minimum 3 boxes
Margin Bottom:
Margin Top:
Label Styles: The third grey going from the right
Label Border: no borders on labels, except if labels are used as headers of columns in a table
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.
Width:
Height: 6
Margin Bottom: 2
Margin Right: 4
Cloneable: checked by default
Reportable: Yes
Editable: checked by default
Max number of characters: 500
Show Field Name as Label: checked by default
Name Orientation: Top
Name Horizontal Alignment: Left
Name Vertical Alignment: Central
Name Style Color: The third grey going from the right
Input Horizontal Alignment: Left
Input Vertical Alignment: Central
Input Border: Bottom
Width: 26
Height: 6
Margin Bottom: 2
Margin Right: 4
Cloneable: checked by default
Reportable: Yes
Decimal Places Format: 2
Editable: checked by default
Show Field Name as Label: checked by default
Name Orientation: Top
Name Horizontal Alignment: Left
Name Vertical Alignment: Central
Name Style Color: The third grey going from the right
Input Horizontal Alignment: Left
Input Vertical Alignment: Central
Input Border: Bottom
Width: 26
Height: 6
Margin Bottom: 2
Margin Right: 4
Cloneable: checked by default
Reportable: Yes
Date & Time Format: MMM dd yyyy
Editable: checked by default
Show Field Name as Label: checked by default
Name Orientation: Top
Name Horizontal Alignment: Left
Name Vertical Alignment: Central
Name Style Color: The third grey going from the right
Input Horizontal Alignment: Left
Input Vertical Alignment: Central
Input Border: Bottom
Width: 26
Height: 6
Margin Bottom: 2
Margin Right: 4
Cloneable: checked by default
Reportable: Yes
Editable: checked by default
Show Field Name as Label: checked by default
Name Orientation: Top
Name Horizontal Alignment: Left
Name Vertical Alignment: Central
Name Style Color: The third grey going from the right
Input Horizontal Alignment: Left
Input Vertical Alignment: Central
Input Border: Bottom
Width: 4
Height: 3
Margin Bottom: 2
Cloneable: checked by default
Reportable: Yes
Editable: checked by default
Show Field Name as Label: not checked by default
Input Horizontal Alignment: Left
Input Vertical Alignment: Central
Input Border: None
Best Practice: use a combination of Checkbox type field for user’s input with “Show Field name as Label” unchecked and additional Label field type to name the checkbox field
Width: 86
Height: 10
Margin Bottom: 2
Margin Top: 2
Cloneable: checked by default
Reportable: Yes
Editable: checked by default
Show Field Name as Label: checked by default
Name Orientation: Top
Name Horizontal Alignment: Left
Name Vertical Alignment: Central
Name Style Color: The third grey going from the right
Input Border: All
Width: 35
Height: 35
Margin Bottom: 2
Allow Multiple Values: checked by default
Cloneable: checked by default
Reportable: Yes
Editable: checked by default
Show Field Name as Label: checked by default
Name Orientation: Top
Name Horizontal Alignment: Left
Name Vertical Alignment: Central
Name Style Color: The third grey going from the right
Input Horizontal Alignment: Left
Input Vertical Alignment: Central
Input Border: All
Width: 41
Height: 6
Margin Bottom: 2
Margin Right: 4
Cloneable: checked by default
Reportable: Yes
Editable: checked by default
Show Field Name as Label: checked by default
Name Orientation: Top
Name Horizontal Alignment: Left
Name Vertical Alignment: Central
Name Style Color: The third grey going from the right
Input Horizontal Alignment: Left
Input Vertical Alignment: Central
Input Border: Bottom
Width: 41
Height: 6
Margin Bottom: 2
Margin Right: 4
Cloneable: checked by default
Reportable: Yes
Editable: checked by default
Show Field Name as Label: checked by default
Name Orientation: Top
Name Horizontal Alignment: Left
Name Vertical Alignment: Central
Name Style Color: The third grey going from the right
Input Horizontal Alignment: Left
Input Vertical Alignment: Central
Input Border: Bottom
Width: 41
Height: 6
Margin Bottom: 2
Margin Right: 4
Cloneable: checked by default
Reportable: Yes
Editable: checked by default
Show Field Name as Label: checked by default
Name Orientation: Top
Name Horizontal Alignment: Left
Name Vertical Alignment: Central
Name Style Color: The third grey going from the right
Input Horizontal Alignment: Left
Input Vertical Alignment: Central
Input Border: Bottom
Width: 26
Height: 6
Margin Bottom: 2
Margin Right: 4
Cloneable: checked by default
Reportable: Yes
Editable: checked by default
Show Field Name as Label: checked by default
Name Orientation: Top
Name Horizontal Alignment: Left
Name Vertical Alignment: Central
Name Style Color: The third grey going from the right
Input Horizontal Alignment: Left
Input Vertical Alignment: Central
Input Border: Bottom
Image field can be used for displaying a Logo of the company. Size of the field should be adjusted to the size of the logo image.
Another use case is to upload a PDF file to the Image field. In the User Portal There will be a link on the place of the Image field. When the User clicks on it, a PDF file opens on another tab.
Width: 26
Height: 6
Margin Bottom: 2
Margin Right: 4
Button Color: Blue, third going from the right
Width: optional
Height: optional
Margin Bottom: optional
Margin Left: optional
Best practice:
Width: optional, depending on how many columns you have in the table
Height: 3
Margin Bottom: 2
Margin Left: 13
Best practice and general rules for the Tables:
Width: 16
Height: 24
Margin Bottom: 2
Margin Top: 4
Best practice:
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:
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.