Configuration Portal Administrator Manual

Before You Start 

In this manual you will find all explanations for using the Configuration Portal of the Alchemy app. The document has structured subchapters with important parts of text highlighted in differently colored bubbles. There are two additional spreadsheets that are templates that you should use as preparation for configuring. At the end, there is an Appendix with schemes of process templates mentioned throughout the Manual. 


Red bubbles are the use cases that should always be implemented.

Always have a unique Name and Identifier

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 bubbles represent the best practices that we recommend. 

Advice for different borders

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 bubbles represent examples. 

Fields with and without margins

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.


Comparison screenshots show how the configured templates and fields look in the User Portal.


1. Introduction

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 portal, configured templates will allow members of your organization to record their work in a structured and predetermined way. 

The User Manual will help you navigate around the Configuration portal, set up your workspace and learn all the best practices. Here you will also find our templates for designing process and record templates that are proved to be a great practice in the configuration process.  

Sign In 

After receiving an email from Alchemy, you need to set your password. By opening the link from the email, you will see our Sign In page, where you will insert your credentials. In case you forgot your password, you will be able to request a Reset 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 start with the Process Templates page, On the left-hand side menu (accessed by menu icon), the Alchemy Configuration Portal is divided into four sections:

  1. Process Templates
  2. Record Templates
  3. Tags
  4. Users

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

"Tags" and "Users" sections are tools for managing the users, how they interact with each other and with the portal across different organization groups. You will use configuration portal sections to define custom content, and manage general settings, users and user group identifiers (tags).

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 and System Data

Configuration data contains:

  • Process Templates - a process template is a digital representation of work patterns (processes) your company follows (e.g.,  Lab Work, New Product Development, Alternative Raw Materials). A user can later initiate multiple Lab Works using the template created in the Configuration Portal. Each Lab Work will follow the rules and conditions defined by this template.  The complete process template consists of stages with record templates inside them that have to be filled out, as well as the set of privileges, which define the user's role in this process. In Privileges, User Tags are used and can be assigned to multiple Users.
  • Record Templates - a record template is any data entry template that is used throughout the process (e.g.,  Approval Form, Formulation Form, Quote, Characterization). For example, you can configure a record template for all the Formulations, which can save every Formulation consistently. 

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. 

Figure 1.1 Configuration Data Scheme

Predefined templates and inputs from all users in the User Portal together make the System Data. The system stores:

  1. Configuration Data - The complete set of rules and patterns your company follows (see above), see in Figure 1.1 and Figure 1.2.
  2. User Data - The data collected by users who fill out the templates in the User Portal. This is not the same as the user’s personal data.
  3. System and User activity data - Data collected by the system while in use (e.g., activity logs - when some work is started, when it is done, etc.)
Figure 1.2 What system stores

2. Process Templates

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 2.1). 

Figure 2.1 Flow for Lab Work Process Template

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 describe the actions and set the order and responsibilities for each stage of the process.

Lab Work Process

The Lab Work process is used by Alchemy Laboratory Inc. when a customer asks for an analysis of a sample. It starts by recording the customer's request (Stage: Request). Then the Lab Manager reviews the request (Stage: Request Review).
If (s)he needs more information, (s)he'll ask for a technical call with the customer (Stage: Technical Call). If (s)he has all the info, (s)he defines what tests need to be done in the Lab and approves the request (Stage: Request Review). The Technicians then make the sample based on customer specification (Stage: Formulation), analyze it in the lab using their standard procedures and write the result of the tests in Alchemy (Stages: Characterization and Application Testing). The Lab Manager then reviews the work (Stage: Lab Work Review). If successful, (s)he compiles a report to be sent to the customer (Stage: Report), or send back to the lab if not successful (Stage: Formulation) (Figure 2.1)

2.1 Process Templates Page Overview

Upon signing in, you you will land on the Process Templates Page (Figure 2.2):

Figure 2.2 Process Templates page overview

1 - Template Name - the name of the process template.
Clicking on it will open a Process Template Page where you can edit it.

2 - Template Identifier  - a unique identifier of the template, used in formulas  

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

2.2 Configuring a Process Template 

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.

Figure 2.4 Process Template page overview

1 - Process Template Name 

2 - Flow - digital representation of your process flow

3 - Verify - check if the configuration is in order

4 - Process Template Edit Button - brings up the Process Template Menu

5 - Process Template Menu - additional options about your process

6 - Delete - deleting  process is possible only if you did not use it in formulas or if you did not create any process from that template  in User Portal.


2.2.1 Creating Process Templates

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 through with in the manual. Once you are ready, our template from Chapter 7. Design Templates will help. 

To start creating your processes, navigate to the Process Templates Page by selecting it from the Navigation Bar. 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 2.5).

Figure 2.5 Creating a process template

 

Always - Uniqueness in Process Template Naming

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 within one process.

The Name can contain any characters 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 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 2.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.

Words and phrases that can't be used as Identifiers

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:

Name, Status, Template, CurrentStage, Priority, Duration, FinalDuration, TotalEffortSpent, CreatedOn, CompletedOn, CreatedBy, CompletedBy.

After you click the "Save" button, you will go to the Single Process Template Page as seen in Figure 2.6. On the right-hand side a process template menu is displayed.It is divided into two tabs, PROPERTIES and PRIVILEGES. Under properties, 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 privileges tab, you will set the process privileges for different User Tags. You can come back to this menu by clicking the edit button next to the process template name.

Figure 2.6 Created process opening page

On this page, you can modify your process by adding (or removing) Stages and Privileges, which are explained in the following sections. 

2.2.2 Process Title in the User Portal

Process title in the User Portal (Figure 2.7) is defined by the system following a pre-set naming pattern and can be edited by the user.
 

Figure 2.7 Process Title in the User Portal

Always - Process Title

The process title is defined and set by the naming field (Identifier: Name). There must be an alphanumeric field with that identifier 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 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 (created automatically when new process is started).

As Admin, you can define a pattern by which the processes title will be created for each new process in the User Portal. Setting the pattern has to be done in the name field (Identifier: Name). 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 "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. 

More about how to customize this record is explained in the Record Templates Chapter

Lab Work Title in the User Portal

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-2020-09-001 (for the first process in september). The following one will be named LW-2020-09-002, etc.
More about the pattern formulas is explained later.

2.3 Stages

A process in Alchemy is constructed from stages that also 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 the stages for each group of users to perform a set of tasks, 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, 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.

Stage: Request

The lab work process in Alchemy Coatings Inc. starts when a customer submits a request. Thus the recording of this request is the first stage of the Lab Work process. This stage is usually done by a sales representative or the lab manager.

The second stage in the process is when the lab manager reviews the request and either approves (sends it to the Lab Work stage) or rejects and asks for more information (the Technical Call stage)


Words and phrases that can't be used as Identifiers

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:

Name, Completed, Run, TotalEffortSpent, FinalDuration, CreatedOn, CompletedOn, CompletedBy.

When a new process template is created, it is not initially empty. Inside the process template you will have one stage, named Stage 1 (as presented in Figure 2.6) and one record inside that stage, named Process Template. Inside that Process Record template there is only one field with the identifier Name. It is important to always have one field with that identifier in the first record, placed in the first stage of your process. As it is already mentioned, a new process created in the User Portal will be named from the value entered in the field with that identifier.

You can choose to replace the automatically created Stage 1 with a custom made stage, or to replace the Process Record with another Record template. If you decide to do so, make sure to place one field with the identifier: Name in the first record of your first stage, and to delete Process Record and/or Stage 1 from your process.

2.3.1 Adding Stages to a Process

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.

2.3.2 Editing Stage Properties

Once you create a Stage, you will be able to see it on the Single Process Template Page as a box with the stage name (Figure 2.8). 

Figure 2.8 Stages on a Process Page

On the right-hand side stage menu, under properties, you can see the name and identifier of your stage. 

On this page, you can set the Stage Order and expected duration of that stage.

Set the Stage Order

Stage Order will be set with the next chronological number when you create a new stage in the process template. If you reorder your stages in the process afterward, the Stage Order number will stay the same 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.

The completion target date of the stage is calculated based on the duration and the date when the process is created. All tasks created on this stage will have this completion target by default. 

Lab Work Duration

A Lab Work has the expected duration of 48 hours and is created on Jan-01-2019 at 13:00h, the completion target date for this process will be Jan-03-2019 at 13:00h.


For each stage, users in the Alchemy User Portal can keep track of the effort involved to complete it. 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.

2.3.3 Adding Record Templates to a Stage

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 3, 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..

Record Templates in Formulation Stage

In the Formulation Stage for Alchemy Laboratory, you want to know the batch information (size, units, etc), the formulation table and processing details. These are all record templates in Alchemy that you will add to the formulation stage.

To add a record template shown in Figure 2.9:

1 - Select the stage you want to add it in

2 - Click on the Records tab on the right-side stage menu

3 - Click on the + ADD RECORD 

Figure 2.9 Adding record template 

This will open a popup menu (Figure 2.10) where you need to define:

1 - The record template you want to add to the stage. You can select them from a list of published templates (Chapter 3. 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 also 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 the third party.  Anyone who has edit privilege on that stage will be able to share the record from Alchemy User portal with  recipients outside of Alchemy. The user can also define whether the third party can edit or only view the shared record.

Figure 2.10 Popup menu for adding record templates


Publish your records

Make sure that the record you wish to add to a stage is published. Don't forget to publish the record again if any changes are made.

2.3.4 Using Patterns for Record Names

The record name has to be unique in the process, so when allowing more than one record to be created from the same template, you need to define the record naming pattern using the PATTERN expression. This is explained more in Chapter 6.5 Functions. Here it is important to note that it returns a text, auto-incremented by each new iteration. 

Request Approval 1 - making a pattern for the Approval Record template

A formula PATTERN('N') returns '1' first time invoked, '2' the second time and it goes up until 9; the 10th one will be again '1' and so on. If you need '10', '11', you will use 'NN' (the same logic is used for three digits numbers - 'NNN'). You can combine this with any other text or text constants (i.e. 'Request Approval ' + PATTERN('N') = Request Approval 1, Request Approval 2...)

2.3.5 Number of Records

When adding a record template to a stage (+ ADD RECORD) you can specify the minimum (Figure 2.8. number 3) and maximum (Figure 2.8. 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:

  1. Min (1) and max (1) - This will create one and only one record of that template on process creation. The user will not be able to add more of the records, nor to delete the one that is created on activation.
  2. Min (0) and max (5) - No records will be created on stage activation, but the user may add up to 5 records if necessary, using the + New Record on the left-side navigation.
  3. Min (1) and max (5) - One record will be created on stage activation, and the user may add up to 5 records of this template in the User Portal if necessary. The user can delete all but one record, since the defined minimum is one.
  4. Min (5) and max (5) - Five records will be created on stage activation, and the user may not add or delete any of them. 

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.

Setting up a minimum and maximum number of records in the Request stage

In the Request stage Sales need a Request Form record in order to fill in all the necessary data for Lab Manager. Sales person needs only one form and that form needs to be opened when the Request is started. You will achieve that by writing number one, both in the Minimum Records field and Maximum Records field. That is how one form will be automatically created and Sales person will not be able to add one more since 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 6. Formulas.


Using Formulas to define the number of records

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.

Setting up a minimum and maximum number of records in the Request Review stage

In the Request Review stage Lab Manager needs an Approval Record and a Test Selection Record. The Lab Manager chooses tests only when (s)he approves the request. Each time the Lab Work loops back to the Request Review stage Lab Manager needs a new Approval Record to fill in. That is how Alchemy Laboratory Inc. will be able to trace parts of the Lab Work process about approving part of the Lab Work process. You will achieve that by setting up this formula for Minimum Records and Maximum Records on the Request Review Stage: Stage[RequestReview].Run

Test Selection Record will be opened only when Lab Manager approves the request. Again, you will use a formula in order to get that record only after approval. Both, for the Minimum and Maximum Records you will write: IFS(Approved=true,1,Approved=false,0). That is how you will ensure that the minimum and maximum of the records is one when request is approved, but zero when request is rejected. By doing so you will enable User to add Test Selection record template on the User Portal only when Request is approved. More about how to write formulas can be found in the Chapter Formula.

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

Reordering Record Templates

After you have added multiple templates, 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 2.11).

Figure 2.11 Reordering Record Templates

Record Template Properties

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 input fields you entered when adding it.

2.3.6 Deleting Stage

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 2.12):

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

