edoras one Modeler Tutorial

By following this tutorial, step by step, you will learn how to create your own App, including the following:

For this tutorial we will use the scenario of building an App to handle travel requests. A person who needs to travel will start a new travel request, and a travel agent will organize all the necessary bookings for the trip.

The request process will be built step by step, adding approvers to the process, modeling a feedback-loop between travel agent and requestor and by adding mail tasks to send out information once the travel has been organized.

Everything around the travel request is modeled within a case, so we can attach any necessary information (such as reservation information or vouchers) directly to the case, as well as having an overview of everything going on while managing the travel request.

In order to get started, go to the modeler dashboard and hit c or click the Create button in the menu and choose Create App.

Type Tutorial App as the name for the App.

Select English as the primary language for the App.

Select any other languages you want as secondary languages.

Let’s create a first form by typing again c (shortcut) or clicking the Create button in the menu. Now let’s choose Create Form Model and make sure the Tutorial App is selected as the parent App (meaning the new form model will be created inside that App).

Type Travel Request Form as the name for the new form model and click Create and design in order to create the model and directly go to the form designer.

Now switch back to the browser tab where you created the new form (not the form designer) and click the Create button once again and select Create case model.

Fill out the case model form:

Click Create to create the new case model.

Done! We have our very first version of the Tutorial App ready to be deployed and used.

Click the Tutorial App link from the previous green success message, or the link within the header of the current case model in order to navigate to the Tutorial App.

In the App, you should now see two models: the Travel Request case model and the Travel Request Form model.

From the list of actions on the right side menu you can select Deploy, opening the deploy dialog. Navigate to the end of the dialog and click OK to deploy the App. This will make it available within the user dashboard, so now we can test it.

In order to test the newly deployed App, we switch to the user dashboard. You can do so by selecting the User dashboard from the menu of dashboards or use the d shortcut. While modeling and testing, it is also a good practice to have two tabs open constantly, one with the user dashboard and one with the modeler dashboard.

Once in the user dashboard, click Create or type c to open the creation dialog. Select Create Case and choose Travel Request from the selection menu.

Fill out the request init form we’ve just designed. Please note the validation checks within the date picker, specifically notice that you will not be able to enter a date earlier than today.

Click the Create button to complete creation of the new case. You will see the newly created case displayed using the same form, as we set it for both the init and the work form. Now you will be able to modify any values and click Save in order to change the data for that case.

On the right side you will find available actions for the current work item (a case currently). The top right area shows the available views of the work item.

Actions, from top to bottom:

Views, from left to right:

Switch back to the modeler dashboard (either through the dashboard switcher or by going to your second tab with the modeler dashboard still open).

Choose the Tutorial App if not yet open and click Create or hit c. Now let’s choose Create Process Model and enter Travel Request Management Process as its name, then click Create and Design to create the process model and immediately open it in the process modeler in one step.

The process modeler is quite similar in its basic functionality to the form designer. On the left-hand side you can find the shape palette with several sections from where you can choose process elements. The middle area is the main canvas area where you design the process. The right-hand side shows the attributes of the currently selected element in the process canvas.

You can add elements to the process by simply dragging and dropping them from the shape palette onto the canvas.

Hint: as you start modeling processes, the spacing tool is a very handy feature to make more space in your current process model:

Activating it will allow you to easily expand sections of the process model or make a section smaller. Give it a try once you have some elements on the canvas and make yourself familiar with using the feature. Simply turn it off by clicking it once again to deselecting it.

Let’s start the process model by adding a pool and lanes to it. This is optional in BPMN 2, but is a good practice in order to visualize the different roles, people and groups involved in the process.

Go to the Roles section in the shape palette, drag & drop a Pool onto the canvas and name it Travel Request Process. A single lane has been added automatically, double-click its label (called Lane) and rename it to Requestor.

Now let’s add a second lane for the travel agent managing the travel request. Select Lane from the Roles section of the shape palette and drag it to the bottom part of the pool; dropping it will add it as a second lane below the existing one. Name it Travel Agent. Using the spacing tool, it’s easy to make the lanes smaller or larger according to need.

We’ve now created two lanes representing two different types of people involved in the process: the requestor actually creating the travel request, and the travel agent responsible for managing the travel.

Let’s add a start event to the process by dragging the Start event element from the Execution section of the shape palette onto the Requestor lane. When an element is selected, you should see the fast-modeling menu floating next to the element. The start event element should still be selected, so click the user symbol from its fast-modeling menu in order to add a user task immediately after the start event. Name it Manage Travel Request, click on the user symbol again and name the next task Review Travel Bookings, then finally click the thick rounded end event in the fast-modeling menu.

Done! We have our very first process with a start event, two user tasks and an end event, looking something like the following:

Now let’s get the tasks into the right lane simply by moving them. Move the Manage Travel Request task into the second lane, as it should be done by the travel agent. Make use of the spacing tool in order to add or remove space between lanes and elements.

