edoras one Modeler Tutorial

The form designer consists of three parts: on the left you can find the shape palette, the main canvas for the form design in the middle and on the right-hand side you can find the attributes of the currently selected widget (component) on the canvas.

You can add a new widget to the canvas by simply dragging & dropping it from the shape palette to the canvas. During the drag & drop you will get feedback by the responsive layout manager on where the widget can be dropped.

The layout is responsive, with twelve slots you can use to arrange your widgets. By using the handles on the left or right side of a widget, you can define the span of the widget from one up to twelve slots.

The shape palette has several sections to choose from. Use the predefined widgets if you don’t want to worry about bindings and any other technical issues. The widget section has a wide collection of all the available widgets, which will need configuration through the attributes section.

To start with the design, let’s use two predefined fields: the name and description. These fields are always available and each work item supports them.

Now drag & drop the name and description field from the predefined bindings section on to the empty form. Rename the name label to Travel subject and the description label to Travel notes.

Now let’s add two fields to enter the origin and destination of the travel. There is no predefined field for location, so let’s use the Text field from the Components section. Name the first one Origin and the second one Destination. By dropping the second field onto the first one, the row will split into two parts with both fields in the same row, each spanning six slots.

To make the fields mandatory, select a field and click the red star icon. Do this for both Fields. You can also achieve the same result by clicking the Required attribute in right side panel.

Before we can define the data bindings for the new fields, let’s have a short look at how data is stored and managed within edoras one.

The basic structure to manage anything within edoras one is called a work item. A work item is an object of a particular type (e.g. a case, a task, a process or a document), its behavior is driven by its type and model (e.g. a process work item is driven by its process model, which in our case is modeled with BPMN 2). Besides its behavior, every work item is able to store arbitrary data, called variables. Variables hold different types of data, such as text, numeric value, a date or a boolean value. Variables can even hold lists of data or maps or even lists of maps with unlimited nesting.

In order to enter or display the data of work items, its variables can be mapped (bound) to fields.

The next step is to set the binding for the newly added fields. Double-click the field or go to the Value attribute on the right side. Bindings tell the form engine where to save and load the data for a particular field.

Let’s save the origin in a variable named travelOrigin and destination in a variable named travelDestination, respectively. Bindings are specified using expressions, which start with a double curly brace {{ and end with a double curly brace }}.

If we don’t specify any prefix to the variable name, the data is stored and retrieved from the same work item the form is associated with.

Now let’s add two new fields to pick the starting and ending date for the travel. Drag & drop two Date fields on the form and name them Outward trip date and Return trip date, respectively.

Make the fields mandatory and set the bindings to {{outwardTripDate}} and {{returnTripDate}}.

As we want to make sure there is no date selected in the past, let’s add a validation rule to the date picker.

You can do so by selecting the date field and then clicking on the Minimum date attribute on the right side under Specific attributes. Select a relative date validation by choosing Today + 0 Days.

For the Return trip date we also want to add a validation rule. Here we want to ensure that the selected date is not before the Outward trip date. To achieve this, we simply add {{outwardTripDate}} to the Minimum date attribute of the Return trip date widget.

Save the form by clicking the Save icon in the designer menu on the left.

Before we start designing the new task form, let’s have a look at how the data is organized in the work item hierarchy. The process is started within the case, making the process instance a child work item of the case. If a user task is created automatically through the process, this task becomes a child element of the process. You can think of this as a hierarchy, where the case is the root, having a process as a child and the process having a task as its child:

You can store data on every work item, and every work item has also access to the data of its parent up to the root. But of course when building form data bindings, you need to be aware of the hierarchy and where the form is actually used. Bindings such as {{foo}} without any prefix are always bound to the work item that form is used with. If you want to store or read data from the case, use the root prefix, for example {{root.foo}} would store or read the data from the case’s variable named foo. You can also use the special parent in order to go up one level in the hierarchy of the current work item. For a user-task, its parent is the process the user-task is part of.

Now let’s go back to our user task form for managing the travel request. It’s good practice to display helpful information about the current task on the task form. As a first step, we can add an Output textarea to it in order to display the travel request details in a read-only way. Drag and drop an Output textarea from the shape palette onto the form, but don’t enter a label name, just leave it blank.

Double-click the widget on the form, or click the Value attribute, to open the rich editor to edit the content for the widget.