Figure 2.12 Deleting the stage

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.

Always - make sure that other dependencies are manually deleted

Alchemy will delete everything that is on the stage that you want to remove. However, you need to delete everything that depends on the deleted stage (i.e. conditions that are relying on that stage) and it is on the other existing stages.



2.4 Actions

2.4.1 Stage Life Cycle

Every stage has its own life cycle, or series of events that the stage goes through. 

In Alchemy, those events are:

  1. Activation attempt - the first event in the stage's life cycle. When a previous stage is completed, the system evaluates conditions for the next stage activation.
  2. Activated - If all the conditions are met, stage activation happens. That means that the stage is now active and accessible by users.
  3. Completed - the last event in one stage's life cycle. After all the required work is done and all essential information is captured, the stage can be completed. Completion triggers the activation attempt for the next available stage, and the cycle repeats or it completes the process. 

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. 

2.4.2 Types of Actions

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:

  • Activate Stage - This action sets specific criteria for step activation. This means that the stage will only be activated when the criteria are met. 

Advice - Usage in parallel stages

This is mostly used when there are parallel stages transitioning to one stage and we want to make sure all of the previous stages are complete.

Activating Lab Work Review Stage

In the Lab Work flow there are two parallel stages - Characterization and Application Testing. Only when both are completed, stage Lab Work Review will be activated and Lab Manager will receive the task.

You can make this possible adding action "On" Activation Attempt on the Lab Work Review stage. In the "When" field you will write Stage[Characterization].Status='Completed' AND Stage[ApplicationTesting].Status='Completed' and in "Do" field you will choose Activate Stage.

On Activated actions:

  • Create a Task - This action will create a defined task in the User Portal. The task is assigned to the users defined by the action. In the action, assigning tasks will be defined by using Tags. More information about that will be in Chapter 5. Tags.
  • Create Record - This action will create the specified record in the User Portal. Records will be explained in Chapter 3. Record Templates, and adding records to stages is explained in subchapter 2.3.3 Adding Record Templates to a Stage.
  • Notify - This action will send a notification to the users you define by using an appropriate tag in the "Notification Recipients" field. User tags and expressions are defined in more detail in Chapter 5. Tags.

Send Email - This action will send an email to the recipients defined in the Recipients field. Set - up for this action is explained in details in 2.4.8 Adding Send Email Action.

On Completed actions:

  • Transition to - This is an action that tells the system where to go after the stage is completed. When this action is executed, it will create an Activation Attempt event on the stage you specify in the transition.
  • Notify - This action will send a notification to the users, same as the On Activation notification
  • Send Email - This action will send an email to the recipients defined in the Recipients field,, same as the On Activation action
  • Complete Process - Executing this action will complete the process.

Advice - Usage of the Complete the Process

Use this action either on completing the last stage of the process (i.e. Report) or at certain gates in the process (i.e. after the Request Review was rejected and the process should be finished).

2.4.3 Action Conditions

When defining actions, you are able to define a condition under which the action is executed. 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 - transition from Request Review to Formulation

At Alchemy Coatings Inc, after the request is reviewed by the Lab Manager, the Formulation Stage only starts if the request is approved. You will do this by adding a condition ApprovalRecord.RequestApproved = true in the When to your transition action between the Review and Formulation stage. ApprovalRecord is an identifier of a Record Type field in the Formulation Stage and RequestApproved is an identifier of a Yes/No Type field in the Request Review stage. This means that if the Lab Manager selected "Yes" in the Approval Form, the user will transition to the Formulation stage. More about dotting as a type of formula will be explained in Chapter Formulas.


You may also create a new action that will complete the process if the request is not approved
(On Completed Action - Complete the Process).


2.4.4 Adding Transitions

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 2.13). 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

Figure 2.13 Adding Transitions 

This will open a pop-up window where you will define your action in the following steps (Figure 2.14):

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

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 Review)

Figure 2.14 Adding Transition to Request Review action on Completed Request

After saving the transition, the two stages are now connected (Figure 2.15). This means that after the user completes the request, they will transition to the Request Review stage.  Since we didn't choose any condition for the transition, this will happen on each completion of the Request.

Figure 2.15 Transition Added

Stage dependencies can be different based on your flow sequences (Figure 2.16). In the Lab Work flow you can see them all:

1 - Sequential

2 - Looping back

3 - Parallel stages

Figure 2.16 Stage Dependencies 

Transition Conditions

Always - Account for all possibilities in transitions

Be careful when adding conditions to a transition. If you do so, you need to account for all possibilities and not to leave any loose ends. If not all possibilities are covered, you would get stuck in a process where all stages are complete, and none is activated.

Covering both cases in transition from Review Request to Formulation Step


Stage runs

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, seen in Figure 2.17). 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 activates all actions that are defined for that stage. All of these runs are done and edited in the same stage; however, they do not automatically overwrite or modify any of the records from previous runs (unless the user does so).

Figure 2.17 Stage Runs

2.4.5 Adding Create Task Action

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 2.18):

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 5. Tags.

5 - Write the Subject

6 - Write the 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 6. Formulas. Subject is limited to 80 characters, including spaces and quotes, while the Description can contain up to 2048 characters, spaces and quotes included. 

Figure 2.18 Adding Task

Always - Create a task per stage

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

Always - Paste As Plain Text

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 recognize your text as a string value, and an issue may occur.

Advice - Assigning a task

You should assign a task to only one person whenever possible.

Writing Subject and Description for a task on the Review Request stage

Lab Manager needs to review a request that is completed by Sales. When Sales person completes Request, Lab Manager needs to get a task to review it where (s)he will see what (s)he needs to do. You will do that by adding Create Task action. In the Task Subject you will write 'Review ' + ProcessName + ' Request'. Our Lab Manager will receive a task. In its subject (s)he will see which Lab Work needs a review request. 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. 


Advice - Unique Task Subject

Task subject should be as unique as possible. That is how 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.

Task assignment to the person who has created the process

A Sales person has started the new Lab Work process, (s)he has finished the Request stage, the next stage, Request Review is being reviewed by the Lab Manager. If the request is approved, the process is continuing to the Formulation stage and further. The Lab Manager wants to delegate the Report stage to the person who has created the process but there are multiple Sales persons with the tag HAS_ANY_TAG(Tag[Sales]). In the stage 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.


2.4.6 Adding Notify Action

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 2.19):

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 5. Tags.

5 - Write the Subject

6 - Write the Description

Figure 2.19 Adding Notify Action

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 6. Formulas.

2.4.7 Adding Create Record Action

You can customize 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 (2.3.3 Adding Record Templates to a Stage).

Go to the Actions tab and click on the + New Action on the stage you need to add the actions and follow the steps (Figure 2.20):

1 - The event that triggers the action, which for Create Records is on Activated.

2 - Define a condition under which the action will happen. Following the example, we want this action executed only if the field with the identifier pHTestNeeded from the record template with the identifier TestSelection is true ("Yes" selected).

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 also be a formula dependent on a field (i.e. NumberOfFormulations).

Figure 2.20 Adding Create Record Action

Always - add Record Template to the stage before adding Create Record action

Make sure that the Record Template is added to the particular stage before adding an action that will Create Record. If 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.

Advice - Use Create Records Action when you want records to be created under some condition

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.

Creating a pH Test Results record as an action on activated Characterization

In the Alchemy Lab, after reviewing the request, the Lab Manager decides which tests need to be done in the Characterization stage. 

When pH test is needed, Lab Manager will check "Yes" in the field named pH test needed with the identifier pHTestNeeded in the Request Review stage. To create a record for the result of the pH test when this is checked, you will add an action to the Characterization stage, on activated stage when pHTestNeeded = true, create record: pH Test Results, number of records: 1. To make sure that one pH Test Results record will be open without a possibility of adding another one in the User Portal, by user, you need to adjust Minimum Records to zero and Maximum Records to one. You will do that in the Lab Work Process Template when adding record templates to the stage (Chapter "Adding Record Templates to the Stage").

2.4.8 Adding Send Email Action

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 need to add the actions. Adding Send Email Action is done in the following steps (Figure 2.20):

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:

  • By entering the recipients email address inside single quotation marks ' ' (i.e. 'john.johnson@gmail.com') 
  • By using a System data, (explained in 6.3.3 User Data chapter) to map out appropriate user email (i.e. Record[Request].SalesResponsible.Email where Record Request is created earlier in the process and SalesResponsible is the identifier of a User type of field. Email as a system data will pull the information from Alchemy for the User selected in that particular field)
  • By using an identifier of a field created for a user to type in an email address (i.e. Record[Quote]].CustomerEmail where CustomerEmail is the identifier of an alphanumeric field. If User enters an incorrect email address or other text inside that field, the system will not report an error but the email will not be sent.)

5 - Write the Subject

6 - Write the Description

Figure 2.21 Send Email Action

2.4.9 Adding Complete Process Action

Executing this action will complete the process, which will close all other stages. Adding this action is done following steps 1-3 of the above actions.


2.5 Privileges

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 can start with mapping privileges in the Process Template Design Document from Chapter 7. Design Templates.

Lab Work process privileges

In the Lab Work, Sales are able to create the Lab Work process and fill in the request step. 

In the following stage (Request Review), everyone can view the decision, while only the Lab Manager may approve or deny the request.

Formulation and Characterization are done by Chemists, while Sales can only view to keep track of the process.


There are two 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:

  • create - create a process from a process template. This privilege is required, and must be given to at least one user tag (defined by tag expression).
  • set priority - change the priority of each process created using this process template. This privilege is required, and must be given to only one user tag. In the User Portal, your organization's processes will appear on the list based on priority.
  • put on hold - the process is on hold and the users cannot work on their tasks until it is reactivated. However, they can edit records in the process, but it will not move forward (i.e., complete the task to move to the next stage).
  • void - stopping the process and all work related to it. Once voided it cannot be reactivated again, but it stays visible in the User Portal. 

2) Stage Privileges are defined for each stage separately and define which users can:

  • View or
  • View and Edit the stage

And on which conditions they have those privileges.

2.5.1 Adding Process Creation Privileges

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 added using the User Tags (explained in Chapter 5. Tags), writing them 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 2.22). 

Figure 2.22 Adding process creation privilege

2.5.2 Set Priority Privileges

Set priority privileges can only be given to one user tag. 

Never - Expression usage in the assigning priority

For defining priority setting privilege, you must specify only one tag by writing its exact name. You cannot use expression (i.e. HAS_ANY_TAG).

Advice - Create a special 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.

Adjusting Set Priority for Lab Work

