edoras one Modeler Tutorial

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

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

The layout is responsive having 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 repository has several sections to choose from. Use any predefined widgets in order to not having to care about bindings and any other technical issues. The component section on the other hand has a collection of all available widgets which can be used by configuration through the attributes section.

To start with the design, let’s use two predefined fields; the name and description. Those fields are always available; each work item is supporting them.

Now drag and 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 that, 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 will split up the row into two parts and now having two fields in the same row, both spanning six slots.

By selecting the first and then the second field and clicking the red star icon will make the fields mandatory. You can do the same by clicking the Required attribute on the right side.

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

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

In order to enter or show data of work items, the 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 are telling the form engine where to save and load the data for a particular field.

Let’s save the origin in a variable called 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 / retrieved from the very work item the form is used for.

Now let’s add two new fields to pick the starting and ending date for the travel. Drag and drop two Date fields to 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 to the date picker.

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

Now 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 on how the data is organized in the work item hierarchy. The process is started within the case, so 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, so think of a hierarchy, where the case is the root, having a process as a child and the process having a task as it’s child. You can store data on every work item and every work item has also access to the data of it’s parent up to the root. But of course when building form data bindings, you have to be aware of the hierarchy and where the form is actually used. Bindings like {{foo}} without any prefix are always bound to the work item that form is used with. Let’s say you want to store / read data in the case, use the root prefix, for example the {{root.foo}} would store / read the data from the case’s variable named foo. You can also use parent as a prefix in order to go up one hierarchy level of the current work item. In a user-task, the parent would be the process.

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

Double click the component 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 the same way you did with the bindings of the 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, which is stored in the case. Make sure you use the very same variable names you used in the case init form.

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

We can now additionally add some description to the notes field to let the travel agent now, that he should enter additional information in there. Select the travel notes field and click in 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 component.

The form should now look like this:

Save the form with name Manage Travel Request Task Form. In order to re-use the output component with the all the information in it, select the output text area component and copy it. Now you can 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 + button in the second task named Review Travel Bookings and select New again. In the new form designer, paste the output component we previously copied from the first user task form. Note that copy / paste is supported not only within the same model, but also across models, which is quite handy sometimes.

Double click the output component in order to adapt it’s content to reflect the current task we want to create the form for. As this is just a review task, we also include the traveling notes in there directly rather than put the 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 that App will be deployed to the runtime of the edoras one platform and so 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 models. By default, the deploy mechanism is using a careful strategy by don’t migrating existing instance like cases, processes and tasks. This means, they will still be mapped to exactly the version they have been created with until they are either completed or migrated to a newer version.

For now, we want our cases to already reflect the newest change within the form, the attachment component, so go to the tutorial App and navigate to the Travel Request case model by selecting it. Click the Migrate action in the action menu of the case model and migrate all existing cases to the newest, 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 reflect the newest version. You should see the attachment component by now:

Click the upload icon and attach an image for instance. 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 other forms and thus different contexts, it is essential to isolate its data bindings and make it configurable outside of the subform where it is used.