Save the process model by clicking on the Save action in the menu bar (we will add task forms later, so ignore any warning messages for now) and switch to the browser tab with the process model within the Tutorial App (not the designer window).

Navigate to the Tutorial App and select the travel request case model. In the Autostart Processes selection choose the newly created process model and save the case model again.

We’ve now created our first, albeit simple, process model and attached it to the existing case model. We can now re-deploy the App by using the Deploy action as we did before and switch to the user dashboard in order to test the changes made.

After successfully deploying the Tutorial App, switch to the user dashboard and click Create then select Create Case. Select the Travel Request template, fill out the form and start the next travel request case.

Did you notice the gray badge in the left top corner of the children view button? It shows you that there is one child work item of the current case, which is the first task being created by the process.

Click the children list view to see that task. The open task should be named Manage Travel Request and behind it you should see the name of the travel request case (the same as in the header).

Navigate to the task by clicking its name. It will take you to the work form of that user task. You can still see the case in the header section of the task and use it to navigate back to the case, or you can also use the browser back button to go back. To navigate to the task, select it as the current work item. As you’ve probably noticed, this will change the available views and actions, always reflecting the possibilities with the currently selected work item.

The user task has a default form with the name of the task and a description field. But let’s have a look at the different options available when working with the task. There is a new view called Preview; selecting it will display the process with a red border highlighting the current task.

Go back to the work form by clicking on the Browse button, add some notes and click Complete. This will complete the task and hand control back to the process engine, continuing with the process execution and, in our case, leading to the second task being created. You can go to the preview again and see that the process execution has now moved to the second task. Complete the second task as well and this will finish the process execution. You can then navigate back to the case by using the case link in the header of the task, and check that the children view doesn’t show the badge anymore, as there are no more opened tasks available.

As we haven’t created specific user task forms yet, you’ll have realized that default forms were used. Of course, this doesn’t make much sense for real use and we can improve the two user tasks by designing task forms for them, showing all necessary information needed to complete each task.

Switch back to the process designer (if still open, otherwise switch to the modeler dashboard, select the process model and click Design to open the process modeler).

Select the Manage Travel Request user task. There are two ways to create or select a form for this user task: either click the Add reference context menu; or, go to the attributes of the task and click the Form reference attribute.

Here, you can choose between selecting an existing form (of course we don’t have any suitable forms yet) or creating a new one. And that’s what we’re going to do, so choose New. The form designer is opened again, ready for a new form to be designed that will be automatically attached to that task.

We’ve successfully added two new task forms and attached them to the appropriate user tasks in the process. So let’s test it by deploying the App again, creating a new travel request and stepping through the process.

Make sure you save the process model too before you redeploy the App, as we have also changed it to map the newly created forms!

Once you have redeployed the App, create a new case, click on the children view and select the manage travel request task. You should now see the specific task form we designed:

Add some notes, complete the task and check whether the data in the second task reflects this correctly.

Instead of having to manually upload any booking documents, let’s place an attachment widget directly to the case form for easy access to this capability.

First, switch back to the App in the modeler dashboard, navigate to the Travel Request Form and click Design.

Let’s add a comment on the attachment widget for the user to understand how to use it in our context. Drag & drop an Output textarea to the bottom of the form, don’t add a label, and double-click the widget to open the rich editor and enter something like this:

Below the output widget, drag & drop a new Attachment widget from the Component section of the shape palette and name it Attachments / bookings. Like text data bindings, the attachment widget can also be bound to a variable, which will hold all information about any attachments uploaded. Use the binding {{attachments}} this time and your form should look like this:

Now let’s fine-tune the widget by selecting it and changing some attributes. First, let’s customize the Select file message by changing the default value to Upload any booking documents here or similar. Set the Preview type to Thumbnail, as we want to include a preview in the attachments, if possible. Set the Thumbnail maximum height to 200 to prevent big pictures from using too much space on the form.

Now save the case form and redeploy the App. Instead of creating a new case straight-away, let’s have a look at how versioning is done while deploying an App.

It so happens that we also want to add the same attachment widget to the task forms. We could do this the same way as we did before using copy and paste, but this time we want to try a new feature of forms, sub forms, a great way for re-using existing parts of forms, either for technical or business reasons.

Go to the Tutorial App and click Create, select Create Form Model and enter Attachment Section Sub Form as its name, then click Create and Design to directly open it in the form designer.

First, go back to the case form designer and select both the output widget and the attachment widget and copy them to the clipboard. Switch back to the new, still empty, subform and paste the widgets there. The subform should now look like this:

Save the subform and switch back to the case form designer ready to add it there, but first we need to understand how the binding works for subforms.

Assuming the problem as described above, there are several options for how the travel agent could solve it:

The first two options are probably the way we solve many unexpected business situations, but they are not integrated in a way that any new information is automatically available within the case. In a large organization there might be a team of travel agents working together and they would need to share that information somehow, so everyone can always be up to date.

As a first step, let’s create an appropriate ad-hoc task model to support this directly within the case. In parallel to the running process, a user can create ad-hoc tasks at anytime if enabled in the case model (which is the default).

Ad-hoc tasks can be built with forms in exactly the same way we’ve created forms so far. This time, we’re going to create a different init-form. Go to the Tutorial App, click Create, select Create Form Model and name it Ad-hoc Feedback Init Task Form. Click Create and Design to open the new form in the form designer.

This time we will also learn the difference between an init-form and a work-form. So far we’ve used the same form in the case for both. Additionally, we will use a subform to show the data of the case within the case form itself, a nice way to ensure all the data for a case is shown in another context.

First of all, we want to be able to set a subject for the ad-hoc task (like the subject you would put in an email). We can use one of the predefined widgets, so drag the Name widget from the Predefined bindings section of the shape palette onto the form and rename the label to Task subject.

For the description of the task (the request for additional information, review or whatever) we will also use a predefined widget, so drag & drop the Description widget onto the form and rename its label to Task description. Click the star button of the description widget to make it required, to force the user to specify a task description.

Remember, we’re still designing the init-form of the ad-hoc task, which is only used during the creation of the new task, so we also want to be able to select the assignee for the ad-hoc task. There’s a predefined widget to do exactly that, so drag & drop the Assignee selection widget from the Predefined selections section onto the form and rename its label to Assignee for the task. Let’s also add a due-date for the task (another default field as well), so drag the Due date widget from the Predefined bindings section and drop it onto the assignee field in the right part, splitting the row into two parts, and rename its label to Task due date.

Now the form should look like this:

As mentioned before, this time we want different forms for initializing (creating) a new ad-hoc task and for working on it, so go back to the Tutorial App, select the Ad-hoc Feedback Init Task Form and click the Duplicate action, as we want to create a copy of the form so we only have to change what’s different between the init-form and work-form. In the duplicate name field, write Ad-hoc Feedback Work Task Form and click Ok to copy it. Go back to the Tutorial App (link in the header) and select that newly created duplicate form, then click Design to open it in the form designer.

Now we only have to make a few modifications to suit our needs. It doesn’t make sense to allow the subject and description to be changed, so let’s make them read-only by setting their attributes Editable to false. Next, remove the assignee selection and task due date, as we don’t want to be able to modify them.

As the requestor of the initial case, we want to be able to modify the case data itself, so let’s add that case information by using a subform. Previously we saw how data from the case can be shown in a task form by using an output textarea widget and then manually add all necessary data with appropriate expressions to it. This is one option, now let’s see a more generic way to include the case data in the task form by adding it as a read-only subform, using the very same form as we used for the case itself. This way, we make sure that whenever we add new stuff to the case form, it will automatically show up in this task form as well, because it’s a subform. Additionally, we want to be able to choose to show and hide the case information through a checkbox.

Drag & drop a Checkbox widget to the form, label it Show case information and bind it to {{showCaseInfo}}. Select the Default value attribute and set it to true as the default (so the case info is visible by default).

Now drag & drop a Single-type subform below the checkbox and label it Case information. Click the + button and select Reference and then Travel Request Form, our primary case form. Next, we need the binding for the subform. Remember, we want to show the case information in there, so we use {{root}} for the binding, which will map to the current case within which the ad-hoc task has been created. Last thing to do is to set the Visible (RT) attribute to the same binding as the checkbox {{showCaseInfo}} to make the visibility flag of the subform dependent of the state of the checkbox. Visible (RT) means visible runtime and lets you define an expression that must resolve to either true or false, then the visibility is dynamic based on the expression’s value. Also note that expressions are evaluated in real-time directly within the form engine of edoras one, whenever the data that the expression is based on changes. In our case with the checkbox value, the visibility flag is automatically adjusted appropriately. Make sure we have Show border set to true and Multiple elements to false, as there is exactly one case instance to be shown and we want it in a border to visually indicate its data is coming from somewhere else.

The interesting part now is that we can even modify data in one single form for both the task and the case instance simultaneously, so the user doesn’t even need to be aware of context that data is coming from or being saved.

The ad-hoc task work form now should look similar to this (the attribute section is the one from the selected subform):

Now save the form and go back to the Tutorial App for our next step.

Go to the Tutorial App and click Create and choose Create Task Model. Set the name to Travel Feedback Task.

Now select the appropriate init-form and work-form in the Init Form and Work Form selections of the task model and complete creation of the model by clicking Create.

Navigate back to the Tutorial App and deploy it again, which will make our new ad-hoc task available for use.