Only Lab Manager can prioritize work in the Lab Work process. You can achieve that by adjusting Set Priority Privilege. You need to assign it writing only a tag name in the "To:" field Tag[LabManager]. Or you can create a LWPrioritySetter tag. Assign it only to one person and then in the "To:" field write Tag[LWPrioritySetter].

2.5.3 Adding Other Process Privileges

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 receive it 

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 2.23 adding “void privilege” is shown. 

Figure 2.23 Adding void privilege

2.5.4 Adding Stage Privileges

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 2.24):

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 receive it

3 - What the privilege allows them to do (can view, can view and edit)

Figure 2.24 Adding stage privilege - Can View and Edit

All privileges can be added to users under a certain condition, using the same principle as for actions.

Assigning View and Edit privilege for Request Review using conditions

You need to assign view and edit privileges in the Request Review stage to certain workgroups, based on what location is selected in the Request. In order to do that, each tag privilege should be defined separately. If location 'New York Plant' is selected - person who has tags "New York" and "LabManager" will get the assignment (Figure 2.19). If location 'Tokyo Plant' is selected - person who has tags "Tokyo" and "LabManager" will get the assignment. You will achieve this by creating two separate privileges, by defining a condition in "When" field and by choosing appropriate tag in the "To:" field. When the location selected is 'New York Plant' you will write Record[Request].SelectPlant = 'New York Plant', To HAS_ALL_TAGS(Tag[LabManager], Tag[NewYork]), select Can View and Edit. You will do the same for Tokyo Plant. 


2.6 Verify, Publish and Version - Process Templates

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. In order to make the changes available in the user portal, you will need to publish your work.

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 of the steps from above are configured correctly. If something is not correct it will notify you to adjust the configuration. After a successful verification, a Publish button will appear:

Publishing the process template will create a new version. In the Process Templates 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.

What happens with processes created before publishing a new version?

Processes created before publishing a new version will remain in the old version in the User Portal, which means they will not have the changes published after its creation.

2.7 Deleting Process Templates

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 2.25):

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

Figure 2.25 Deleting Lab Work Process Template

When can a process template be deleted?

You may only delete process templates if no process was created for it in the User Portal or if it is not referenced in any other processes.

2.8 Additional Options For Process Templates

Figure 2.26 Process Additional Options

You can also Edit, Duplicate process templates, and Export it to .json type of file. In Figure 2.26 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. 

  • By choosing Edit, the same screen as presented in Figure 2.26 where you can change the name of the process template or edit any other information, or just continue working on the configuration. 
  • By choosing Duplicate, a new modal dialog will be presented (Figure 2.25 A). In order to save the duplicated version of your process, you must change both the Process Template Name and the Process Template Identifier and then click on the DUPLICATE button. This action will create a new process template with all stages, records, fields, actions and transitions exactly the same as in the original one but with a different process template name and identifier. You can now edit each process further.
Figure 2.27 Duplicate Process Template Dialog

  • By choosing Export, you can get the whole process template saved as a .json file on your computer. You can later make changes directly in that file and import it back by clicking on the IMPORT PROCESS TEMPLATE button. Please remember that at least Process Template name and Identifier must be unique prior to import.

3. Record Templates

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. 

3.1 Record Templates Page Overview

Figure 3.1 Record Template Page Overview

1 - + NEW RECORD TEMPLATE button - for creating new template from scratch

2 - IMPORT RECORD TEMPLATE button - to import a record template form .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



3.2 Configuring a Record Template

Figure 3.2 Inside a Record Template

1 - Record Template Name and Edit Button - a pen for opening  the right-hand side menu will open

2 - Verify - Alchemy is checking if the configuration is in order

3 - Grid -  the working space for creating digital forms

4 - Record Template Menu - details about the Record Template

4.1 - Record Template Identifier - an identifier which is used for referencing the Record Template

4.2 - Record Template Description - short info about the Record Template

5 - The three dots, Delete - option for deleting the Record Template

3.2.1  Creating a New 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 (i.e. LabWork, New_Product_Development, Quote etc.).The Identifier is used to reference your template in formulas.

Figure 3.3 New Record Template Pop Up

1 - Record Template Name

2 - Record Template Identifier (automatically suggested after the name is typed in)

You can start making your record template in a grid. This grid is the working space for creating digital forms (in our case Record Templates). Each Record Template consists of different field types that have different properties. Each field type will be explained in Chapter 3.2.5 Field Types

Field with Name identifier in the first record of the first stage in a process

When creating a new process template the first stage is created by the system. Inside this stage the first record needs to have a field with an Identifier "Name". This field needs to be an Alphanumeric field type and should be a required field. Whatever the user writes in this field will be the process title. In the Calculation Formula of that field you can put a pattern, a string of text, or a combination of other fields inside that record and patterns. There is a wide range of possibilities.

Important: Only one record with the field with an Identifier "Name" may be in one process template.


Always have a unique Name and Identifier

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.

Words and phrases that can't be used as Identifiers

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
  • Template
  • Status
  • CreatedOn
  • CreatedBy
  • Process
  • Stage


3.2.2 Creating a New Field in the Record Template

Advice - Think first, configure later

At the beginning of creating a record, think about what fields will make up the contents of the Record Template. In that phase, we recommended using our template from Chapter 7. 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 3.4
  2. Select the field type you want to create from the list e.g., Alphanumeric
Figure 3.4 Steps 1 and 2 for Field Type Creation

  1. Enter a Name (1) and Identifier (2). The Name and Identifier need to be unique on the Record Template level. But two different Record Templates can have a field type with the same Name and Identifier. See Figure 3.5.

Advice - use a label if the field name is an interrogative sentence

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.

Figure 3.5 Step 3 for Field Type Creation

In the right-side record menu in the tab "Properties," additional options are available. These options will be explained in the next few chapters (Figure 3.6).

Figure 3.6 Properties tab on the right side

Grid Navigation

The record template fields can be rearranged by dragging and dropping on the grid. Select the field you would like to move, drag it on the grid and place it where you find suitable. When moving a field, it will always snap to the upper left corner of the target square. Moving the field outside of the grid borders will return the field to its original place. See the before and after grids in Figure 3.7 and Figure 3.8, respectively.

Before:

Figure 3.7 Fields on the grid before rearranging

After:

Figure 3.8 Fields on the grid after rearranging


Red areas around the field types are their margins. More about them will be explained in the next chapter.

Margins

Areas on the grid that are not occupied by field types or their margins are blank. Blank rows and columns on the grid appear to be separating fields in the Configuration Portal, but in the User Portal, these blank areas will be rendered differently. The rows are removed in the user portal if the whole row is blank. The fields are not shifted up, but all the fields are then shifted to the left, wherever there is space.

The fields are moved next to each other, which is why they may appear “glued” together. To make sure that the layout in the User Portal is the same as the one you configured, you can add margins to the fields in any of the four directions. 

Use margins to separate fields

Blank rows and columns appear to be separating different fields in the Configuration Portal but, in the User Portal the fields will appear "glued" together. To avoid this, add margins around the fields if you want to make them separate.

Fields with and without margins

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.

To separate the fields, you can adjust the margin between them. Margins can be  adjusted on the right-side menu in the "Properties" tab. In the example shown in Figure 3.9 B, the bottom margin of the field Formulation Name is set to 5. 


Figure 3.9 A) Fields without margins compared in the Configuration and User Portal

Figure 3.9 B) Fields with margins compared in the Configuration and User Portal

The same principle applies to fields that are put next to each other, but adjustments are done to left and right margins. If fields don't have margins around them (red highlighted squares), the fields will be stacked together in the User Portal. When adding margins to fields in the right-hand side properties tab, you can write the desired number of squares for margins or use the + and - buttons to adjust the margins.

Never add margins through the grid limit

If you have only 4 rows until the end of the grid on the left side but added 5 left margins 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

You can adjust the size of a field by changing the field width and height in the Properties tab. An example is shown in Figure 3.10.

Figure 3.10 Field size adjusting

When adjusting the size, the field will expand first to fit the entire label and then the input section will expand. The size of the label and the input section will be preserved on the user portal. If the user writes an input that is larger than the section, a scroller will appear, instead of adjusting the size of the field.

Field Name Properties

The gray area with the Field Name is the Label of the input field in the User Portal.

You can format how the field name will be shown in the User portal. In the field properties, under the "Name Properties" you can set:

  1. Name Size - the number of squares the name will use. If left blank, the name will be autosized to fit the text, and the input field will use the remaining space.
  2. Name Orientation - Define where the name will be related to the input.
  3. Alignment - Vertical and Horizontal
  4. Font and Size
  5. Name Styles and color
Figure 3.11 Field Name Properties

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 3.11A

Figure 3.11A) Field name size scaled automatically

Figure 3.11B) Field Name Size set to a specific size

You can change the label orientation to "Left," "Right," "Top" or "Bottom" as seen in Figure 3.12.

Figure 3.12 Different label orientations



In Figure 3.13 A and B, an example of the field is shown in the Configuration and User Portals. Label orientation is changed from left to right.


Figure 3.13 A) Field labels on the left side


Figure 3.13 B) Field labels on the right side



You can define if the field name is shown in the User Portal by selecting the checkbox "Show Field Name as Label" in the Properties tab. If it is not checked, only the input field will be visible without a label. See Figure 3.14. 

Figure 3.14  Field with and without a Label



Changes to the font and styles will only be visible in the user portal.

Field Borders and Text Format

You can set Borders and Text Format for the input section of the field in the properties tab. An example is shown in Figure 3.15. Borders are shown around both the field and the label in the Configuration Portal, while in the User Portal it is only around the input field.

Figure 3.15 Different options for field borders and alignments

Text format options are set under the Input Properties section, and are the same as the Name Properties. In this version of the app, format are not visible in the Configuration Portal, but the changes are applied to the User Portal. 



For more formatting options, use the Label field type which will be explained in detail in Chapter Label.

Advice for different borders

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.



3.2.3 Deleting and Duplicating Fields

Fields in the Record Template can be deleted or duplicated by clicking on the 3 dots on the far right of the screen.

To delete a field, select it and click "Delete" from the drop-down menu on the 3 dots.

To duplicate a field, select it and press "Duplicate" from the drop-down menu on the 3 dots. A window will pop up where you need to provide a new Name and Identifier for the duplicate. After those changes, a field with the same properties and type will appear below the original field. Keep in mind that all text alignments, field width and height, borders, design elements, calculations, and other properties are being duplicated (Figure 3.16). Don't forget to change those items if needed. The field type and uniqueness settings will also be duplicated, but not editable afterwards.

Figure 3.16 Changed Name and Identifier for a duplicated field


3.2.4 Advanced Settings

In the right-side field type menu is a section called "Advanced Settings." Most of these settings 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 complete the stage in the User Portal if (s)he did not fill in all of the required fields on the Stage. 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 3.17.

Figure 3.17 Required field shown in the Configuration and User Portal


Allow Multiple Values - checking this box will allow a user in the User Portal to enter multiple values, dividing them with a comma while inputting. 

Printable - This box is checked by default, and determines whether the field will be shown when printing the record or not. Instead of fields that are not printed, a blank space will be shown.

Figure 3.18 Printable Fields

Hidden - Checking this box will not show the field on the User Portal. Hidden fields will still have values determined by the calculation formula (explained below). This is useful for some local variables, that you do not need the user to see, but you need for intermediate calculations or filtering.

Hidden Fields - Project Scoring

In the NPD Request From, the user might be asked to assess the complexity of the project. You could 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 would not be visible on the user portal, but you can use the numerical value to calculate an end score or risks etc. 