Assume a subform with two fields in it with bindings to {{foo}} and {{bar}}. The subform should be used within a case form as well as within a task form but displaying the same data. Or the subform should even be used several times on the same form, but with different meanings (e.g. an address subform used twice, once for the main address another one 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 the exact same rules as explained previously in this tutorial. For instance, if the 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:

Now we learned the basics for the binding / isolation of data in subforms. There are some possibilities when it comes to which form is actually used as the subform as well as whether the subform should have one entry or is able to show multiple entries.

Now having learned the basics for how subforms are bound to data and for the different types of subforms, let’s use it in our case form to 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 component as we want to replace them with the subform we just created.

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

Click the + button at the bottom of the component to select the subform we want to use and select Reference and then the Attachment Section Sub Form to be used as the form reference.

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

Make sure Multiple entries 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 much identical as we had before adding the subform.

Because we entered a label name for the subform (optional), we can choose to remove the label from the attachment component to avoid duplicate information on the form. To do so, click the subform-name-link at the bottom of the subform component to directly open it in the form editor.

Go to the tutorial App, deploy it again, navigate to the Travel Request case model and migrate the existing cases, switch into the user dashboard and navigate to one of your previously created cases and you should see pretty much the same as before, but now done with a subform:

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

Open both task forms in the form designer. You can do that by either going back to the process model and click the + button the user task to open the corresponding form, you can go to the modeler dashboard to select the form in the My Form Models widget or you can navigate to the tutorial App and choose the appropriate forms from there.

Once opened in the form designer, drag and drop a Single-type subform at the bottom of the form and label it Attachments. As we’ve done before within 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 entries are turned off. Now the binding will be slightly different than we used on 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 is {{root}}.

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

For the other user task form, you can simply copy / paste the subform component from the other 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 into the user dashboard and navigate to one of your previously created cases (already having at least one attachment).

Now let’s see how we can start the process ad-hoc. Remember than 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 action menu and select Travel Request Management Process and click Start. This will start the process in the same case again. This is how ad-hoc processes can be manually started as an alternative to automatically start them during the creation of the case.

As we had in the beginning, the children view of the case shows one task as we re-started the process again in the case. Navigate to the task and check, whether you see the attachments too there:

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

In the process model click the + button of the Manage Travel Request user task in order 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 component from the Component section onto the form between the travel notes and the attachment subform and drop it in between. 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 out 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 decide to store it there and not in the 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 and enter two options in there:

The name column reflects the label used for that option whereas the value is used to store the selection in the mapped variable.

If we choose the first option, we want to show a new note field where the agent can specify what kind of information is needed from the requestor. So let’s drag and drop a Rich textarea from the Components section of the shape repository below the selection component 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 hence the validation will to take it into consideration. Bind the field to {{root.infoRequest}}, we want to make that information persistent, even after the process has been ended, so let’s store it within the case context and that’s why we use the root prefix instead of parent like we did with the nextStep variable.

As we are already thinking ahead 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 and drop a new Output textara 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 let’s select the Information request field and enter {{parent.nextStep=='moreInfo'}} in the Visible (RT) attribute, so it will only be visible 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, so it will only be visible, 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 within the process designer.

Still remembering the spacing tool? We can make use of it now by adding 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 repository and drop it directly onto 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 in between the two user tasks.

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

Select the gateway element (if not yet selected) and drag / drop the small user task icon in order 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 line 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 turn green and drop it in order to connect the two tasks with a sequence flow.

We now modeled the feedback loop after the gateway. Next step is to tell the engine which flow to use after the gateway by specifying conditions on all outgoing sequence flows.

Select the sequence flow between the gateway and the Answer Info Request user task and click into the Condition expression attribute and enter #{nextStep=='moreInfo'} as the expression. We will explain the difference in the 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'} in the Condition expression attribute and name it finish.

Optionally we can add a note to the gateway to document why it splits the process flow by selecting the gateway element and drag / drop the note icon and adding next step? as the note.

You probably noticed that there is a difference in the syntax for frontend expressions as being used within forms and backend expressions as used now in the process model. The difference is where they are being evaluated, directly within the browser (frontend / forms) or on the server (backend, everywhere else like process, email templates, document templates, etc). As the frontend expression are limited to whatever the browser and form engine know in contrast to the expressions on the server side which could even 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 difference very prominent to the modeler.

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

We now have to create the user task form for the new task added to the process. If you still remember, you can simply click the + icon, select New and it will create a new form, attach it to the user task and open 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 component and add the following content to it:

Note that we can include expressions everywhere in the content as we like.

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

The form will now look like this:

Now 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 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 directly onto the sequence flow between the start event and the user task and name it Reset next step selection.

Move the sequence flow end of the flow between the answer and the manage task to the new reset service task by dragging the green point at the end of the arrow and dropping it onto the reset service task. If you want to re-arrange the sequence flows, there are several handles you can do that with. There is a red point in every edge of the sequence flow to move that edge with. Adding a new edge is easy too, simply point anywhere on the sequence flow and drag / move the red point which is appearing. You can move a sequence flow in parallel by moving the red rectangle appearing in the middle of the flow.

Your process model should now look like:

Of course we need to tell the engine now which variables to initialize within the reset service task we just added. Select the service task and click the Init variables attribute where a dialog appears to enter the variables we want to initialize or reset as in 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. If you also want to clear the previously entered information request text, add an extra row to the dialog which should then look the following way:

Close the dialog and set the attribute Overwrite if existing to true (checked and green). This is necessary, as we explicitly want the variables to be overwritten if they already exist. If you would leave that option to false, it would only initialize variables not yet existing and would leave existing variable values untouched.

Save the process model and go back to the tutorial App in order to redeploy it and test the slightly changed behavior.