General rule concepts

• 1: Adding Conditions
• 2: Multiple rules
• 3: Expression builder
• 4: Success/Error Mapping

1 - Adding Conditions

Conditions are a key component of Kianda rules. They are the triggers that result in fully dynamic forms. Conditions enable you to create natural language conditions when rules should be triggered.

The Conditions button is found within all rules as well as dashboard widgets. Conditions can also be set when setting data source security levels for B2B portals.

Conditions add an important level of interactivity, creating dynamic pathways within a process. These pathways could result from user interaction or from other events that happen.

Conditions work on the ‘if…then’ principle: ‘if’ the condition exists ‘then’ an action happens, and where applicable, if the condition does not exist, then another action can happen. You can use these principles as steps to implementing conditions:

1. Create the condition(s)
2. Create the action(s) that will be applied as a result of the first condition being in place.
3. Where applicable, create the otherwise action(s) based on other conditions being in place.

Create the condition

1. To create conditions, first choose the process element you want the condition to apply to – such as a form, set of forms, a field/control or set of fields. This could also be a set of common fields associated with all process instances, such as Process ID, Status or Modified by, see image below.

   

2. Next, depending on whether the rule is applied to text-based fields, date fields or user picker fields, choose from 13 text operators, 25 date operators and one additional user picker operator, as shown in the image below.

3. Then choose a value, this could be typed in text, number(s), date(s), form(s) or field(s).

Condition elements

In the case of multiple conditions, you can use And or Or to create a group of compound conditions:

The result is a flexible process workflow that will result in desired actions based on any number of conditions.

Rule action(s) – example Hide or Disable rule

To create actions and where applicable, otherwise actions, the action will depend on the rule that is chosen. All Kianda rules use a natural language structure to make it is easy to apply actions. For example, for the Workflow rule, Hide or Disable, you can choose forms and fields from your process and then apply seven possible actions (as shown below).

Action elements for Hide or Disable

The actions within Hide or disable are:

• Hide will hide a process element (forms or fields) from view.
• Show will show the element.
• Disable blocks a user from editing an element.
• Enable allows a user to add a value to an element.
• Toggle visible will toggle between showing an element or not, based on subsequent clicks of a field that the rule is applied to.
• Toggle enable will toggle between allowing an element to be edited or not, based on subsequent clicks of a field that the rule is applied to.
• Hide and clear will allow you to hide a process element and clear the details. For example, if a toggle button has this rule applied, with an otherwise action of show on a textbox, then if one value is chosen on the toggle button, the user is allowed enter details into the textbox. The otherwise action is that the field is hidden and cleared of data, so that no data can be retrieved. This might be useful, for example, when sensitive information is used, like a social security number on a form.

Note: You can use rules to create actions without conditions too. In this case the rule will simply execute, for example when a form or field is clicked on.

What’s next

Depending on how the rule is applied, for example to a Submit button, the rule order is important to consider, see Multiple rules.

To find out more about rule implementation, go to the main Rules page and then click on the links to the different rule categories.

2 - Multiple rules

Introduction

When working with rules in forms, a key principle to consider is rule order. Rule order is important if there are multiple rules attached to an item like a button or form field to determine the sequence of rule execution. As a form designer, you can change the order of execution to suit your specific process design.

Remember you can assign rules at:

• Process level - onload rules that execute when a new process instance is initiated.

  

• Form level - onload rules that execute when a form is submitted.

  

• Button/field level - rules attached to buttons or fields within forms, or at the end of a form, for example a Submit button. An example of rule order is given at this level in the section below Rule order example.

Rules are typically synchronously executed in Kianda, so for example when using a Start a process rule, when the rule is executed first any mappings from a secondary/target process are mapped into a primary process, and from there if there are any rules to trigger on the secondary/target process those are executed, but a rule will only execute when the previous rule has completed. This is different to asynchronous execution where the system will execute rules without waiting for the previous rule execution to finish. Within time defined rules, like Start a process and Schedule a rule there is an option to choose between synchronous/in-series or asynchronous/in-parallel where the latter may be useful for rules without dependency.

Rule order example

For example, you may want a process to send automated emails to a safety manager, where the email includes submitted form data. In this case a Send email rule could be attached to a form Submit button so an email is sent once the button is clicked. This will result in an automated email to a designated person. To generate a report of the completed form, you can use the Generate word document rule triggered again when the Submit button is clicked. In this example the Generate word document rule has to be executed before the Send email rule, so that the Word document can be generated and then attached to the email.

The rule order consideration is therefore particularly important when rules are dependent on each other - where the output of one rule is the input of another rule.

Changing the rule order of multiple rules

In the example below we will look at changing the rule order of a Send email rule attached to a Submit button. The Submit, Save and Close buttons by default already have Submit, Save and Close process rules attached, in order to allow form shutdown.

To change rule order, when the rule is created:

1. Click on the item that has multiple rules attached, for example a Submit button. Remember by default Submit buttons in forms will have ‘form shutdown’ rules, namely Submit, Save and Close.
2. Click on Rules in the right-hand pane, drag the Send email rule to the top of the list by clicking on the rule and drag it to the top of the list, before Submit, Save and Close rules.

The video below shows an example of a Send email rule being created and saved. The rule is attached to the Submit button. Once the rule is created, by default the new rule goes to the bottom of the list of rules. To move the rule, simply click on it and drag it to where you wish to place it. In this example we want the email sent before any of the shutdown processes like Submit or Save, but after a Generate Inspection rule, so the output from that rule can be used in the Send email rule.

What’s next

To find out more about rule implementation, go to the main Rules page and then click on the links to the different rule categories.

3 - Expression builder

Introduction

Expressions allow you to put together form identifiers (form field IDs) and constants with operators and functions to return a dynamic value that can be used in various places – for example, in a form or field rule to automate processes.

Expressions

For example, expressions could be used in the body of an automated email sent using the Send email rule, as shown here:

Expression example

In the example above, [RequesterName] and [category] are identifiers, that are unique IDs for form fields. ProcessLink() is a function that will return a link to that process instance. Using the expressions above in an email will mean that every time an instance of the process runs, the values will be presented in an automated email, creating greater efficiencies and personalising the email for the recipient.

Getting started with expressions – example Email body text

Expressions are recognisable in Kianda from the Expressions button found in Edit rule dialog boxes and other menu items, such as enabling quick actions for processes and number fields.

Within rules, expressions can be created using the Expression builder where you can Add field to an expression or use the handy Reference guide to get a list of commonly used functions.

Expression builder

Let’s look at an example of using an expression in the Body section of an email being sent using the Send email rule:

1. First, add a Send email rule to a form or forms, field or fields by selecting Add a rule > Communications> Send email from the left-side pane.

2. Type in any text that you want in the email Body and position your cursor where you want to add the expression.

   

3. On the right of the Body section of the email, click on the Expressions button .

4. The Expression builder dialog box appears.

5. Click on the blank box under Add field to expression and find the field you want to reference in your email, for example, a text box with a name ‘EmployeeName’.

6. Click Add to expression. The result is that the field appears in the Expression box.

   

7. Click OK to add the expression to the email body text, or click on Close to exit the dialog box without making changes.

8. To add additional field expressions, click on the Expressions button again, under Add field to expression, click on X beside the field name to clear the expression box and then search for the desired field from a form.

9. To add a function, click on Reference and copy the function into the body of the email. A list of references are available below.

Expression functions

All JavaScript expressions and functions can be used in the Expression builder to create the impact you want, see Javascript expressions for more details.

In addition to defining your own expressions there is a set list of expressions found under References, see table below for meaning.

Expression	Function
+, -, /, *	Performs one of the basic mathematical operations: add, subtract, divide or multiply.
Sum(arg1, arg2, …)	Returns the sum of the arguments listed between the parentheses.
Date(arg1)	Converts the argument into a date.
DateAdd(dateArg, day, month, year, hour, min)	Adds time to a given date. The date is stored in dateArg and the time to be added is stored in the day, month, year, hour and min arguments.
Status()	Returns the status of the current process.
ProcessID()	Returns the ID of the current process.
FormOwner(formName)	Returns the form owner(s) for the given form.
FormCompleted(formName)	Returns the date completed for the given form.
Pad(value, size, symbol)	Adds left padding to the value with the symbol provided.
QueryString(parameter)	Returns the URL query string for the given parameter (or an empty string if undefined).
IsOnline()	Returns “yes” or “no” depending on the status of the online connection.
ProcessLink()	Returns the HTML link to the current process The link text can be added between the parantheses e.g. ProcessLink(“click here”). This expression is for use in emails and rich text fields.
Digest()	Returns a summary of changes to fields in the current process. A table will be given with the original and new values.
Digest(‘fieldName1’,‘fieldName2’)	Returns a summary of the changes for the given fields. See note below.
GetFieldText(‘fieldName’)	Returns the text in the given field. See note below.
GetFieldValue(‘fieldName’)	Returns the value in the given field. See note below.