Field Visibility Condition - a field can be shown or not shown in the User Portal under specific conditions. For example, a field to write pH value can be shown when a pH test is selected. When pH test is not selected, the field is not shown. The condition is written in a formula form, and it returns a boolean value. All the formulas are defined in Chapter 6. Formulas.

Visibility Conditions - selection of the pH test

In the Review Request stage Lab Manager is choosing tests after approving the Request. There is a list of checkboxes offered for a specific test selection. Different tests can be visible depending on what is checked in the list. See the checklist in Figure 3.19 B. Only the pH test is selected. The name of this selected field is pH test needed and the identifier is pHTestNeeded. The field where User should write the result for the pH test has the name pH Result and identifier pHResult. The condition in the Visibility section of the advanced settings for pHResult will be phTestNeeded = true as seen in Figure 3.19 A. In this case, only when the checkbox pH is selected the field for the result will be visible.

Fields that are not visible do not have a value!

A field that has a visibility condition false will not have a value. This means that this fields can be used in calculations only if the visibility condition is true. The calculation formula is triggered only when the field is visible.

This is different than the hidden fields, since hidden fields always have the value, even if not shown on the User Portal.



Figure 3.19 A) Visibility condition for field pH Result

Figure 3.19 B) Visibility condition for field pH Result shown in the User Portal


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 3.20. In the record Template called Equipment Malfunction, a field for Priority should be filled out. When the user hovers over it, a helper text will appear explaining the details about different priority statuses.

Figure 3.20 Set up of the Field Helper Text


Calculation Formula - to give the field a calculated value, you can write a formula in this field by following the rules from Chapter Formulas

Calculation Formula Example - average value of three measurements

In the Characterization stage 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, pHRasult3. 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 3.21.


Figure 3.21 Calculation Formula Example

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.

Provided - when checked, this field will have the value provided from the Stage Template. Checking this field will hide the calculation formula, and you will be able to set it for each stage separately. This is useful if you want to have the calculation formula depending on the context.

Figure 3.22 Provided Formula Configuration Example



Provided Formula - Approvals

Provided values are used when one record template is re-used in different stages, and we want to have some values depending on the context the record is in. If we use the same Approval Form record in both the Request Review and Lab Work Review stages, you could have a field in the Record Template that will write the Stage Name. 



3.2.5 Field Types

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, Chemical Structure and Image.

Each field type has additional properties you can define, other than the Name and Identifier.

Label 

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, only the Label title should be filled out, and it does not have to be unique (Figure 3.23). The Label field type does not have an Identifier; it can be used as a headline for another field or provide additional information on the digital form. It is used for column and row labels when making tables in Alchemy. 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 instead of the field name, please remember that the field name will actually be the one used for filtering in views and therefore, set one that will make the most sense.


Figure 3.23 Label field type creation

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 3.24

 

Figure 3.24 Formatting the Label type field in the Configuration Portal.

Alphanumeric

The Alphanumeric field is 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.

Uniqueness

While creating the field, you can also select whether the input in the User Portal should be unique. If selected, you can choose the scope where the field will be unique from a dropdown menu. See Figure 3.25.

Figure 3.25 Definition of uniqueness for an Alphanumeric field type

The scope in which the field must be unique may be:

  1. System - the field value will be unique in the entire system. The same field in any other record template cannot have the same value, regardless if the same users are able to see it. (e.g., anywhere)
  2. Process - this field will be unique in each process where it is used (e.g., each Lab Work). Field input has to be unique on the process level (input in every record on that process has to be unique).
  3. Record - Input has to be unique per record (two different records on that process can have the same input).
Alphanumeric lists and predefined values

Input for the Alphanumeric fields in the User Portal can be provided in a predefined value list. To set this up, under the tab "Values," you can enter the values the user will see as a dropdown menu. If you click on +NEW VALUE a window will open. 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 3.26).


Figure 3.26 Predefined values for the Alphanumeric field type


Number

In a number field (e.g., , Volume, Weight, pH) users can enter any number in the User Portal. As Admin you can define the number of decimal places that will be visible. 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 view mode in the user Portal (rounded), but in the edit mode, all decimal places will be visible. 

The Number field type, like the Alphanumeric, can have a defined uniqueness on the System, Process or Record level. 

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 values under the "Values" tab.


Type of input fields - Alphanumeric or Number

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 - as you cannot perform mathematical operations with them.

Advice - when to use Alphanumeric and Number field types

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

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

Table 3.1 Different Time and Date formats supported by Alchemy

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 3.1. The function is further explained in Chapter 6.

Advice - TODAY function for dates

It is common to use the TODAY function in a date field. This will write the current date in the field when evaulated (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 explain in Chapter 6.


Yes/No

Yes/No 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 User selects one of the options, they cannot unselect both again.

Advice - Yes/No field type in use

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 the result will become visible in the form, as seen in Figure 3.27).

Figure 3.27 Visibility condition according to a Yes/No field type

Checkbox

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.

Advice - common uses for Checkbox field types

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.


Checkbox field type as required

If a checkbox is set as a required field, it has to be checked in the User Portal in order to complete the stage and continue with transition.

As mentioned in Chapter 3.2.2 Creating a New Field Type, if you are making field names that will contain a question, it is better to use a separate label for the question and uncheck the "Show Field Name as Label" checkbox. This is usually most applicable to Yes/No and Checkbox fields. The user will then have a more intuitive record to fill out, while the manager will have more consistent field names when creating a report.

Rich Text

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:

  • The text can be formatted by a user in the User Portal
  • The field height can be adjusted by the user in the user portal
  • It cannot have multiple values
  • It cannot have predefined values (a dropdown menu in the User Portal)

In Figure 3.28 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. 

Figure 3.28 The editor for the Rich Text field type with a link and image attached


Attachment

Attachment fields are used to enable users to attach files to records in the User Portal (e.g., SDS, Quote, Sample Image). The file preview size is set by the configured field size. Here are the settings:

  • If the field height <10px and the label is visible, file is displayed as file name
  • If the field height <6px and the label is not visible, file is displayed as file name
  • If the field height >=10px and the label is visible, file is displayed as the thumbnail if the file type is supported, otherwise it is displayed as file name
  • If the field height >=6px and  the label is not visible, file is displayed as the thumbnail if the file type is supported, otherwise it is displayed as file name

The size of one square in the configuration portal grid is 8px x 8px


Supported attachment file types, displayed as thumbnails are: .pdf, .xlx, .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 100 MB.

Attaching files

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 the attachment field in a repeatable row or repeatable column group. The groups are further explained in Chapter 3.3 Field Groups.


Advice - allow the User to add multiple attachments

To allow the User to have multiple attachments, the field for attachment should be put inside a Repeatable Row or Repeatable Column group. As shown in Figure 3.29, the dedicated field type for the attachment is placed inside a Repeatable Column group (marked slightly darker grey on the image) and in the section Repeatable Options set "Defined by User". In the User Portal there will be a plus button above the field for attaching (Figure 3.29), so the User can add as many attachments as (s)he needs. More about group creation will be covered in the chapter 3.3FieldGroups.

Figure 3.29 Multiple attachments allowed by putting the field in a Repeatable Column Group

 

Advice - multiple attachments with separate labels

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. 


Record

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 (fields). In the User Portal, it will be shown as a dropdown list with all Records created in 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.

Only published record templates can be referenced

The record templates you want to reference have to be published, both on the record template and process template level.

The creation of the Record field type is shown in Figure 3.30. 

  1. First, enter the Name and Identifier
  2. The next step is to enter the Referenced record templates. A dropdown list with published record templates will appear. 
  3. In this example, the Record field According To Lab Work Request is referenced to record templates Request Form
Figure 3.30 Creation of the Record field type

Figure 3.31 shows how the Record field type looks in the User Portal.

Figure 3.31 Record field type, choosing a referenced record from the drop-down list

Company referencing in Opportunity record template

In the Opportunity record template, the Sales person needs to choose for which company is the sales opportunity (s)he is working on. If the company which is needed is not available in the dropdown list the salesperson can click on the + New RecordCompany. This option will be available if you follow the explanation of adding appropriate record templates to stages in chapter 2.3.3 Adding Record Templates to a Stage. Right after the Sales person finishes inputs for the Company record, this new company will be available for choosing in the Opportunity record.

Record Filter Criteria

In the Advanced Settings for the field type Record, an additional section is available called Record Filter Criteria. In this section, you can filter down the records the user can choose from the dropdown list of the record field in the User Portal. Filter expressions are written using the Result keyword, which refers to the referenced record templates chosen upon field creation.  More examples for the Record Filter Criteria formulas are explained in chapter 6. Formulas in the section 6.4 Result and Item.

Show only the list of contacts from a particular company

Sales person in the Request Form should choose Company and Contact for that request. After choosing the Company from the dropdown it is expected that under Contacts you can choose only among ones that are employed in the chosen Company. 

Both Company (Identifier: RequestCompany) and Contact (Identifier: RequestContact) are Record field types. While creating a Contact field you will choose record Contact in the Referenced Record Template. In order to filter down companies you will set the Filter Criteria with: Result.Company = RequestCompany. The keyword Result is always used to filter down the options for the dropdown list. Company is the identifier of the record type field in the record template Contact that system needs to know in order to show only Contacts that have that field equals with RequestCompany field from the current record template.


Process

Process field type is a field in which you can reference a process. 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 type if you want to have a hyperlink to the other process, if you want to have access to the data from that process, or if you need a system data for that process (who created that process, what its status is, etc. chapter 6. Formulas, includes the whole list of system data).

While creating it, you have to define which process template you are referencing. By selecting "Lab Work," the user will see a dropdown list with all the Lab Work processes created in the User Portal.

Only published record templates can be referenced

The record templates you want to reference have to be published, both on the record template and process template level.

See the Process field type creation in Figure 3.32. It is similar to the Record field type creation, but instead of choosing the Record referenced templates, you will choose Process referenced templates. In the User Portal, the representation is the same as for the Record field type shown in Figure 3.31.

Figure 3.32 Process field type creation


Advice - usage of the Process field type

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.

Request form from a specific record template

Request Form record template is standardized and is used in all process templates where request is needed (i.e., Lab Work, Sample, Recommendation etc.). Lab Manager is starting a New Product Development process where (s)he needs to refer to the specific Request Form from Lab Work. You will enable him/her to do that following the next steps:

  • Create Process Field Type, identifier: ProcessFieldType
  • While creating it you will choose from the dropdown in the Referenced Process Template - Lab Work. 
  • Create Record Field Type.
  • While creating it you will choose from the dropdown in the Referenced Record Template - Request Form. In the Record Filter Criteria write the expression: Result.Process = ProcessFieldType to narrow the choices for the offered records in the dropdown list.

After configuring this you enabled Lab Manager to choose only Request Form from Lab Work process templates.

Process Filter Criteria

In the Advanced Settings for the field type Process, an additional section called Process Filter Criteria is available. In this field you can write formula 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.

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 6. Formulas.

Process Filter Criteria according to process status

In the stage Request (the first stage of the process Lab Work) there is a Process field type with Name: Reference to Previous Lab Work and Identifier PreviousLabWork. In this field the Sales person is choosing the process, a previous Lab Work, which is connected to the current Lab Work on which (s)he is working on. To filter down all possible Lab Work 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).


Pulling Data from a Referenced Process

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 6. Formulas


User

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. For this field, you can define User Filter criteria using the expressions for tags (Chapter 5. Tags). This is the expression that defines the list of users that will be available for selection. If the filter is not defined, a dropdown menu in the User Portal will show the complete list of all system users. In Figure 3.33 the User field type in the User Portal is shown.

Assigning the Sample Preparation to a specific Chemist

In the Request Form the Lab Manager can decide from a list of Chemists to whom (s)he will assign the task for Sample Preparation to. In the Request Form, there is a User field type with the Name: Assign Sample Preparation to and identifier: AssignSamplePreparation. In the User Filter Criteria, you can filter the selection with this expression: Result.UserTags = Tag[Chemist]. That way the Lab Manager can select only Chemists.


Figure 3.33 User field type in the User Portal

Words and phrases that can't be used as Identifiers

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. They are:

  • FirstName
  • LastName
  • Email
  • UserTags

Link

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 URL and Link Text in edit mode. In view mode Link text is shown with the possibility for the user to click on it. This action will open a new browser tab and load the defined webpage. See how the Link field type looks in the User Portal in Figure 3.34.


Figure 3.34 Link field type in the User Portal

Multiple links are enabled by putting this field inside a Repeatable Row group, the same as for the attachment field type.

The Link field type, like the Alphanumeric, can have a defined uniqueness on the System, Process or Record level. 

Chemical Structure - functionality coming soon 

Chemical Structure is a type of field that will allow the user to draw or upload structural chemical formulas in the User Portal. In view mode, an image of the chemical structure is shown. In edit mode, the chemical structure editor is loaded. The size of the field in which the user can draw the formula is set by the field size in the configuration portal.

Multiple chemical structures are enabled by putting this field inside a Repeatable Row or Column group, the same as for the attachment field type.

Image

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. The field size in the configuration portal, must be the same size as the field!

Size of the Image field

When uploading a picture to the image field, the picture size must not be greater that 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 your company logo on records you need to print (i.e. reports, quotes…).

3.2.6 Page Break

In addition to the fields and field groups, you can also add a page break anywhere in your records. This element has no additional settings and is represented by a simple blue line in the configuration portal.

Figure 3.35 - Page Break

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.


3.3  Field Groups

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 3.36):

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.

Keep fields inside a group lines!

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.

Each group type has a special setting requirements for margins. Those will be explained in the following chapters, for each group type separately.


Figure 3.36 Creating a Group in the Configuration Portal


Advice - group beyond the field borders

When 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 3.34, under number 5, you can see that the darker gray square is bigger than the fields inside it. For 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 fields 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.

3.3.1 Simple Group


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 like field types. The first part is for the design elements, for setting up group width, height and margins. In the advanced setting for the Simple group type, you can see the field for the Field Group Visibility Condition (Figure 3.37).

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.

Figure 3.37 Simple group type

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.

Simple Group - fields related to the same topic and visibility condition

Multiple fields in the record Physical Characteristics can be grouped together. Properties like Density, Opacity, 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 field Field 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 the how this looks in the Configuration Portal in Figure 3.35.


Deleting and Duplicating Groups

Groups can be deleted and duplicated. To do this, click on the three dots in the upper right corner and choose Delete or Duplicate. If you duplicate a group, all the settings will be duplicated, the design elements as well as the visibility condition.


3.3.2 Repeatable Row

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 attach multiple files under each other (explained in subchapter Attachment)

3 - when you want to allow the user to add multiple links under each other

4 - when you want to allow the user to add multiple chemical structures under each other