Switch to the user dashboard and select one of your previously created travel request cases. Now click Create and choose Create Task. If you do that in the context of a currently selected case, it should be automatically preselected in the Parent Case selection. Now choose the Travel Feedback Task Template, fill out a task subject and description, choose yourself as the assignee (so you don’t have to logout and login to complete it) and optionally also choose a due-date.

Click Create to create the ad-hoc task. If you check Create another before hitting Create, the new task will be created and you will return back to the same init-form so you can quickly create another one.

Going to the newly created ad-hoc task there are several things you should note. First of all, you should be able to show and hide the case information by simply clicking the Show case information checkbox. Also note that the information in there reflects the case information and you are able to modify it directly while in the task. You can test that by changing some case information in there, clicking Save (not Complete yet) and navigating to the case. The data in the case itself should have been updated accordingly.

To complete the task, simply click Complete and it will be finished. By default, completed tasks are not shown in the children list of a case. If you would like to see them, go to the children list of the case and select status All within the search box. Now you will see all work items of the case, even completed ones.

As an alternative to the ad-hoc task approach we just tried, we now want to incorporate the agent <→ requestor feedback loop directly into the management process.

And here is how we can do it:

Go back to the Tutorial App and redeploy it. Now switch to the user dashboard and create a new case with our Travel Request template.

Did you notice the new attachment widget was also visible in the init-form? If you don’t want to be able to upload attachments while starting the travel request, just add {{root.id}} within the Visible (RT) attribute of the subform widget holding the attachment subform in the Travel Request Form. It will not show up as long as the case hasn’t been initialized, because the root.id variable is not available.

If you navigate to the Manage travel request task within the children view of the case you will see the updated management task form. Select Need more information… from the Next step selection and the new Information request field should appear, where you can enter the information you need from the requestor:

Did you notice the rich text capabilities within the text editor? When selecting part of the text, a toolbox appears that allows you to change the formatting:

If you now click Complete, the next task will be the answer info request task, where you can provide an answer, after which the process will go back to the management task. You can use this feedback loop as many times as you want. As soon as you choose Finish…, the process goes to the review task and will finish.

Did you notice the pre-selected next step combobox when returning back to the management user task? Remember that we bound the selection of this widget to parent.nextStep, and as the selection is stored in the process it will be remembered the next time that information is used again. As we don’t wont that behavior, let’s go back to the process and add a service task to reset its value before we return to the management task again.

Before we include the responsibilities (assignees) in our process, let’s have a look at the permission concepts behind edoras one. Every work item (a case, task, document, and so on) can have the following information concerning responsibilities and sharing:

In order to have access to a work item you must either be the owner or the assignee of it, or be a member of one of the candidate groups, alternatively, you must have been added explicitly as a candidate user.

If we want to use groups and users in our App, it is important to also understand how they are managed in edoras one. Go to the Administrator dashboard by selecting it from the Dashboard menu (you need to have administrator permission in order to have access to this dashboard, of course). You will now see an overview of your accounts, groups and users in your tenant.

Technically, this CSS class will be added to the same div that contains the class .edoras-one.
In custom.css there is a commented line to import the file accounts.css. This file contains an example of how to apply your custom styles. To use account CSS customizations, uncomment this line and replace account-example with the name of the CSS classes defined on your account. You can do this for several accounts by repeating the content and changing the class name. Elements that you do not want to customise can be safely removed from the accounts.css.

For "Cloud" solutions, there are some predefined account CSS classes:

To turn off UI customisation for the Account and use default colours, simply remove your class from the account form, leaving only the "account-" prefix.

To create a new Account, click Create or hit C and choose Create Account from the dialog, fill out the necessary information and create it by clicking Create.

As we learned earlier, participants, groups and roles are modeled through pools and lanes in BPMN 2.
We currently have two different participants in our process: the requestor of the travel request, and the travel agent managing the request.

First, we need to extend the travel management task form by adding a new possible next step.
Open the Travel Request Management process and click the + sign within the Manage Travel Request user task in order to open the task form.

Select the Select next step combobox and click the Options property. Now add a new option by clicking the Add button. Add the new approval option like the following:

You can move the order of the new entry by selecting its row and clicking the up-arrow.

If the user selects this new option, we want to display a text field for them to enter any additional approval notes and, of course, select the approving user.
Drag & drop a new Rich textarea just below the Information request text area, name it Approval notes and bind it to {{root.approvalNotes}}. We only want to show this new field whenever the new step is selected, so set the Visible (RT) property to {{parent.nextStep=='approval'}}.

From the Predefined selections section of the shape palette, choose the User selection widget just below the Approval notes text area and name it Select approver. Change the binding expression to {{root.approver}}, make it required and set the Visible (RT) property to {{parent.nextStep=='approval'}} as well.

Your task form should now look like this:

Now save the task form and switch back to the process in order to extend it with this new approval functionality.

As we will be adding a new role to the process, let’s add a new lane to represent it. Drag & drop a Lane below the Travel Agent lane onto the existing process pool and name it Approver:

From the existing gateway, drag a new user task out of it, drop it within the newly added Approver lane and name it Approve Travel Request.
Now select the sequence flow between the gateway and the newly added user task and name it approval. We also need to tell the process engine when to actually use this flow, so set the Condition expression to #{nextStep=='approval'}.

Drag a new sequence flow out of the new approval task and connect it to the existing Reset next step selection task.
There are now three incoming sequence flows to that task and it’s good practice to use a joining gateway before that task for better visibility of the flow, although it isn’t necessary by the BPMN 2 standard.
To be able to do that, make some more space (using the spacing tool, if you remember) before the Reset next step selection task and drop a new Exclusive gateway onto the sequence flow. Then you have to re-connect the existing sequence flow leading into the Reset next step selection task to the newly added gateway. You can do so by hovering over the sequence flow you want to re-connect until the green circle handles become visible, then drag & drop it using those green handles to the new gateway.

Your process should now look like this:

Next, we need to set the assignee for the approval task to be the person we selected in the management task. Select the Approve Travel Request user task and set the Assignee (RT) property to #{root.approver}.

The only remaining missing thing is the approval task form, so let’s create one. Select the Approve Travel Request user task, open the attributes and click on the form reference in the Specific Attributes section. Then select New and click the OK button to create a new task form.

Drag & drop a new Output textarea to the form in order to add some information for this approval task. Double-click it to open the editor for its content and add the following:

Notice the expressions we used in the output widget. First of all, they are frontend expressions using double-curly braces, as they will be rendered in the form engine running on the frontend. {{root.name}} actually renders the travel requests name (case name or root name). {{root.approvalNotes}} is the notes field we added within the management task form to allow the travel agent to add special notes for the approver. Finally, we have {{root.travelAgent}}, which will be automatically set after the management task has been completed by the travel agent, using a Initialize variable task.

When it comes to the decision widget for the approver, we basically have two choices: using a checkbox (for instance, if we have yes / no options) or using a selection combobox, the latter being a little bit more verbose and, of course, can have more than two options.

Drag & drop a Static select widget below the output text area and name it Please make your decision. Then double-click the widget and enter {{root.approvalDecision}} for the data binding (or enter it in the value property). Also, make the field required (by either clicking the red small star of the widget or checking the Required property).

Now click the Options property and enter the following values to the dialog:

Finally, let’s add a Rich textarea, name it Decision notes and set the data binding to {{root.approvalDecisionNotes}} to let the approver add any special notes about the decision.

The form should now look like this:

Save the form, name it Travel Request Approval Task Form and switch back to the process model and save it too.

What did we do? We added a new option to the Manage Travel Request task for getting approval for the travel request, added the approval user task and routed the process back to the travel agent, who then needs to decide whether to further organize the travel or stop it (if approval wasn’t given). How does the travel agent know about the decision made by the approver? We can add this information back to the management task, so they have everything there.

Let’s go back to the process, 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 task form. You can also switch to the task form, if it is still open.
There are several options for how we could add this information. As it is read-only information, we can display it using another output widget that we only want to show if there is an approval already done.
Add a new Output textarea and drop it below the Travel notes rich textarea, double-click it and set it to this content:

We only want to show this widget if the approval has already been given. We can do so by using the Visible (RT) property we’ve used before. Select the output widget and enter {{root.approvalDecision}} in the Visible (RT) property. This way, the widget will only be shown if the approval variable is set, which can only be the case after the approval task has completed.

Save the form and go back to the Tutorial App to redeploy it. Start a new travel request, select the Need approval option, select an approver (yourself, to avoid logging out and logging in again) and you should end up at our new approval task.

As we look at the approval task now, we have some room for improvement. First of all, do you see how the expression {{root.travelAgent}} is rendered? It’s some cryptic user ID rather than the users name. The backend could support something like #{root.travelAgent.name} in order to access the name of that user, but the frontend doesn’t currently provide that.
So, what options do we have? Remember the Initialize variable service task we used to store the travel agent ID after the Manage Travel Request user task? Let’s add another variable to hold the travel agents name.
Open the Travel Request Management process and select the Store travel agent user task. Click the Init variables property and add the following variable initialization:

Save the process and open the Travel Request Approval Task (or switch to it, if it’s still open). Double-click the output widget at the top of the form and replace {{root.travelAgent}} with {{root.travelAgentName}}, so it uses the user’s name rather than their ID.

Save the form, go back to the Tutorial App, redeploy it and test the process again.

If not, here are the basic steps:

We want to create the email template as the first step, so go to the Tutorial App and hit C or click the Create button and choose Create Mail Model and name it Travel Request Declined Email Template. You can hit Create now and fill in the rest of the template later, or complete the email template within the Create Mail Model form.

Now create the template so it looks like this:

As we only want to send the email if the travel request was declined, we need to add a new gateway after the approval user task. Open the Travel Request Management Process and make some space at the bottom of the lane in order to add a new gateway. Reroute the existing sequence flow so the process looks similar to this:

After adding the new elements and rerouting the sequence flows accordingly, we need to add the conditions for the new sequence flows leaving our new gateway to tell the engine which flow to take.
Select the sequence flow with the label yes and set the property Condition expression to #{root.approvalDecision=='approved'} and for the no labeled flow use the expression #{root.approvalDecision=='declined'}. After this, whenever a travel request is declined, the process will end directly without any notification.

Abruptly ending the travel request process just because a request is not approved isn’t the most friendly solution, so we want to integrate our email template and send out a notification email once the request is declined.
Go to the Travel Request Management Process and make some space between the gateway and the end event, to give us room for a new email task. Now drag & drop a new Send mail service task onto the no sequence flow and name it Send decline notification email.

Select the Travel Request Declined Email Template as the Mail model for the Send mail service task, so this will be used when creating the email subject and body to be sent. We want to send the email to our initial requestor and CC to the travel agent. To do that, we’ll use #{root.ownerId} for the Mail recipient property and #{root.travelAgent} for the Mail CC one.
Your process should now look like the following:

When you are testing the email functionality, please note that it may take several minutes before you receive the email.

A document might have some properties (metadata) stored as variables that can be used to classify it or allow it to be found later. This is done using a form in just the same way as for cases or tasks, to create a document or to manage the metadata of a document.

Go to the Tutorial App and hit C or click Create and select Create Form Model, name it Travel Request Document Form and click Create and design. Drag & drop the Name and Description fields onto the canvas. Let’s assume we want to select an assignee for the document, so drag & drop the Assignee selection widget below the description. To share the document with other groups, we could drag & drop the Share with groups selection widget as well.

If you want to have more metadata for your document, just add more fields to the form; you can design the document form in the same way as for tasks or cases.

The document form should now look like this:

If we want to be able to upload content during the creation of the document (init-form), we can add an upload-widget. Drag & drop the Upload widget to the top of the form (before the name field) and name it Upload document. This is a special widget that’s only used for uploading the content of a work item (in this case, a document), so we don’t need any special data binding.

We only want the upload widget, the assignee selection and the share with group field to be visible during the initialization of the document, but we’d like the form to be used as both init-form and work-form. There is a way to achieve this using the Visible (RT) property to show or hide a widget, depending on whether the form is used as an init-form or as a work-form.

With that knowledge, let’s add {{!root.id}} as the Visible (RT) property for the Upload widget, as well as for the Assignee and the Share with groups widgets.

The document form should now look like this:

Save the form and go back to the tutorial app.

Using the document form we just created, we want to create a new document model within our Tutorial App, so go back to the tutorial app and hit C or click the Create button and select Create Document Model, name it Travel Request Document and select Travel Request Document Form for both the Init form and Work form. Now create it, navigate back to the Tutorial App and deploy it, so we can test our new document model.

We’ve learned how we can create and use a document work item from uploadable content. In our next step, we will attach a file template, also called a skeleton, to the document model. Go back to the tutorial app and select the Travel Request Document and click the Upload skeleton button. You can now upload a document that will be used as the template whenever we create a new document based on that model. Choose an empty Word document for now, and we will use it again later with placeholders.
After having uploaded the document, you will see it in the preview (even if it is a Word document).

Now have a file template attached to the document model, we really don’t need the upload widget in the init-form anymore, so go to the Travel Request Document Form, remove the Upload widget and save the form.

Go back to the Tutorial App, redeploy it, switch back to the user dashboard and navigate into one of your previous cases. Click Create, select Create Document, select Travel Request Document, choose any name you want for the document and click Create. If you go to the Preview (eye icon), you will see a document that looks the same as you used for the skeleton in the document model.

Whenever there is a skeleton file attached to a document model in an App, it will create a copy of it and store it in the case in which the document was created.

We’ve learned how document skeletons can be used as the template that is copied when a new document is created. In our next step, we will add placeholder fields in the document so we can automatically fill in data from the root case of the document.
Go back to the Tutorial App, select our Travel Request Document and click Edit skeleton, which should open the document in Microsoft Word. If the Java plugin for the Office integration is not supported in your browser, you can just use the Download skeleton button, save it to your desktop and open the document from there.

Now write your travel request document template and use text fields for the placeholders (you typically find them in the developer tools of Microsoft Word). Your document could now look like this:

Double-clicking a placeholder opens up its details:

The important information is the text marker name, which we will use later for data binding. We’re using the expression we’re going to map to afterwards as the standard text, but this is not mandatory, only good practice to see where data will be filled in.

I used the following placeholder information:

Now save the Word document. You need to use the Upload skeleton action and upload the saved Word document again.