Let’s add something like this:

You can use formatting and add any text you want. Of course, you can also add expressions in the same way we did with the data bindings of fields. Please note that we are now designing the form of a user task and hence we need the root prefix in order to display data that is stored on the case. Make sure you use the same variable names that you used in the case init form.

We want the notes for the travel request not only to be shown, but also to be editable by the travel agent, so let’s include a notes field to the form using the predefined widget named Case description. Drag & drop the Case description field from the Predefined bindings in the shape palette below the output widget on the form and rename its label to Travel notes.

We can now additionally add a hint in the notes field to let the travel agent know that he should enter additional information here. Select the travel notes field and click on the Description attribute on the right side. Enter something like Please add any additional information for the travel in here. You can also directly edit that description by double-clicking it directly in the form widget.

The form should now look like this:

Save the form with the name Manage Travel Request Task Form. In order to re-use the output widget with all its configuration details, select the output text area widget and copy it. You can now close the form designer browser tab, which should take you back to the process modeler.

Switch back to the process modeler browser tab and click on the Add reference context menu for the second task, named Review Travel Bookings, and again select New. In the new form designer, paste the output widget we previously copied from the first user task form. Note that copy and paste is supported across models, not only within the same model, which can be quite handy for quickly modifying models.

Double-click the output widget in order to change its content to reflect the current task we want to create the form for. As this is just a review task, we’ll include the traveling notes in there directly rather than using a description field as we did in the previous form.

Now save the task form, name it Review Travel Bookings Task Form and close the form designer browser tab.

Whenever an App is deployed, all of the models within it will be deployed to the runtime of the edoras one platform, and then they become available within the user dashboard. An App is deployed as a new version every time you deploy it, to make it fully consistent and compatible with all the models it contains. By default, the deployment mechanism uses a safe strategy of not migrating existing instances to the new models, including cases, processes and tasks. This means they will still be mapped to precisely the version they were created with until they are either completed or migrated to a newer version. So, even with an updated form in an App, existing instances of it will continue to display and use the older versions of the form.

For now, we want our cases to immediately reflect the latest changes within the form (the attachment widget), so go to the Tutorial App and navigate to the Travel Request case model by selecting it. Click the Migrate action in the right side action menu of the case model, and migrate all existing cases to the latest, just redeployed, version of the App.

Switch back to the user form and select one of your previously created travel request cases to make sure they now reflect the latest version. You should see the attachment widget now:

Click the upload icon and attach an image, for example. You will have to save the case form in order to see the preview (thumbnail) of the uploaded image:

In order to use a subform in different forms and therefore different contexts, it is essential to isolate its data bindings and make them configurable outside of the subform where they are used.

Assume a subform has two fields in it with bindings to {{foo}} and {{bar}}. The subform may be used within a case form as well as within a task form, displaying the same data in those different contexts. Or the subform may even be used several times on the same form, but with different meanings (for example, an address subform used once for the main address and again for the billing address). In order to be able to deal with situations like this the subform itself needs a data binding as well, following exactly the same rules as explained earlier in this tutorial. So, for instance, if a subform is bound to {{mySubFormData}}, there will be a variable named mySubFormData, which itself will be a map holding all data contained in that subform.

Example 1:

Example 2:

Example 3:

Example 4:

That’s now given us the basics for the binding and isolation of data in subforms. There are also some useful possibilities of dynamically changing which form is actually used as the subform, as well as whether the subform should have one element or is able to show multiple elements.

Now having learned more about how subforms are bound to data and the different types of subforms, let’s use it in our case form to change how we represent the attachment section of the request.

Go to the form designer for the Travel Request Form, if not already there, and delete the output textarea and the attachment widget, as now we want to replace them with the subform we just created.

Drag & drop a Single-type subform from the Components section of the shape palette onto the bottom of the case form and label it Attachments.

Click the + button at the bottom of the widget to select the subform we want to use. Choose Reference and then select the Attachment Section Sub Form as the referenced form.

Double-click the subform or click the Value attribute to enter the binding for the subform. As we want the same behavior as we had before without the subform, bind it to {{$this}}, meaning the data in the subform will be directly stored in the case (this also means we’ll even be able to migrate the existing cases without having to migrate any data).

Make sure Multiple elements is turned off in the Specific attributes section. You can choose whether you want a border around the subform or not. Turn it off to be as similar to we had before adding the subform.

