While the main ambition of BPMN and GO-BPMN processes is to automate your processes as much as possible, there is a good chance that your processes will now and then require input from a human user.

You can get such user input at a certain point of a process execution or at any point in time. Depending on this requirement, you will use either a to-do or a document:

A to-do serves to get input at a particular moment during a process execution.
A document serves to get input at any point in time; no process execution is required;

Getting Input for a Process

To get input at a particular moment during a process execution, we need to add a user task to the process flow: when the execution reaches the user task, it generates a so-called to-do, a work item with a form. A set of users, performers, can see the to-do from the Application User Interface; we say that the to-do has been assigned to the initial assignees. When one of the assignees opens the to-do, the to-do disappears from the to-do lists of other assignees: it is locked by the user. This user performs the actions and provides the information required by the to-do and once happy with the result they submit the form. On submit, the execution of the user task finishes and the execution of the process continues.

Hence, a user task must define the data for the to-do:

the set of its performers,
the content that is displayed when one of the perspective opens the to-do.

Note: In your custom Application User Interface, you will most likely substitute the default To-Do List with your custom implementation to display additional information about the to-dos. Instructions on how to do so are available in a dedicated tutorial.

Now, we will create a process with a user task, define a simple content for the to-do and demonstrate, how the end-user submits the to-do.

Creating a Process with a User Task

To create a process with a user task, do the following:

Create a process definition file.
Insert a user task.

You have now a process with a user task: there are multiple errors on the task since we have not defined its required parameters, yet; we will do so shortly.

Note that you do not need to insert a None Start Event or Simple End Event into the process; they are implied.

Defining To-Do Properties

When the user task becomes alive, the system generates a to-do with some content for the initial performers or assignees. Hence we need to define the content and the performers:

Let's first define the content:
1. Create a form definition file.
  
  Important: When creating the form definition, make sure the flag Use FormComponent-based UI IS SELECTED: Designer comes with two different implementations of forms; the flag defines which of the two is used in the new form. You are using the newer implementation.
2. In the form, insert a button and define its Click Listener expression so it submits the form (the expression is executed whenever the button is clicked).
Now, let's define the properties of the user task:
1. Select the user task on the canvas or in the Outline view.
2. Focus the Properties view.
3. In the Properties view, open the Parameters tab and define the following parameters:
  - Define the title of the todo, for example, title -> "Submit Me"
  - Define the admin user as the sole performer in the task properties: performers -> {getPerson("admin")}
    
    The getPerson() function call returns the admin user: no other user will see the to-do in their to-do list..
  - Define the form you created as the to-do content: this is done in the uiDefinition parameter of the user task, for example, uiDefinition -> new SubmitForm().
Save changes.

After you save changes, your project should be error-free.

Running the Model

Let you run the model: we start Designer Embedded Server; if you are using the cloud edition, connect to the cloud server.

The server did the following:

It created a model instance.
It created an instance of the process in this model instance.
It triggered the execution of the process instance: this created an instance of the user task, which is now alive and generated a to-do.

The execution is now stuck on the User task waiting for the to-do to be submitted: open the Application User Interface as the admin user and submit the to-do.

When you clicked the Submit button in the to-do, the execution flow continued:

in our case the to-do ceased to exist,
the user task became finished; because there was no execution going on in the process instance,
the process instance finished and subsequently also the model instance.

You can check the status in the Management perspective.

Getting Input at Any Point in Time

If you want to create a page that will take input from a user at any point in time, create a document: similarly to a to-do, its content is a form. Unlike a to-do, the document is accessible always as long as the module with the document is in the Module Repository.

Note: Under the hood, whenever a user opens a new document, the system creates a new model instance. The instance contains only the instance of the document and finishes when the user submits the document.

Creating a Document Definition

You will now create a document with the same content as the to-do (we will use the same form).

To create a document, do the following:

Create a document definition file.
In the file, create a new document definition with the following properties:
- UI Definition: the form with the submit button, for example, new SubmitForm()
- Access right: access rights of the user to the document; set it so that any user can access the document; that means it must always evaluate to true
- Navigation: page to go to after the document is submitted
  
  By default, the user is redirected to home page. This property overrides the home redirect. You could set it to the Documents page:
  { s:Set<Todo> -> new AppNavigation(code -> "documents")}

Uploading and Accessing a Document

Run or connect to your server and upload the module with the document.

Now you can open the document as any user.

Proceed to Goal Hierarchies