Navigate to the Tutorial App and redeploy it, then switch to the user dashboard, select one of your previously created cases and create a new document the same way we did before.

Your document in the case should now look similar to this:

As you can see, the request name has not been properly set within the title, which is because we used caseName as the name of the marker and this is not a variable name that’s available in our travel request case. Not only that, we’d really like to change the formatting of the dates as well, so let’s see how we can do that.

We’ve so far learned how to create a document model, use skeletons and further improve them with placeholders (optionally with placeholder mappings using expressions). Our next step takes us back to the process model, where we want to automatically create our document as part of the process. Go to the Tutorial App and open the Travel Request Management Process.

Drag & drop a new Create document service task onto the sequence flow, right after the last Review Travel Bookings user task, and name it Create Travel Doc. In the property Document model, choose our recently created Travel Request Document model and use root.travelDoc as the Document id variable name property. You can optionally specify the name for the document using the Document name variable, so we’ll set it to #{root.name}.docx.

Your process should now look like this:

You can now save the process model, redeploy the app and start a new travel request or start the travel management process within an existing case again. By the end of the process, our document will have been created from the template using the data from the case, and stored within the case.

As a final step, we want to send a document from our case as an attachment to an email. Go back to our Travel Request Management Process and make some space before the Send decline notification email task. Before we can use the document as the attachment in that email, we first have to create it using the same task we added in our last step. We could add a new Create document task again or we can copy & paste our existing one, so we don’t have to enter all properties again. You can do so by selecting the existing Create Travel Doc task, using the Copy button or hit Ctrl-C to copy it and then the Paste button or Ctrl-V to paste it. Drag this copy and drop it onto the sequence flow just before the Send decline notification email task.

Your process should now look like this:

Select the Send decline notification email task, click the Attachment ids property and enter #{root.travelDoc} in the property dialog.

Save the process, redeploy the app and start the process again or create a new travel request. Make sure to use the approval path and decline it in order to send an email with the document as an attachment.

If we want to get a list of all open travel request cases, here’s the way to create an appropriate query item:

You probably noticed that some of the terms are being removed from the search box and represented using the predefined, simple search selection, for example the state and type terms or even the sort term.

Once you have the results in the way you want them, click the Create Query button, add a name for it and click Create. If you go back to the user dashboard, you will see the new query item in the list of My Queries.
If you wish, you can share a query item with others by using the Share action. This will mean other users will have the opportunity to see and use that query in their own dashboards.

Once you’ve created a query item, it’s simple to use it by just clicking it in the user dashboard. It will then be executed and return a list of work items matching the query terms.
If you select the Work Form view at a later time, you can change the name and query term for the item and save it the same way you would with a case or task item. Alternatively, you can use the Share action to add some groups you want to share the query item with.

Once you’ve execute a query item, you can export its results and data by clicking the Export Query Data button. This will create an Excel file containing all data from the returned work items.
Currently, you can’t configure what data is exported, so the Excel file can become quite large.

We are going to model and design a case to act as our dashboard. Since we can design a working form for a case, we can design it in such a way that it could act as our dashboard. We can’t use it directly, so we need to create an instance of the case and find its unique URL, then store this URL as the default one in our user profile and we’re done!

This is exactly the same as we’ve done many times now in this tutorial, so go to the Tutorial App, hit C or click the Create button and select Create Form Model to create our dashboard view. Name the form Dashboard View as it’s more a view than a form, then click Create and Design to directly create the form model and open it in edoras vis to design it.

Drag & drop an Output textarea on to the top of the form, so we can add some information about the dashboard. Double-click it and add something like this to it:

We want to add some lists of information to the dashboard, so drag & drop a new List widget onto the form and remove the label by deleting its predefined text. Lists show work items retrieved using a query term. Still remember the query items from our last chapter? A list widget is based on exactly the same query terms and uses the same search functionality as a query item or the global search action in edoras one.

Now select the newly added List widget and set the Title property to Open travel requests.

With the Format property we can specify how the labels of the items in the list will be displayed. By default, it will use the name of the work item. We would like to also include the original requestor of the travel request, so let’s set the Format property to {{item.name}} (Requestor: {{item.owner.name}}), which will include the name of the requestor after the name of the travel request case.

Set the Query property to the following search term: type:CAS state:open model:'Travel Request' sort:creation:desc

We can limit the height of the list widget by setting the property Maximum number of rows, for example, to 10.

Your form should now look like this:

We would like to add two more lists, one of them only showing the Manage Travel Request user tasks, and the other showing all open tasks, regardless the type of case or app.
First the management tasks: drag & drop another List widget to the right-hand side of the existing list and configure the following properties:

Add a third List widget to the far right of the same row as the two other lists. If we want the three list widgets to be equally spaced, use the handle on the right or left-hand side of the widget to drag it to the left or right until it spans as many cells as you want (four, in our case, to have three equally spaced lists).