Because we entered a label name for the subform (although optional), we might decide to remove the label from the attachment widget to avoid duplicate information on the form. To do so, click the subform-name-link at the bottom of the subform widget to open it directly in the form editor and make the change.

Go to the Tutorial App, deploy it again, navigate to the Travel Request case model and migrate the existing cases. Switch to the user dashboard and navigate to one of your previously created cases and you should see pretty much the same as before, but now achieved using a subform:

Now we have a reuseable subform, let’s add it to both user task forms as well, so we have all the useful information available in the different contexts of the process.

Open both task forms in the form designer. There are different ways to do that:

Once opened in the form designer, drag & drop a Single-type subform to the bottom of the form and label it Attachments. As we did before with the case form, click the + button at the bottom of the subform and select the Attachment Section Sub Form.

Turn off the border and make sure multiple elements are turned off. Now the binding will need to be slightly different than we used in the case form. Remember that we bound the subform to {{$this}}, meaning its data is directly stored within the case itself. In order to show the same data in the context of the task, we now need to bind it to the case, which can be done using {{root}}.

So, for the travel management task form, it should look like this:

For the second user task form, you can simply copy and paste the subform widget from the first task form (not from the case form though, as the binding is different there).

Go to the Tutorial App, deploy it again, navigate to the Travel Request case model and migrate the existing cases. Switch to the user dashboard and navigate to one of your previously created cases (one that already has at least one attachment).

Now let’s see how we can start the process whenever we want, in an ad-hoc way. Remember that the first time the process was started automatically when we created the case. Now let’s see how this can be done manually.

Click the Start Process action in the right hand action menu and select Travel Request Management Process, then click Start. This will start a new instance of the process in the same case. This is how processes can be manually started as an alternative to automatically starting them during the creation of a case.

As before, the children view of the case shows one task because we started the process again within the case. Navigate to the task and check, whether you see the attachments there too:

Navigate to our travel request management process and open it using the Design action (if the process modeler is not already open).

Open the process model in the process modeler, select the Manage Travel Request user task, open the attributes and click on the form reference in the Specific Attributes section. Then select Reference and click the OK button to open the form designer for the task form.

In order to separate the previous form elements from the next one, drag a new Horizontal line from the Component section and drop it right after the Travel notes field.

Drag a Static select widget from the Component section onto the form between the travel notes and the attachment subform, and drop it inbetween. Label it Select next step and bind it to {{parent.nextStep}}. Why did we use the parent prefix? Note that our form is used within a user task created as part of a process. If we want to be able to use the data in the nextStep variable in the process context, we must not store the data in the local task context, but rather in the process context (parent-prefix) or even the case context (root-prefix). As this information is only needed during the lifecycle of the process, we’ll to store it in the parent process and not in the root case context.

Let’s make the selection mandatory by clicking the red star or setting the attribute Required to true. Now open the Options attribute dialog by clicking its attribute value, then enter two options in there:

The name column defines the label used for that option, while the value column is used to define the variable to store the selection.

If we choose the first option, we want to show a new note field where the agent can describe what kind of information is needed from the requestor. So let’s drag & drop a Rich textarea from the Components section of the shape palette to below the selection widget on the form and label it Information request. Make that field required by clicking the red star, but note that the required-validation will only take place if the field is shown; if it stays hidden, there is obviously nothing to be entered and the validation takes this into account. Bind the field to {{root.infoRequest}}, as we want to keep that information, even after the process has been ended. We’ll store it within the case context and that’s why we’ve used the root prefix instead of parent that we used with the nextStep variable.

As we are already thinking ahead to when the feedback loop returns from the requestor back to the agent, we want to show the information the requestor entered, so let’s add an output textarea showing that information. Drag & drop a new Output textarea below the information request field and leave the label empty. Double-click it and add the following content to it:

We only want to show the information request field if the next step selected is moreInfo, so select the Information request field and enter {{parent.nextStep=='moreInfo'}} in the Visible (RT) attribute, making it visible only if we select Need more info… in the next step selection.

The output text area should only be visible if it has content, so let’s enter {{root.infoRequestAnswer}} in the Visible (RT) attribute, making it visible only if the variable root.infoRequestAnswer has content.

The form should now look like this:

We now have to add the feedback loop to the process model, so let’s open it in the process designer.

Still remember the spacing tool? We can make use of it now to add some extra space after the management task in order to add the gateway after the user task.

Now drag a new Exclusive gateway from the Execution section of the shape palette and drag it over to the sequence flow after the user task. As soon as the sequence flow becomes green we can drop it, as the modeler has recognized that we want to drop it inbetween the two user tasks.

As you can see, the modeler automatically splits the sequence flow into two and adds the gateway inbetween.

Select the gateway element (if not already selected) and drag & drop the small user task icon to add another outgoing sequence flow with a user task after the gateway:

Name the new user task Answer Info Request and align it right above the gateway and on the same horizontal level as the other requestor task:

Select the new user task and drag the arrow icon next to it onto the Manage Travel Request user task until it turns green, then drop it to connect the two tasks with a sequence flow.

We’ve now successfully modeled the feedback loop after the gateway. Our next step is to tell the engine which flow to use from the gateway by specifying conditions on all outgoing sequence flows.

Select the sequence flow between the gateway and the Answer Info Request user task, then click on the Condition expression attribute and enter #{nextStep=='moreInfo'} as the expression. We’ll explain the different expression syntax in just a minute, but first let’s add a label to the sequence flow. This can be done by clicking the Name attribute and entering the name, or simply by double-clicking the sequence flow directly in the process canvas. Let’s name it more info.

Now select the sequence flow between the gateway and the Review Travel Bookings user task and enter #{nextStep=='finish'} as the Condition expression attribute and name it finish.

It’s good practice to add a label to a gateway element, so double-click the gateway and type Decision?

You probably noticed that there is a difference in the syntax for frontend expressions used within forms and backend expressions as we’ve just used in the process model. The difference is down to where they are being evaluated: directly within the browser (frontend / forms), or on the server (backend, everywhere else, such as process, email templates, document templates, and so on). Frontend expressions are limited to whatever the browser and form engine know, in contrast to the expressions on the server side, which could contain your own service calls, functions, any navigation through the work item network and much more. That’s why we use different syntaxes, to make the difference in their evaluation very prominent to the modeler.

But now, back to our sequence flow condition #{nextStep=='moreInfo'}. Why didn’t we use parent.nextStep as we did in the form? It’s very important to always remember in which context an expression will be evaluated. In the user task form we are in the context of a task work item, which is a child element of the process work item. The expression on the sequence flow, however, is evaluated in the context of the process itself and therefore we don’t need the parent prefix that we needed in the task context.

We now have to create the user task form for the new task added to the process. If you remember, you can simply click the icon, select New and it will create a new form, attach it to the user task and open it up within the form designer.

Let’s add an Output textarea to the form so we can add the necessary information in there. Leave the label empty, double-click the widget and add the following content to it:

Note that we can include expressions anywhere within the content as we like.

Below the output field, add a new Rich textarea widget, label it Your answer and bind it to {{root.infoRequestAnswer}} (the same expression we already used in the management task form). Additionally, make it required by clicking the red star icon.

The form should now look like this:

Save the form, name it Answer Info Request Task Form and close it in order to return back to the process design.

Save the process model as well, with the new feedback loop, in order to test it.

Make some more space before the Manage Travel Request user task in order to add a service task there. Afterwards drag a new Initialize variables task from the Service tasks section onto the sequence flow between the start event and the user task, drop it and name it Reset next step selection.

Move the sequence flow connection that’s between the answer and the manage task so it points to the new reset service task by selecting the connection and dragging the green point at the end of the flow arrow, dropping it onto the reset service task. If you want to rearrange the sequence flows, there are several handles available to choose from. There is a red point on every bend of the sequence flow to allow you to move the bend location. Adding a new bend is easy too, simply click anywhere on the sequence flow and drag the red point that appears. You can move a sequence flow in parallel by moving the red rectangle that appears in the middle of the flow.

Your process model should now look like:

Of course, we still need to tell the engine which variables to initialize within the reset service task we just added. Select the service task and click the Init variables attribute, in the dialog that appears, enter the variables we want to initialize or reset for our case.

The first column can be left empty as our nextStep variable is in the process scope. Write nextStep in the variable name column and leave the last column empty as well as we simply want to clear the previous selection value. If you also want to clear the previously entered information request text, add an extra row to the dialog which should then look like the following: