# Process template

Process template is defined in format NEON.

Template consist of several basic elements:

  • process
  • acl
  • steps

And from several optional elements:

  • layout
  • variables
  • events

# Process

Process allows define name of process (name) and description (description).

  • name (required) - name of process template
  • version (required) - for process architects to keep track of template states. Only accepts <digit>.<digit>.<digit> or <digit>.<digit>.<digit>-<a-zA-Z0-9_> eg. (0.0.1, 1.0.2-concept)
  • description (optional) - description of process template
process:
	name: New connection
	version: 1.4.2
	description: '''
		# New connection

		- item 1
		- item 2
	'''
1
2
3
4
5
6
7
8
9

# ACL

Process ACL are defined by subsection roles in which are users assigned to individual roles.

Users are selected through their unique identifier (ID) or user group.

# User roles

acl:
	roles:
		technician: [1,2,3,4,5]
		accountant: [7,8,9]
1
2
3
4

# Magic roles

Magic roles are prefixed with @ and are usually defined by system.

@creator

Listed users in @creator have the rights to start the process, no-one else. Except the admin from administration.

acl:
	roles:
		@creator: [1,2,3]
1
2
3

@supervisor

Listed users in @supervisor have the rights to supervise (control) given process. There's a special tab called "Supervisor" on the process detail.

acl:
	roles:
		@supervisor: [1,2,3]
1
2
3

# User groups

User groups aggregate users in predefined virtual groups. Useful when you don't want to modify process template all the time.

acl:
	roles:
		@creator: [&admins]
		technicians: [1,2,&viptechnicians]
1
2
3
4

Only users in user group admins can create the process. In resolver role technicians are users (1,2) and all users in user group viptechnicians.

# Tags