5 - in general, when you need a field or a group of fields to repeat under each other (it could be a Notes field as 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 3.3 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.

Repeatable Row Margins

If the Repeatable Row group has the Repeatable Option set to User Defined,  the Left margin needs to be minimum 13. When the Repeatable Row group is used to make a table, a Simple Group will be above it as labels for the columns (chapter 3.3.1 Simple Group). For this Simple Group in this context the same rules apply, Left margin 13. If the Repeatable Row group is used without the simple group then the additional Top margin needs to be set to at least 3.

If the group has any other Repeatable Option set up, minimum margins on the Left need to be 5 (Figure 3.38). 

The reason for the "extra" margins is that the additional select options and controls are visible in the User Portal and are taking up this "empty" space.

Repeatable Row for Review Notes

In the stage Lab Work Review of the Lab Work Process, in the record Approval, after the information whether the Lab Work is approved there is a notes field with the Name: Review Notes (Alphanumeric). You may want to allow the user to add different Review Notes, in case the process loops back and it is useful not to change the input of the field that was written in the first stage run. You will put that field inside the Repeatable Row group and in the advanced settings for Repeatable Options select "User Defined". In the User portal a plus button will be available under the field and the user can add multiple Review Notes (Figure 3.39).


Figure 3.38 Creating a Repeatable Row group in the Configuration Portal and setting up appropriate margins

Figure 3.39 The Repeatable Row group option in the User Portal with the User Defined option

How to make a table in Alchemy?

In every table in Alchemy, there are two parts that need to be considered. First you need to create the column names or labels. This part will not be in a repeatable row group; all labels will be inside a simple group. The next set of fields are the input fields that will be placed under the labels on the grid. These fields will be inside the repeatable row group because you want just the input fields to repeat, not the labels. Also, the input fields will have the checkbox "Show Field Name as Label" unchecked because labels above them are already explaining the inputs. However, the field names will be visible later in the views and not the labels, so make sure they are also self-explanatory.

Here are the steps for creating a table in Alchemy:

  1. Create all the column names, labels you want to have
  2. Create a simple group and place it above the labels. Set group margins to Left: 16, Bottom: 0 Right: optional, Top: optional
  3. Create input fields that can be different types (Number, Alphanumeric, Checkbox, etc.). For each field uncheck the "Show Field Name as Label" checkbox.
  4. Create a repeatable row group and put it above the input fields. Set group margins to Left: 16, Bottom: 4 Right: optional, Top: optional

A horizontal table in Alchemy

To make a characterization table in the Characterization 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. Next, make the input fields; in this example, all input fields will be numbers. Make a repeatable row group and place it over the input fields. In this case the Repeatable Option will be User defined. In the user portal, chemist will add as many rows as they need for their characterization measurements. In Figure 3.40 you can see how the table looks in the Configuration and User Portals.

Figure 3.40 A table in Alchemy, in the Configuration and User Portal

Advice for field borders in a table

When you are making a table, the first row will be label fields and the second row are input fields that are repeatable. If you would like to add borders to all fields try not to 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 add 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 has already two borders shared with the field above and before it. In this case just two additional borders are needed.

Visibility conditions in tables

Make sure the same visibility condition is set for table Labels-a simple group and for the input fields in the repeatable row group. It is possible to set visibility condition for each label and input field individually, but it is best to wrap all labels and input fields into one simple and one repeatable row group and set the group visibility on it.

Repeatable Options

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. These options are:

1 - Defined by User

2 - Determined by Formula

3 - Determined by Record Reference

4- Determined by Filter

In the previous examples, the Defined by User option was used, and the User Portal, a + Row button appeared under the input row. This means that the user can add as many rows as (s)he wants. 

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.

Number of rows determined by number of samples

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 (Figure 3.41).

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.


 

Figure 3.41 Repeatable Row with the option Determined by Formula

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. R1 is in process A and R2 is in process B. You are currently in the record R2 making a row table with 3 fields that are repeating. 

  1. A precondition is to add a record reference field in record R1 where you will be referencing record R2. This field is providing a connection to R2. For example, the Name of this field is Connection Field.
  2. In the group advanced settings of the repeatable row in R2, in the Referenced Record Template field you can choose the template that you want to reference. In this case, you want to reference record R1. You will choose it from the dropdown list.
  3. In the Referenced Record Fields you will see a dropdown list of the possible record reference fields from the record R1. In this case, you will select the Connection Field.
  4. The last field is for the Filter Criteria. Here you can filter down from which records you will pull data. Here you can use the Result keyword for system data or fields inside the referenced record. More about this is explained in Chapter 6.4.1 Result.


How to make a bound table in Alchemy?

Following the theoretical example in the previous chapter, you can make a bound table in Alchemy. A bound table allows you to pull the information from records to a table. That table is bound to a record template and is accessing data from created records.

In the Business Initiative process template we want to be able to keep track of all the NPDs done for a specific initiative. In the process template, in the last stage, we have a record NPD Summary, where we want to see this information, and where we will configure a repeatable row group, determined by record reference. This kind of tables are called "bound tables" in Alchemy.

Inside the New Product Development process template ,in Record template NPD Requirements The user will choose which Business Initiative the NPD belongs to. Each time the user selects a specific initiative, a new row will be created in the Lab Work Summary bound table - one row for each related NPD.

The process templates are described in the Appendix, showing where the records are located. And in order to configure the bound table, follow these steps:

  1. In the NPD Requirements record, create a record field with the name: Related Business Initiative and identifier: RelatedBusinessInitiative. Select the NPD Summary as the referenced record template. 

Figure 3.42 Field of the record template NPD Requirements

  1. In the NPD Summary record template, make a repeatable row group with the fields NPDName, ProjectAssignedTo and Details, that will show the data from the connected NPD Requirements records.
  2. Select the Repeatable Options for the group Determined by Record Reference. 
  3. In the Advanced Settings of the Repeatable Row Group, for the Referenced Record Templates choose NPD Requirements.
  4. In the Referenced Record Fields choose the field that was made in the step 1, called Related Business Initiative

In the user portal, when the users select a specific Lab Work Summary record in the Business Initiative Record

Figure 3.43 Configuring the bound table in the NPD Summary Record 

Now that the two tables are connected (bound to each other), you can access fields from the NPD requirements using the Item keyword (more about this in Chapter 6.3.2 Item).

In the Calculation Formula of each input field inside the Repeatable Row, a formula expression with the keyword Item should be added so that the information is automatically populated:

  • For the NPDName: Item.Process.Name (system field of the processes where NPD Requirements is situated.)
  • For the ProjectAssignedTo: Item.AssignTo (field identifier of the field Assign To inside NPD Requirements)
  • For the Details: Item.Details (field identifier of the field Details inside NPD Requirements)

In the user portal, when you create the Lab Work Summary record (i.e. LWS#1) you will be able to select it in the NPD Requirements Record, in the Fitness For Use Record field.

Repeatable Row Determined by Record Filter

When selecting "Determined by Filter" in the repeatable options for a repeatable row group, you can define what records will be auto populated in your table. After selecting this option, you will need to specify the Record templates which are to be bound and the Filter Criteria to narrow down the records of that template. You can choose the record template from a dropdown, while the filter criteria needs to be written as an expression explained in chapter 6.

Same as in a "bound table" explained earlier, you can access fields from the selected record template using the Item keyword (more about this in Chapter 6.3.2 Item).

Repeatable Row Groups determined by Record Filter are calculated only when the record is created or the group becomes visible. It will not update if new records fitting the filter criteria are created afterwards.


3.3.3 Repeatable Column

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 - when you want to allow the user to add multiple chemical structures next to each other

4 - 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 are the same as for the Repeatable Row, explained in Chapter 3.3.2 Repeatable Row


Never - apply two or more field groups to the same fields

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.

Repeatable Column Margins

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

Do not add label fields to a repeatable row/column group

You should not put a separate label field in a repeatable row or column groups. Labels are used for additional formatting options outside the tables.

3.4 Verify, Publish and Record Template Versions

While editing your process, all changes are saved automatically. However, users in the User Portal will not see the changes you make to the existing record template immediately. In order to make the changes available in the user portal, you will need to publish your work. 

The first step is to click the Verify button in the top right corner next to the sidebar.


Verify is used for Alchemy to check the configured data. Alchemy is checking entered formulas, conditions and other field rules. If something is not correct, it will notify you to adjust the configuration. After a successful verification, a Publish button will appear:

After you have published a record template, an additional step is needed. You need to publish again all process templates that contain that specific record template if you want the change to be visible in all of them

Publishing the record template will create a new version. The Record Templates page shows the latest published version of each record. When you create a process from a template in the User Portal, the newest version of the record template will be used.

What happens with processes created before publishing a new version?

Processes created before publishing a new version will remain in the old version in the User Portal, which means they will not have the changes published after its creation.


3.5 Deleting a Record Template 

To delete a record template, go to the record template page of the record you wish to delete, then (Figure 3.44):

1 - Click on the edit button next to the process name (pen icon)

2 - Click on the three dots on the right-side process menu

3 - Click "Delete" button

Figure 3.44 Deleting a Record Template

When can a Record Template be deleted?

You may only delete a Record Template if no process was created with it in the User Portal or if it is not referenced in any other processes.

3.6 Import/Export a Record Template

In the additional options on the record page (Figure 3.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.


Figure 3.45 Exporting a record template

To import a record template from a .json file you previously downloaded, on the record page select the Import Record Template option, and copy the "text" from the .json file into the dialog shown on Figure 3.46. This will create a new record template in your configuration.

Figure 3.46 Importing a record template

Keep in mind, that if you're trying to import a record template you previously exported, you should at last change the template name and the identifier by editing the .json file first.

4. Users

Users are all the people who will have access to the system in the User Portal.

Figure 4.1 Users page

1 and 2 - First and Last name

3 - Email

4 - Has Access To - information about the portal the user has access to

5 - Sorting options available for each column on hover

Clicking on the user name will open the User Menu on the right side (Figure 4.2): 

Figure 4.2 User menu

1 - User first and last name

2 - Properties - edit User information

3 - User Tags - edit (add/remove) tags a User has

4 - Customization Access - enabling this let's the user log into the configuration portal

5 - Remove Access/Invite User- remove User's access from the system. If you did not invite your user yet, "Invite User" will appear

4.1 Creating Users

Click on the  +NEW USER  and a window will pop up (Figure 4.3). 

After filling in all the required fields (First (Figure 4.3 Number 1), Last Name (Figure 4.3 Number 2) and Email (Figure 4.3 Number 3) you will be able to save (Figure 4.3 Number 4) the new user. 

Always - Unique Email

Make sure that Email address is unique for each user.

Figure 4.3 Creating new user

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. 

4.2 Adding Tags to Users

User Tag is a mark of a broader group that the user belongs to. By added tag, Alchemy will recognize privileges (Chapter 2.5 Privileges) for that user. This way you are able to assign multiple tags to one user.

To assign a tag, follow the next steps (Figure 4.4):

1 - Choose the user to whom you want to assign tags

2 - Click on the User Tags tab

3 - Click on the + ASSIGN TAGS

Figure 4.4 Assigning tags 

After the third step, a window will pop up (Figure 4.5). You can then assign appropriate tags from the list. There is no limit to the number of tags a user may have.

Figure 4.5 Choosing tags

4.3 Inviting a User

The new user will get an activation email from Alchemy when invited from the Properties tab using the INVITE USER button. The activation email contains a temporary access link. The link is active for 7 days (168 hours). By clicking the link, the user can activate the account and set their password. Until the user sets their password, under Has Access To it will be written "Invited." One user can be invited multiple times in case the link expires.   

4.4 Accessing Portals 

New users, after they are invited and set password, will have access to the User Portal by default. To enable access to the Customization portal for that user, mark the checkbox "Has access to customization" in the Properties tab (orange framed in Figure 4.2).

5. Tags

In Alchemy, tags are used to describe users in a way relevant to your organization. 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 user tag can be applied to several users, and one user can have more than one tag.

Figure 5.1 Tags page 

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 with the selected tag

4 - Delete - deleting the selected tag 


5.1 Creating Tags

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 Page. Click on the + NEW USER 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).

Always - Write tags using alphanumeric characters

Tag Names must be written using only alphanumeric characters (English alphabet letters and numbers) and underscores. Furthermore, they must start with a letter.

Advice - Use CamelCase

Write the names in CamelCase, which is capitalizing each word and removing the spaces between them (e.g. LabManager, OhioLab, FloridaHQ, TechServiceDept).

5.2 Tagging Users

After you have created a tag, you can tag users with it. Click on the tag name from the list on the main page (Figure 5.2 Number 1) and click on +TAG USERS (Figure 5.2 Number 2).

Figure 5.2 Tagging users

This will open a menu where you can select as many users as you wish. Alternatively, you may assign tags to a user directly from the Users Page.

Advice - Most useful groups of tags

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

5.2.1 User Tag Expressions

In some of the previous chapters, we used tags to define which users will be assigned a privilege or task/notification. 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_ANY_TAG(Tag[LabManager], Tag[Chemist], Tag[Technician])
  • HAS_ANY_TAG(Tag[Sales], Tag[Marketing])
  • 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:
  • HAS_ALL_TAGS(Tag[Chemist], Tag[SynthesisLab])
  • HAS_ALL_TAGS(Tag[Chemist], Tag[ApplicationLab])
  • HAS_ALL_TAGS(Tag[Sales], Tag[Americas])

Using tag expressions for assign privileges

In the Alchemy Laboratory, Dustin is a lab manager (has the LabManager tag). Devlin, Daisy and Lisa 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 Dustin. If we want to include him as well, we need to expand the formula: HAS_ANY_TAG(Tag[Chemist], Tag[LabManager])

5.2.2 Additional Formulas Can be Used in User Expressions

  • Union -  Calculates the union between multiple lists of users. Examples:
  • UNION(HAS_ANY_TAG(Tag[Chemist], Tag[SynthesisLab]),HAS_ALL_TAGS(Tag[LabManager]))
  • Intersect - Calculates the intersection between multiple lists of users, Examples:
  • INTERSECT(HAS_ANY_TAG(Tag[Chemists], Tag[SynthesisLab]),HAS_ALL_TAGS(Tag[Americas])

6. Formulas

Throughout the previous chapters, you had the chance to see different formula expressions in examples and explanations. Formulas have many uses, i.e., to calculate a value based on inputs, to filter users for privileges or even to write your own reports and bound tables. There are 4 types of formulas in Alchemy:

  1. Field value calculations
  2. Field or group visibility calculations
  3. Action conditions
  4. Filter Criterias

Before we see how to write formulas, we need to define the types of data to be used in formulas: 

  • String - Consists of letters, numbers and characters of any kind or alphabet. Depending on the length it can be regular (up to 255 characters) or long (more than 255 characters). It is represented with an expression inside quotation marks (e.g. 'Alchemy', 'New Product Development').
  • Number - Real, decimal numbers with the decimal dot "." for precision. Numbers are shown with the number of decimal places that is defined while creating the number field. However, the full number is saved in Alchemy and figures in calculations. For example, if the result is 4.318221, but the decimal places format is  2, the result will be shown as 4.32, however the number is saved in the database as the original number (4.318221)
  • Boolean - Logical values, true and false (written all lowercase). Yes/No and Checkbox fields are saved in the system as booleans.
  • Datetime - The Date and Time are saved in one format type in Alchemy. The different time and date formats can be defined in the Customization Portal (Chapter Date & Time).
  • User reference - A link to a User of the Alchemy User Portal. User Reference fields may be used as a variables (i.e., in the Assign To formulas).
  • Record References - They can be used as connections to access configuration and system fields for the records they are referenced to. These are record reference objects, that can either be accessed using expressions or configured records fields. 
  • Process References - They can be used as connections to access process system fields or records. These are process reference objects that can either be accessed using expressions for the current process or selected by the user in the user portal. All defined types of data can have a string representation, as well.

Elements of formula expressions can be:

  1. Variables
  2. Constants
  3. Operators
  4. Functions 

Possible elements of the formula expressions are graphically represented in Figure 6.1.


Figure 6.1 Possible elements of a formula

Figure 6.2 A formula that contains different elements

6.1 Variables

Variables are different fields inside record templates or system fields. System evaluates variables every time the calculation is triggered. Field identifiers are used as variable names in formulas, and field values are treated as its values.

Field types are treated as supported data types following the next pattern: 

  • Field type Alphanumeric, RichText, Link, field values are treated as a string
  • Field type Number field values are treated as a number
  • Field type Yes/No, Checkbox field values are treated as a boolean
  • Field type Date and Time field values are treated as a datetime
  • Field type Record field values are treated as Records
  • Field type Process field values are treated as Process
  • Field type User Reference field values are treated as User


To use fields from a record in the same process:

  • If a variable (the field value) is used in the formula placed in the same record where the formula is written, then you can define that variable in the formula using only the field identifier.  Example of the identifier of a field: 
  • VariableFieldIdentifier

6.1.1 Reference variables

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

Record References from the same Process

You can access all records created in the scope of the current process template using  Record[RecordTemplateIdentifier, RecordToBeAccessed] as your record reference:

  • Record[RecordTemplateIdentifier, RecordToBeAccessed].VariableFieldIdentifier

RecordsToBeAccessed can be an ordinal number or the keyword representing the order of the record, for example, "last." 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. If you skip it, Alchemy will search for and take into account the last created record.

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,RecordToBeAccessed ].VariableFieldIdentifier

Use Case for this was mentioned in chapter Repeatable Options (blue bubble).

Number of rows determined by number of samples

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 (Figure 3.41).

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.

Record References from other Processes

To use these fields from a record in another process you will need to configure a field where the users can select either the record reference directly, or a process reference from where you want to access the record. 

In case you configure the record field, it's identifier will be used as the record reference in your expressions:

RecordFieldIdentifier.VariableFieldIdentifier

In case you configure a process field, you must add it's identifier in from of the expressions with the Record[RecordIdentifier, RecordToBeAccessed]

ProcessField.Record[RecordIdentifier, RecordToBeAccessed].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.

Pull the data from a specific field in another process

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:

  1. Process field type with referenced process template: Register Product (in the User Portal the Lab Manager chooses the exact process (s)he wants from the dropdown list) Name: Choose Product Identifier: ChooseProduct
  2. 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: ChooseProduct.Record[ChemicalCharacteristics].pH

These fields are in the Sample process template, stage Request, record template Request Form as seen in Figure 3.31.


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. 

Pull the data from a specific field in another process

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:

  1. Process field type with referenced process template: Register Product (in the User Portal the Lab Manager chooses the exact process (s)he wants from the dropdown list) Name: Choose Product Identifier: ChooseProduct
  2. Record Field type with referenced record template: Chemical Characteristics (in the User Portal the Lab Manager chooses the exact record (s)he wants from the dropdown list) Name: Characteristic Type Identifier: CharacteristicType. In the Record Filter Criteria field write the expression Result.Process = ChooseProduct. Result is a keyword that is used for filtering, "Process" is a system field used for matching the chosen process above. ChooseProduct is an identifier of the first field where we have chosen a process.

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

 

Multiple Reference Connections

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.

6.1.2 System Data Variables

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.

Process Data

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. 

System data from the current process

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.

System data from another process

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:

  • Name: the name of the process
  • Template: name of the process template of the target process
  • Status: current status of the process, can be one of these four possible values: In Progress, Voided, On Hold, Completed
  • CurrentStage: currently active stages in the target process, formed as a comma-separated list of active stage names (i.e. Requirements, Lab Test, Sample Request). If the process is completed, on hold or voided, it will return the status.

System fields that could be placed in the Calculation Formula of the number field - their output is a number

  • Priority: current priority of the target process; if the process has no priority, it is set to 0. 
  • FinalDuration: Return process duration in days, hours, minutes and seconds after process is identified as status Completed or Voided. If the process is not completed, return an empty value. Duration is a number representing the number of milliseconds.TotalEffortSpent: total effort spent on the process, in hours. It is the sum of all the effort logged on the tasks linked to the process. Every time the effort spent is updated on the task linked to the process, this number is updated.

System fields that could be placed in the Calculation Formula of the datetime field - their output is date and time:

  • CreatedOn: date and time when the process was created 
  • CompletedOn: date and time when the process was completed; the default value is empty.

System fields that could be placed in the Calculation Formula of the user field - their output is the user's first and last name:

  • CreatedBy: the user that has created the process


Stage Run Data

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. 

  1. To get the information for the stages in the current process, the expression is:  Stage[StageIdentifier].SystemFieldIdentifier. If you don't specify the stage run after the StageIdentifier, the system will pull back information from the last run. Stage[StageIdentifier, 1].SystemFieldIdentifier will access the first run, Stage[StageIdentifier, 2].SystemFieldIdentifier will access the second run, etc.
  2. To get the information from another process, similar to the process data, first you need to select the process from which you would like to pull information (from a process reference field type), then create an appropriate field for the data and write in the calculation formula the expression: ProcessTypeFieldIdentifier.Stage[StageIdentifier].SystemFieldIdentifier

System fields that could be placed in the Calculation Formula of the alphanumeric field - their output is a string:

  • Name: name of the stage

System fields that could be placed in the Calculation Formula of the yes/no and checkbox fields, their output is a boolean:

  • Completed: current status of the stage run, returns true if completed

System fields that could be placed in the Calculation Formula of the number field - their output is a number:

  • Run: stage run number
  • TotalEffortSpent: total effort spent for the stage run, in hours. It is the sum of all the effort logged on the tasks linked to the stage run. Every time the effort spent is updated on the task linked to the stage run, this number is updated.

System fields that could be placed in the Calculation Formula of the datetime field - their output is date and time:

  • CreatedOn: date when the stage was created 
  • CompletedOn: date when the stage was completed, datetime data type

System fields that could be placed in the Calculation Formula of the user field - their output is user's first and last name:

  • CompletedBy : user that has completed the stage run 

Effort spent for Application Testing visible in Lab Work Review

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.


Record Data

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:

  • If you want the system data about the record from the current process, you will write Record[RecordTemplateIdentifier,RecordToBeAccessed].SystemFieldIdentifier in the Calculation Formula of your field. You can use this same syntax for any other field, not just the system field. If you don't specify the RecordToBeAccessed in terms of the order of the records, the system will pull back information from the last created record. 
  • If you want the system data about the record from another process, you need to create a record field type where the User will choose the exact record in the User Portal. In another  field where you want to pull the data (alphanumeric, number, datetime or user field, based on the type of data from system field that you want) you will write RecordTypeFieldIdentifier.SystemFieldIdentifier in Calculation Formula, where the  RecordTypeFieldIdentifier is the identifier of the record field type.

System fields that could be placed in the Calculation Formula of the alphanumeric field - their output is a string:

  • Name: name of the record 
  • Template: name of the record template of the target record
  • Status: record status, string data type, values can be Valid or Invalid

System field that could be placed in the Calculation Formula of the datetime field - its output is date and time:

  • CreatedOn: date and time when the record was created

System field that could be placed in the Calculation Formula of the user field - its output is the user's first and last name:

  • CreatedBy: the user that created the record

System field that could be placed in the Calculation Formula of the process field - its output is the process reference:

  • Process: Reference to process a record is linked to
  • Stage: Reference to Stage run a record is linked to

Record Formulation 2 completion date

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.

User Data

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:

  • FirstName: first name of the user 
  • LastName: last name of the user 
  • Email:  user's email
  • UserTags:  returns a list of tags the user is associated with

Email of the responsible person for the Technical Call

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.


Accessing Data - Summary

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:
  • Process.CreatedBy - Used to access the “created by” property of the current process
  • ProcessReferenceField.CreatedBy - Used to access the “created by” property of the process referenced in the  prior process reference field

This approach can be used for all the Process data.

  • Stage run data can be accessed as:
  • Stage[RequestReview].CreatedOn  - will access the last run of request review stage in the current process. In this example, the CreatedOn value of the last stage run is accessed. 
  • Stage[RequestReview, last].CreatedOn - can also be used

To access a specific stage run:

  • Stage[RequestReview, 1].CreatedOn - will access the first run of request review stage in the current process
  • Record data can be accessed as:
  • Stage[RequestReview].Record[Approval].CreatedOn - will access the last record based on Approval record template from the last stage Request Review run. In this example, the CreatedOn value of the last record created in the last stage run is accessed. 
  • Stage[RequestReview, last].Record[Approval, last] - can also be used
  • Stage[RequestReview].Record[Approval, 1].CreatedOn - will access the first record based on Approval record template from the last stage Request Review run. In this example, the CreatedOn value of the first record created in the last stage run is accessed.
  • Record[Approval, 1].CreatedOn - will access the first record of type Approval in the whole process
  • Record[Approval, last].CreatedOn - will access the last record of type Approval in the whole process

Accessing the record data from the current process

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.

6.2 Constants

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:

  • String - Single quotes (' ') are used to indicate the string constant. Example: 'abc' 'a10' '154.3$'
  • Number - regular numbers can be used. Example: 10, 7.5, -4.0000
  • Boolean - written as true, false

Note that other data types (mainly references) cannot be used as constants, as such data always depends on the context in the user portal. 

6.3 Result and Item

Result and Item are keywords that are used for filter expressions and expressions in repeatable groups respectively. Result keyword is used to define filter criteria (Result = [filter]). Item keyword is used to access the specific item from the result set 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.

6.3.1 Result

Expressions with the keyword Result are used in the Filter Criteria field in the advanced settings. Filter Criteria field is available for the referenced fields: Process, Record and User, as well as for the repeatable groups 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, Result allows this selection to be filtered according to a value in a specific field or system data. The Result keyword acts like a record variable, used to refer to the "raw data" that is to be filtered.

In general, the filter expressions use the following syntax:

Result.Parameter = Criteria

The Result refers to the reference variable (Record, Process or User) that you are filtering, the Parameter is optional, and may be used as any system or configured field as explained in the variables chapter. The Criteria is another variable or constant that you want satisfied in order to be able to select the record. Some commonly used examples are:

  • Result.Status - can be used in the filter criteria to access the system data, such as the status of the record.
  • Result.Process.Status - may also be used to add another dimension to the data. For example to filter records, based on the status of the process they are created in.

Filter the Formulation records according to status

You may need to reference Formulation 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 (record template). 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 Formulation Records created in the ongoing Lab Work Processes.

Using the Result.Process in filter criteria

The record template Formulation is used in multiple processes, not only in Lab Work (used also in NPD, ARM). If you want to reference only Formulations from the current process (Lab Work in this case), you need to put a result formula in the Filter Criteria of the record reference field you have made. You need to write in the Filter Criteria field: Result.Process = Process. With this you will be sure that the records selection will only be from the current process.


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

  • Result.AlphanumericField = 'String Constant' - can be used to filter (mainly) records based on an alphanumeric field. The alphanumeric field is usually a dropdown to avoid errors of user entry.

Filter records based on alphanumeric fields

In the Lab Work process, when adding Material records in the Formulation step, we could add a field to select the supplier for that record. The Supplier field can be configured as a record field, referencing the Company Record Template. We want the user to be able to select only the Companies that have the "Company Status" set as "Supplier", The record filer criteria expression should be:

Result.CompanyStatus = 'Supplier'

Where the CompanyStatus is the identifier of the "Company Status" field in the company record, that has a dropdown selection (predefined values) as: 'Competitor', 'Customer' or 'Supplier'.

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. 

Show only the list of contacts from a particular company

Sales person in the Request Form should choose Company and Contact for that request. After choosing the Company from the dropdown it is expected that under Contacts you can choose only among ones that are employed in the chosen Company. 

Both Company (Identifier: RequestCompany) and Contact (Identifier: RequestContact) are Record field types. While creating a Contact field you will choose record Contact in the Referenced Record Template. In order to filter down companies you will set the Filter Criteria with: Result.Company = RequestCompany. The keyword Result is always used to filter down the options for the dropdown list. Company is the identifier of the record type field in the record template Contact that system needs to know in order to show only Contacts that have that field equals with RequestCompany field from the current record template.

6.3.2 Item

Item keyword is used as a record variable, to access a specific item from the result set of fields in repeatable rows or columns. Item is used in 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 that is determined by the NPD Requirements record reference. In this case, the Item keyword, will act as a record reference variable, for the NPD Requirements record. In that table (the repeatable row group) we have three fields:

  • NPDName: Alphanumeric field, where we want to write the name of the NPD. This value is written in the field Name, inside the NPD Requirements record.
  • Calculation Item.Name
  • ProjectAssignedTo: User type field. The value is copied from the field AssignedTo in the NPD Requirements.
  • Calculation: Item.AssignedTo
  • Details: Alphanumeric field. The value is copied from the Details field in the NPD Requirements record.
  • Calculation: Item.Details

A detailed example is explained in the Chapter How to make a bound table in Alchemy?

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 groups as explained above. Some further examples are:

  • Item.Process - to create a process reference
  • Item.Process.Status - string variable, the status of the process where the  record is created in
  • Item.CreatedBy: User who created the record


6.4 Operators and Functions 

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.


6.4.1 Logical operators

  • AND - performs logical conjunction of two operands. Returns true if both left and right operands are true, false otherwise.
  • Keyword: AND
  • Supported operand types: boolean 
  • Output type: boolean
  • Examples: 
  • a AND b
  • a AND b NOT SET
  • NOT a AND b

Transition condition with logical operator AND

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
  • Keyword: OR
  • Supported operand types: boolean 
  • Output type: boolean
  • Examples:
  • a OR b
  • a OR b NOT SET
  • NOT a OR b

Logical Operator OR evaluation

When using the logical operator OR, if the left operand is true, right operand is not evaluated. 

  • NOT - performs logical negation of one operand. Returns true if the operand is false, false otherwise.
  • Keyword: NOT
  • Supported operand types: boolean 
  • Output type: boolean
  • Example:
  • NOT a


6.4.2 Field Operators

  • 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.
  • Keyword: IN
  • Supported operand type: boolean, number, string, datetime, process reference, user reference, stage reference
  • Output type: boolean

Visibility Condition based on the Processing Equipment

In the Formulation stage of Lab Work, Chemist can choose his (her) Processing Equipment (alphanumeric field type with the identifier ProcessingEquipment) from a dropdown - Low Speed Mixer, High Speed Mixer, Mill or Mini Mill. Chemist can choose more than one item from the dropdown. Based on that choice different fields for processing details will open in the User Portal. 

In order to achieve that you will use IN operator in the Field Visibility Condition of processing details fields. In the fields that you would like to be visible in the User Portal when Low Speed Mixer is chosen you will write in the Field Visibility Condition: 'Low Speed Mixer' IN ProcessingEquipment. You will do the same thing for the fields that should be visible when 'Mill' is chosen ('Mill' IN ProcessingEquipment) or any other item from the dropdown.

  • 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
  • Keyword: NOT IN
  • Supported operand type: boolean, number, string, datetime, process reference, user reference
  • Output type: boolean

Calculation Formula based on Status of the Formulation

In the Formulation stage there is a list of formulations that need 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 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 operator 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.
  • Keyword: IS SET
  • Supported operand type: all
  • Output type: boolean

Field Visibility Condition based on the is the Opportunity Status set or not

Sales can add Opportunity record in the Request stage in the Lab Work. In the Opportunity record there is an alphanumeric field named Opportunity Status (identifier: OpportunityStatus) with predefined values Open and Closed. When Sales person choose one of two options in that field, rich text type field named Reason (identifier: Reason) should appear.

You will achieve that by typing expression: OpportunityStatus IS SET in the Field Visibility Condition of the field named Reason. 

  • 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.
  • Keyword: NOT SET
  • Supported operand type: all
  • Output type: boolean
  • Examples:
  • FieldIdentifier NOT SET 
  • 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.
  • Keyword: IFS
  • Supported operand type: all
  • Output type: any
  • 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)

Calculation formula for Score in the Opportunity

In the Opportunity record, Score for that opportunity is calculated. It is calculated based on the field named Opportunity Value (type: Number, identifier: OpportunityValue), field named Number of Lab Work Requests (type: Number, identifier:NumLabWorkRequests) , and field named Margin (type: alphanumeric with predefined values - Low, Medium and High, identifier: Margin). When Sales person fill in those fields, field named Score (type: Number, identifier: Score) will be calculated automatically. 

You will achieve that by typing expression: ((IFS(OpportunityValue < 500000, OpportunityValue/500000, true, 5) * 5) * 0.33) + (IFS(Margin = 'Low', 1, Margin = 'Medium', 3, Margin = 'High', 5) * 0.33) + (IFS(NumLabWorkRequests < 5, NumLabWorkRequests, true, 5) * 0.33) in the Calculation Formula of the field named Score. Comparison and Mathematical operators will be explained in details below.


6.4.3 Comparison Operators

  • 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).
  • Keyword: >
  • Supported operand type: number
  • Output type: boolean
  • 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.
  • Keyword: >=
  • Supported operand type: number
  • Output type: boolean
  • 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.
  • Keyword: <
  • Supported operand type: number
  • Output type: boolean
  • 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.
  • Keyword: <=
  • Supported operand type: number
  • Output type: boolean
  • Examples:
  • a <= b
  • Equal - Compares two operands for equality. Returns true if the left operand is equal to the right operand, false otherwise.
  • Keyword: =
  • Supported operand type: string, number, boolean, datetime, user reference
  • 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 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 compared (Null values - no value present) comparison returns true.
  • Comparison between two operands of different types always returns false, validation error is generated.
  • Output type: boolean 
  • Example:
  • a = b
  • Not Equal - compares two operands for inequality. Works like the exact opposite of equals operator.
  • Keyword: ! =
  • Supported operand type: string, number, boolean, datetime, process reference, user reference, file, link
  • Output type: boolean 
  • Example:
  • a != b

Adjusting Filter Criteria using the Status as a System Data

As mentioned in the process Sample Lab Manager needs to pull some data from a Register Product process. When (S)he clicks on the field Choose Product in the User Portal, (s)he needs to see all processes (products) except the ones with the status "Void". 

In order to make that possible you will write following expression in the Filter Criteria of the field named Choose Product (type: process, identifier: ChooseProduct): ChooseProduct.Status != 'Void'.

6.4.4 Mathematical Operators

  • Addition/Concatenation - Performs numeric addition or string concatenation, depending on operand type.
  • Keyword: +
  • Supported operand type: string, number, datetime, user reference, link. Process and  record reference can be used as a way to have access to some field that you want to add, through the dotting.
  • 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.

Advice - Use empty string in order to make space between concatenated fields

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 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 results 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.
  • Output type: string, number
  • Examples:
  • a + b,
  • a + ' : ' + b
  • RecordIdentifier.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.
  • Keyword: -
  • Supported operand type: number
  • Output type: number
  • Examples: 
  • a - b
  • 1 - a
  • 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.
  • Keyword: *
  • Supported operand type: number
  • Output type: number
  • 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.
  • Keyword: /
  • Supported operand type: number
  • Output type: number
  • Examples:
  • a / b, 
  • a / 3
  • Negation - Changes the sign of the number. Transfers it from negative to positive or vice versa. 
  • Keyword: #
  • Supported operand type: number
  • Output type: number
  • Examples: 
  • #n


6.5 Functions

Functions are expressions in Alchemy that can use one or more inputs, given in brackets (), and perform complex calculations before returning the output. There are certain functions that are defined in Alchemy, which are described below.

  • 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.
  • Keyword: SQRT
  • Supported operand type: number
  • Output type: number
  • 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).
  • Keyword: POW
  • Supported operand type: number
  • Output type: number
  • 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).
  • Keyword: ABS
  • Supported operand type: number
  • Output type: number
  • 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.
  • Keyword: SUM
  • Supported operand type: number
  • Output type: number
  • Examples:
  • SUM(15),
  • SUM(n)


  • LOG - calculates the logarithm (base 10) of the value in argument.
  • Keyword: LOG
  • Supported operand type: Number
  • Output type: Number
  • 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.
  • Keyword: COUNT
  • Supported operand type: all
  • Output type: number
  • 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 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.

  • Keyword: ROW_COUNT
  • Supported operand type: all
  • Output type: number
  • 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).
  • Keyword: AVERAGE
  • Supported operand type: number
  • Output type: number
  • 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.
  • Keyword: TODAY
  • Supported operand type: number
  • Output type: datetime
  • Examples:
  • TODAY,
  • TODAY(2),
  • TODAY(2, 6),
  • TODAY(2, 0, -1),
  • TODAY(-14, 0, 0)


  • Date Format - Function that returns a text representation of a date based on the supplied format.
  • Two operands are expected, the Date as a and the Date and Time variable, and the Format, as a string variable
  • The format is provided as a string constant, as any of the formats available as explained in the section 3.2.5 Field Types, Date and Time Field.
  • Keyword: DATE_FORMAT(Date, Format)
  • Supported operand type: Date and Time as first operand, string as second operand
  • Output type: string
  • Examples:
  • DATE_FORMAT(ProjectStartDate, 'YY-MM-DD')
  • DATE_FORMAT(Process.CreatedOn, 'EEEE, MMMM d, y')

