1. Intro

This step-by-step tutorial will help edoras one modelers to get started with modeling Apps for the edoras one platform.

It’s a good idea to have read the basic edoras one intro (general guide) as well as the edoras one user guide, which can be found here: http://documentation.edorasware.com

1.1. What you will learn

By executing this tutorial step by step, you will learn how to create your own App, which includes the following steps and learning content.

1.1.1. Basic modeling techniques

  • Creating case models

  • Design forms

  • Design processes

  • Creating ad-hoc task models

  • Creating email templates

1.1.2. Advanced modeling

  • …​

1.2. Tutorial App

In this tutorial you will create a new App, which will handle a travel request. A person in need of traveling will create a new travel request and a travel agent is organizing the necessary bookings for the traveling.

The request process is built step by step by 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 are able to attach any necessary information like reservation information, vouchers and the like directly to the case as well as having an overview of everything going on while managing the travel request.

2. Basic Travel Request Case and Form

In this chapter you will create the Tutorial App with a new form and case model, deploy it and test the new case model within the user dashboard.

2.1. Creating a new App

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.

Tip
As an App can be modeled in several languages, you specify a main (primary) language for the App, which will act as the default language, if not all elements are translated. You will be able to design forms and processes with all languages you selected (primary will be default). Now click Create and navigate to the newly created App by clicking on the link in the green success message you see on the top of the screen.
create app 01

2.2. Creating a form to start the travel request

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.

create form 01

2.2.1. Getting familiar with the basics of the form designer

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.

2.2.2. Add name and description widgets

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.

form design 01

2.2.3. Add traveling locations

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.

Tip
Instead of navigating through the shape repository, you can also use the filter functionality to quickliy find a specific component. Click the filter icon in the top right corner of the Shape repository and type the name of the component into the search field (e.g. text).

By selecting a field and clicking the red star icon, it will make the fields mandatory. Do this for both Fields. You can do the same by clicking the Required attribute on the right side.

form design 02

2.2.4. Getting familiar with the data model behind work items

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.

2.2.5. Define data bindings for the 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.

form design 03

2.2.6. Add date pickers for the outward and return trip dates

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}}.

form design 04

2.2.7. Add validation to the date pickers

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.

form design 05

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

form design 06

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

2.3. Create case model

Now switch back to the browser tap 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:

  • Set Travel Request as the name

  • Choose the Travel Request Form as the init and the work form of the case

  • Everything else can be left as it is by default, we will adapt that later

Now click Create to create the new case model.

create case model 01

2.4. Deploy the App

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

Click the Tutorial App link from your 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.

On the right side menu you can select Deploy which opens the deploy dialog. Navigate to the end of the form and click OK to deploy the App and make it available within the user dashboard so we can now test it.

app deploy 01

2.5. Test the App

In order to test the newly deployed App, we switch back to the user dashboard. You can do so by manually 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 as we designed it. Please note the validations and within the date picker, specifically see that you will not be able to enter a date earlier than today.

create case 01

Click Create to start the new case. You will see the newly created case with the same form as we used it for both, the init and the work form. So you will be able to change any data and click Save in order to change the data for that case.

create case 02

2.6. Getting familiar with the basic navigation

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.

case menu 01

Actions from top to bottom:

Assign

let’s you specify the owner and current assignee of the work item

Share

let’s you share the work item with one or more groups

Start Process

start an ad-hoc process within the current case

Archive

closes the current work item and archives it

Views from left to right:

Search

navigates to the list of children of the current case where you can find open tasks, documents or whatever the current case is holding

Browse

navigates to the main work form of the current work item

Comments

navigates to the comment section of the current work item where you can see all existing comments as well as add new comments or reply to existing ones

Edit Entity

only available for modelers, shows a generic view with all data of the current work item and the ability to change it or even add new variables

Edit Entity JSON

a JSON representation of the current work item, which can also be modified (be very careful in doing so as you could break data of the work item by modifying it’s JSON representation)

3. Basic process modeling

In this chapter you will learn how to create your first process and attach it to the previously created case model in order to start it automatically once a new travel request is created.

3.1. Create new "Travel Request Process" model

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 opened and click Create or hit c. Now let’s choose Create Process Model and enter Travel Request Management Process as it’s name and click Create and Design in order to create the process model and directly open it in the process modeler.

create prc model 01

3.2. Getting familiar with the process modeler

The process modeler is quite similar in it’s basic functionality as the form designer. On the left hand side you find the shape repository with several sections where you can choose process elements from, the middle area is the main process canvas where you design the process and the right hand side is showing the attributes of the currently selected element in the process canvas.

You can add elements to the process by simply drag and drop them from the shape repository onto the canvas.

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

prc modeler action 01

Activating it will allow you to simply extend (enlarge) the process model or make it smaller. Give it a try once you have some elements on the canvas and make yourself familiar with that feature. Simply turn it off by clicking it once again and deselecting it.

3.3. Add a pool and lanes to the process

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

Go to the Roles section in the shape repository, drag and 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.

prc modeling 01

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

prc modeling 02

3.4. Model two user tasks as the first version of the process

Now we created two lanes representing two different types of involved people in the process, the requestor actually creating the travel request and the travel agent, responsible to manage the travel.

Let’s add a start event to the process by dragging the Start event element from the Execution section of the shape repository onto the Requestor lane. As long as that element is selected, you should see the fast-modeling menu right next to the element. Click the user symbol in order to add a user task right after the start event. Name it Manage Travel Request, click on the user symbol again and name the next task Review Travel Bookings and then 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.

prc modeling 03

Now let’s move the tasks into the right lane by simply 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, elements, etc.

prc modeling 04

3.5. Save process model and attach it to the case model

Now save the process model by clicking on the save action in the menu bar (ignore the warnings for now, we will add task forms later) and go back 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.