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.
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.
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.
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
.
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.
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.
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.
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}}.
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
.
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.
2.4. Deploy the tutorial 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
to deploy the App
and make it available within the user dashboard so we can now test it.
2.5. Test the tutorial 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.
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.
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.
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:
- List children view
-
navigates to the list of children of the current case where you can find open tasks, documents or whatever the current case is holding
- Work form view
-
navigates to the main work form of the current work item
- Comment view
-
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 variables view
-
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 JSON view
-
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.
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
:
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
.
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.
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.
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.
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.