Registration of tags that can be used in this process.

  • title (required) - user-friendly title
  • color (required) - css color of a tag (green, #F2F2F2)
  • description (optional) - user-friendly description of tag
  • default (optional) - if set to true tag will be attached on process start. Default value is false.
tags:
	vip:
		title: Top client
		color: green
		description: Take extra care of this client
		default: false
1
2
3
4
5
6

# Extra

Process scoped snippets can be defined in section extra. Snippets can be defined in name => template manner. If both process scoped and general snippets exists with same name, process scoped snippet is used.

extra:
	snippets:
		snippetName: 'Good day {$name}'
		snippet2Name: 'Good evening {$name}'
1
2
3
4

In lattenizer snippets can be used this way:

{include 'snippetName.snippet', name=>'Adam'}
1

# Steps

Step is basic building stone of processing.

It consist of:

  • title (required) - user-friendly title
  • type (optional) - START / MANUAL (default) / AUTO / ASYNC / END / END_USER
  • expiration (required) - expiration of step
  • acl (required) - ACL definition for step
    • resolver (required) - who will resolver the step
      • You can use in this role:
        1. Reference role name, e.q. technician or @creator.
    • reader (optional) - who has read access to the step (cannot perform next)
      • You can use in this role:
        1. Re-use existing role reference, e.q. technician or @creator.
        2. Reference user directly, e.q. 10, 15, 20.
        3. Reference application-based user group, e.q. &admins, &viptechnicians, etc.
  • transitions (required) - transitions to subsequent steps (at least one must be defined if step is not ending)
  • layout (optional) - panels layout for specific step

Take a look:

steps:
	sample1:
		title: Sample step 1
		type: START / MANUAL / AUTO / ASYNC / END / END_USER / SUMMARY
		expiration: +1 hour
		acl:
			resolver: accountant
			reader: [technician, @creator, &admins, 10]
		transitions:
			step1:
				expression: "connection.price > 1000"

			step2:
				expression: "connection.price <= 1000"

		layout:
			# ↓ see section layout ↓
		extra:
			# ↓ see section extra ↓
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Each process template must have one START step and at least one END or END_USER step. SUMMARY step is created automatically, but you can override it.

# Types

  • START - Each process need its first step to by properly started.
  • MANUAL - Manual (most often) step. It requires user interaction.
  • AUTO - Step which is done automatically after user interaction. It is not running in background.
  • ASYNC - Step which is done automatically in background. This step need to be triggered, e.g. by cron.
  • END - Step is automatically completed if it get into this step. User interaction is not required,
  • END_USER - Step requires user interaction to be completed.
  • SUMMARY - Displayed if process is completed.

# AUTO

This step is resolved automatically, without user interaction. It's resolved in the same request to server as previous step, so don't use it for heavy tasks. We're suggesting to use it for simple automatization.

# ASYNC

This step is resolved automatically, without user interaction. It's resolved in the background process, so you can use it for heavy (time) tasks. Cron is scheduling every 10 minutes to resolve all waiting async steps.

# SUMMARY

Summary step is special. It's created by default under the name summary. You can override it, but name your step summary. otherwise it won't work.

steps:
	summary:
		title: "Order summary"
		type: SUMMARY
		expiration: now
		acl:
			# Resolver is useless, but required
			resolver: @creator
			# Who can display the summary step
			# Creator and some other users
			reader: [@creator, 2, 3, 10]
		layout:
			# ↓ see section layout ↓
1
2
3
4
5
6
7
8
9
10
11
12
13

# Transitions

For evaluation of transition from step to step is used LPL - Lotus Programming Language.

During evaluation of conditions is required that only one condition is true. System otherwise do not allow transition to next step.

# Examples

There is at least 1 user in technicians role:

!empty(_process.roles['technicians'])

There is at least 1 file uploaded in invoices variable:

!empty(invoices)

# Extra

Each step has a configuration option extra to store additional informations.

Messages

You can override default messages if system try to move process to next step. For each step differently.

steps:
	sample1:
		extra:
			messages:
				next_failure: "Have you fill all forms? Are you sure?"
				next_success: "Everything OK, see you buddy!"
1
2
3
4
5
6

Features

Feature toggles are a powerful technique, allowing modify system behavior.

Current toggles:

  • ajax - Each panel saves his state by himself without redirecting or refreshing page. Previously called saver. The next panel is a main trigger to perform save operation to all panels, a.k.a one button to save it all.

    steps:
    	sample1:
    		extra:
    			features:
    				ajax: true
    
    1
    2
    3
    4
    5

# Layout

Key layout defines layout of panels for process or for specific step.

The whole panel ecosystem is based on library Panelus, take a look.

Process layout

layout:
	# Extending layout
	extends: default

	# Sections with panels
	sections:
		{...definition}
1
2
3
4
5
6
7

Step layout

steps:
	sample1:
		title: Sample step #1
		layout:
			# Extending layout
			extends: minimal

			# Don't extends from any layout,
			# don't use it with extends
			exclusive: false

			# Sections with panels
			sections:
				{...definition}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

If you want extends other defined layout, use extends key. For example, we have somewhere defined minimal layout and we want to use them in our process. List of predefined layout is in Panelus documentation.

# Variables

Variables are concept which allow you control process and define multiple ways how to complete it.

Actually are variables divided into 2 types:

  • json - complex structure (contains multiple specific (scalar) values)
  • scalar - specific value (true/false, 1-X, foo)

Each variable must have:

  • $key (required) - unique ID of variable
  • title (required) - user-friendly variable name
  • type (required) - type of variable (scalar/json)

Also you could define:

  • typeDef (optional) - definition for type and spec (e.g. datus schema)
  • spec (optional) - specification of variable (actually: datus, files, processes)
  • specDef (optional) - definition for spec - e.g. version
  • value (optional) - define default value, which is set into variable contain when process start
variables:
	# Specific value
	customer:
		title: Name of customer
		type: scalar

		# Default value
		value: John Smith

	# Datus
	connection:
		title: Information about connection
		type: json

		# Specification is of type datus
		spec: datus

		# Definition of datus schema (contains version of schema)
		specDef: {version: 1}

		# Default value for datus
		value: { notes: "Default notes" }

		typeDef:
			inputs:
				# Selectbox
				type:
					control:
						label: Connection selection
						type: select
						options: {items: [Fiber, Wired]}

				# Text input
				price:
					control: {type: text, label: Price of connection}

				# Textarea
				notes:
					control:
						label: Notes
						type: textarea
						attributes: {placeholder: "Fill me"}

				# Submit button
				send:
					control: {type: submit, label: Update data}

	# File
	file1:
		title: First file

		# Json is required
		type: json

		# Specification is of type file
		spec: files

	# Processes
	# Array of processes IDs (mainly used for subprocesses)
	processes:
		title: Processes

		# Json is required
		type: json

		# Specification is of type processes
		spec: processes
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

To find out if variable of type JSON at expressions is empty (e.g. when file was not uploaded yet) then is required to use function !empty(variable).

# Events

During process are launched predefined events which you can respond to, e.g. with callbacks.

Scope Event Description
process on_process_start Launched on new process initialization.
process on_process_complete Launched on process completion.
step on_step_start Launched on new/next step initialization.
step on_step_end Launched on step next tryout.
step on_step_completion Launched on active step completion.

# Lifecycle

Action Call stack Description
New process 1. Internally write log on wall
2. Trigger callback on_process_start on the first step
3. Trigger callback on_step_start on the first step
4. Internally compute inbox field for the first step
5. Internally autoselect resolver for the first step
Next step 1. Trigger callback on_step_end on the current step
2. Internally lookup and evaluate next step
3. Trigger callback on_step_completion on the current step
4. Internally move to next step
5. Trigger callback on_step_start on the next step
6. Internally compute inbox field for the next step
7. Internally autoselect resolver for the next step
Complete process 1. Trigger callback on_step_end on the current step
2. Internally lookup for the summary step
3. Trigger callback on_step_completion on the current step
4. Internally move to summary step
5. Trigger callback on_step_start on the summary step
6. Internally compute inbox field for the summary step
7. Internally autoselect resolver for the summary step
8. Internally write log on wall
9. Trigger callback on_process_end