Set the properties of the third list widget to the following values:

Suppose we want to add an instant-filter field to the first list, to allow the user to filter the list to find a particular travel request. Drag & drop a new Text widget between the Output textarea and the List widget on the left. Then drag its right-hand side handle to the left in order to let it span the same number of columns as the list widget and name it Search. Set its value binding to {{caseSearch}}. We can now use that variable within the Query property of our first List widget to dynamically update the saved search terms for the resulting case list.

Select the first List widget (containing the open travel request cases) and add {{caseSearch}} at the end of Query, so it now is configured as type:CAS state:open model:'Travel Request' sort:creation:asc {{caseSearch}}.

The dashboard view should now look like this:

Now let’s save the form and return back to our Tutorial App.

As we said above, we’re going to model a case to represent our dashboard. Hit C or click the Create button and select Create Case Model then use Travel Management Dashboard as the name and set the Dashboard View for the Init Form and Work Form properties. Remove all selections from the Allowed Actions section, except the Create Variables action, as although we don’t want to work with that special case, we do want to display it. If you want to share the dashboard with others, you can select the appropriate groups within the Candidate Groups property.

Now click the Create button and redeploy the Tutorial App, then go to the user dashboard.

Before we can set the dashboard as our default one, we need to create a case instance based on that case model, so hit C or click the Create button within the user dashboard, select our Travel Management Dashboard template and click Create.

If you want to avoid having a case with an empty name, use the Edit view (only available as an admin or modeler) and set the Name field to something like Travel Management Dashboard and click the Save button.

Your dashboard should now look similar to this one:

Assume we have a lot of open tasks or cases and we can’t see all of them in the list widget, but would like to know how many there are. There are special Count widgets that allow us to display a link with a count of work items based on its associated query.
Go back to the Dashboard View form designer and add new Search count link widgets just below each of our list widgets, making their width span equally with the list widget they belong to.
Remove the label, as we only want to display the link text that includes the count of work items in the list.

For the first count widget, use the following properties:

For the second count widget, use the following properties:

For the third count widget, use the following properties:

Your dashboard view should now look similar to this one:

Go to the Tutorial App, redeploy it, go to the Travel Management Dashboard case and click the Migrate action in order to update our dashboard case to the latest version.

Your dashboard view now should look like this:

As a next step, we would like to add a new Create button to the dashboard view so a user can create a new Travel Request without using the general Create button.
Go back to the Dashboard View form and add a new Create button below the first count widget and resize it to only span four columns.
Use Create new travel request as the Button text property, choose Case as the Work item type property and select Travel Request as the Work item model property.
This will create a button that navigates directly to the init-form for a new travel request (the same URL, actually, as if you had clicked the create button and selected the travel request template).

Your dashboard view now should look like this:

Go to the Tutorial App, redeploy it, go to the Travel Management Dashboard case and click the Migrate action in order to update our dashboard case to the latest version.

Your dashboard view now should look like this:

If you click the Create new travel request button, you will go directly to the init form and be able to create a new Travel Request.

Let’s say we want to add some information we already have on the dashboard form and pass it to the init form being invoked by clicking a create button. We can do so by using context parameters.

To visually separate the create button from the list widgets, let’s add a horizontal line between them by dragging & dropping a new Horizontal line between the count widgets and the create button.
Then move the create button to the same four columns as the second list widget, giving us space to add a new text field to the first four columns.
Now drag a new Text widget and drop it on the left-hand side of our create button, name it Request name and bind it to {{travelRequestName}}. Optionally, you can specify a description by setting the Description property to Set the new travel request name used for creating a new travel request.

Next, select the create button and click the Context variables property and enter the following in the property dialog:

We’ll use the value from our newly added text field, ({{travelRequestName}}), and pass it along to the init-form as the name property, so our name field in the init-form will become prepopulated with that value.

Your view should now look like this:

Go to the Tutorial App, redeploy it, go to the Travel Management Dashboard case and click the Migrate action in order to update our dashboard case to the latest version.
If you now enter some text in the request name field and click the create button, that text is passed along and directly added to the init-form.

If you want, you can add even more fields and functionality to your dashboard view.

Now we’ve created our dashboard case, we would like to use it as the default one for the user dashboard.
First, make sure our new custom dashboard is currently shown and copy the URL-part starting with the CAS part (something like CAS/GEAR-xxxx/browse).
We can then set it as the default dashboard by going to our user profile (select the User profile menu action in the top right menu bar) and pasting the copied URL to the Home URL field, finally saving the user profile.

To make the changes visible, you will probably need to refresh the current view, and then you should find yourself looking directly at your new, custom dashboard!
You can always navigate to it by clicking the logo in the top menu bar. If you want to go back to the standard user dashboard, you can do so by selecting it from the dashboard menu or with the Home icon in the menu bar.