Date of the technical call

In the Technical Call stage in the Lab Work Salesperson needs to write down the date when the call happened. It is handy that by default field Date is filled with today's date. 

You can achieve that by writing TODAY in the Calculation Formula of the field named Date (type: Datetime, identifier: Date). You will check Editable checkbox option, so Salesperson can change that date in the User Portal.


  • 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.
  • Keyword: ROUND
  • Supported operand type: number
  • Output type: number
  • 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.
  • Keyword: TRANSITION_FROM
  • Supported operand type: stage reference
  • Output type: boolean
  • Example:
  • TRANSITION_FROM(Stage[Requirements])

Request Review task subject based on TRANSITION_FROM

Request Review in the Lab Work can be done after Request stage or after Technical Call stage.  Lab Manager needs to get the task for reviewing with different subject. 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.
  • Keyword: HAS_ANY_TAG
  • Supported operand type: tag
  • Output type: list of users
  • Example:
  • HAS_ANY_TAG(Tag[SalesDirector], Tag[President])

Using tag expressions for assign privileges

In the Alchemy Laboratory, Dustin is a lab manager (has the LabManager tag). Devlin, Daisy and Lisa 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 Dustin. If we want to include him as well, we need to expand the formula: HAS_ANY_TAG(Tag[Chemist], Tag[LabManager])

  • 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.
  • Keyword: HAS_ALL_TAGS
  • Supported operand type: tag
  • Output type: list of users
  • Example:
  • HAS_ALL_TAGS(Tag[SalesDirector], Tag[VPMarketing])