Note: In the case of the last three expressions, you should select a field which contains data. If you give the name of a button field for example, then no data will be returned.

What’s next

To find out more about rule implementation, go to the main Rules page and then click on the links to the different rule categories.

To see how expressions are used in controls such as Number fields, go to Number control.

To learn more about how to use JavaScript expressions in expression builder go to Javascript expressions for more details.

4 - Success/Error Mapping

Introduction

Success and Error mapping is used to denote the success or failure of certain rules being executed where data is being transferred or a rule is connected to a data connector. As a user with an administrator or designer role, you can use Kianda Designer to populate fields within the Kianda form, using the Edit rule dialog box to set parameters for success and error mapping.

When to use

Success and Error mapping should be with rule execution, displaying values that you want for rule execution success or failure.

You can use mapping with the following rules:

• Data rules > Find items
• Data rules > Create item
• Data rules > Update item
• Data rules > Delete item
• All SharePoint rules, except Get attachments and Create anonymous link

How to use

1. Select the field that will have the rule attached, for example a button at the end of a form, or a field within a form.

2. Click on Add a rule in the left-hand pane and select one of the rules that uses mapping as shown in the When to use list above, for example the SharePoint rule called Create list, used to create a list in SharePoint dynamically using Kianda form data.

   

3. In the Edit rule dialog box, give the rule a Title.

4. If you want to add conditions for the rule, click on the Edit conditions button to create conditions for the rule, see Conditions for more details.

5. Under Action, click on the field Select a SharePoint data source from the drop-down list.

   

6. Fill out any additional fields as necessary, for example to create a list the following fields must be completed:

   • List template - choose from a list of SharePoint list types

   • List name field - choose a form field that will be used the create a name for the list in SharePoint

   • List url field - choose a form field that will be used in the creation of a URL within SharePoint

   • List description field - choose a form field that describes what the list is about

   • Quick Launch menu - options are Yes or No. Choosing Yes allows the created list to be displayed in the Quick Launch menu, containing a link to the list.

7. To add success mapping, click on On success mapping and click on the Add mapping button. See On Success Mapping for more details.

8. For On error mapping and click on the Add mapping button. See On Error Mapping for more details.

9. you simply need to select the field within the form which will store the error message

10. When you are finished editing the dialog box, click on OK or click on Close at any time to exit the dialog box.

On Success Mapping

Success mapping is a concept of populating your form fields with data that is retrieved from a datasource using a data connector, to learn more about data connectors go to Data connectors. This retrieved data from the datasource is known as a response. Using this response data, you can populate a field within your form, for example you can retrieve a file which is stored in your SharePoint or Dropbox datasource and populate the retrieved file into a File field. This will give you the ability to access the retrieved file in your process.

All data connectors within Kianda may have different response data that can be used to populate fields in a form. You can use the Success mapping in the rules mentioned in the When to use section. Take one of the SharePoint rules Create a site as an example. When all information is filled out in the rule, in the On success mapping section you can assess the data object (response) called Site properties. From the Site properties data object you can access three different pieces of data; Site Name, Site Id and Site URL. You can map (populate) those piece of data into fields in your form by selecting a field in the Form field section:

• Form field - this field allows you to select a field in your form to store the value from the datasource.

• Data source field or text - this field allows you to select which piece of data your want to retrieve from the datasource, and store it in a form field.

• Add mapping - Click on the Add mapping to add more fields for mapping results from the datasource to form fields.

• Bin/Trash - Click on the Bin/Trash button to delete a mapping.

On Error Mapping

Error mapping is a concept of populating a form field in your Kianda process when using the rules from the When to use section. When using those rules, you get presented with the ability to map an error when there is an issue as the rule is executing, for example incorrectly filling out a parameter. It is useful to know the details of the error message that comes from the datasource your are connecting with. To see the error message, you need to create a separate Text box field in your form and map the error to that field. Open the On error mapping section and add a mapping by clicking on Add mapping button:

• In the Form field, select a form field which will store the error message in your Kianda form.

• In the Error message or text field, enter an error message that you want to appear in the event of errors or click on the text box and select the Error message option to use a system generated error indicating what has gone wrong when the rule executed.

• Click on the Add mapping button to add further mappings.

• Click on the Bin/Trash button to delete a mapping.

What’s next

To find out more about rule implementation, go to the main Rules page and then click on the links to the different rule categories.