Assigning View and Edit privilege for Request Review using conditions

You need to assign view and edit privileges in the Request Review stage to certain workgroups, based on what location is selected in the Request. In order to do that, each tag privilege should be defined separately. If location 'New York Plant' is selected - person who has tags "New York" and "LabManager" will get the assignment (Figure 2.19). If location 'Tokyo Plant' is selected - person who has tags "Tokyo" and "LabManager" will get the assignment. You will achieve this by creating two separate privileges, by defining a condition in "When" field and by choosing appropriate tag in the "To:" field. When the location selected is 'New York Plant' you will write Record[Request].SelectPlant = 'New York Plant', To HAS_ALL_TAGS(Tag[LabManager], Tag[NewYork]), select Can View and Edit. You will do the same for Tokyo Plant. 


  • INTERSECT - Calculates the intersection between multiple lists of the same type. Only the values that are found in all the supplied lists are returned.
  • Keyword: INTERSECT
  • Supported operand type: all, but all must be of the same type
  • Output type: list of results of the same type as provided parameters
  • 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.
  • Keyword: UNION
  • Supported operand type: all, but all must be of the same type
  • Output type: list of results of the same type as provided parameters
  • 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.
  • Keyword: CREATED_BY
  • Supported operand type: list of users
  • Output type: boolean
  • Example:
  • CREATED_BY(HAS_ANY_TAG(Tag[SalesDirector], Tag[LabManager])) 

Assign task based on who created Lab Work process

Lab Work can be created by Salesperson from New York or from Tokyo. In case that is created by the person from New York it is handled by the plant in New York. 

You need to add action Create Task for Request Review after Request stage when process is created by salesperson from New York. After adding action Create Task in the When (as mentioned above) you will write TRANSITION_FROM(Stage[Request]), in the Assign To you will write HAS_ALL_TAGS(Tag[LabManager],Tag[NewYork]) and the Task Subject you will fill in with the 'Review the Lab Work Request for ' + Process.Name.You will add other action in the sam way for Tokyo.


  • 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. Max 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:
  • N - for single digit
  • A - for single letter uppercase
  • a - for single letter lowercase
  • YYYY - for the current year represented as 4 digits (values from 2019 )
  • MM - for the current month represented as 2 digits (values from 1 -12)
  • MMM - for the current month represented as 3 chars (Jan, Feb, Mar, etc.)
  • DD - for the current date represented as 2 digits (values from 1 - 31)
  • hh - for the current hours represented as 2 digits (values from 00 to 23)
  • mm - for the current minutes represented as 2 digits (values from 1 to 59)
  • ss - for the current seconds represented as 2 digits (values from 1 to 59)
  • characters '-', '/', '.', '_', whitespaces,  and ':' can be used as delimiter characters inside the pattern. They are just there to make the pattern more readable, but they are not breaking the 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. 

  • Supported operand type: string
  • Output type: string
  • Examples:
  • 'Sample ' + PATTERN('ANN'),
  • 'Shipment ' + PATTERN('YYYY-MM-DD-NN').

Lab Work Title in the User Portal

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-2019-09-001 (for the first process in september). The following one will be named LW-2019-09-002 etc. If by the end of the September there are 999 Lab Works, counting will start again from 001. The first Lab Work in October will be titled as LW-2019-10-001.

You may have only one PATTERN formula in one expression

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. 

7. Design Templates

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:

  • Make a list of all users where you will enter email and tags
  • Define process privileges

In the Stage 1 sheet you can define:

  • General info about that stage (Name, Identifier, Duration and Effort Spent Required)
  •  All records and actions needed for that stage
  • Stage privileges

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!

Appendix

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.

Figure 1. Sample
Figure 2. Lab Work 


Figure 3. Register Product Process Template

Figure 4. Business Initiative

Figure 5. New Product Development