1. Intro
This step-by-step tutorial will help new edoras one modelers get started with defining 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, both of which can be found here: http://documentation.edorasware.com
1.1. What you will learn
By following this tutorial, step by step, you will learn how to create your own App, including the following:
-
Creating case models
-
Designing forms
-
Designing processes
-
Creating ad-hoc task models
-
Creating email templates
-
Creating documents models
-
Creating queries
-
Customizing dashboards
1.2. Tutorial App
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.
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 can find the shape palette, the main canvas for the form design in the middle and on the right-hand side you can find the attributes of the currently selected widget (component) on the canvas.
You can add a new widget to the canvas by simply dragging & dropping it from the shape palette to the canvas. During the drag & drop you will get feedback by the responsive layout manager on where the widget can be dropped.
The layout is responsive, with twelve slots you can use to arrange your widgets. By using the handles on the left or right side of a widget, you can define the span of the widget from one up to twelve slots.
The shape palette has several sections to choose from. Use the predefined widgets if you don’t want to worry about bindings and any other technical issues. The widget section has a wide collection of all the available widgets, which will need configuration through the attributes section.
2.2.2. Add name and description widgets
To start with the design, let’s use two predefined fields: the name and description. These fields are always available and each work item supports them.
Now drag & drop the name and description field from the predefined bindings
section on to the empty form.
Rename the name label to Travel subject
and the description label to Travel notes
.
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 location, so let’s use the Text
field from the Components
section.
Name the first one Origin
and the second one Destination
.
By dropping the second field onto the first one, the row will split into two parts with both fields in the same row, each spanning six slots.
Instead of navigating through the shape palette, you can also use the filter functionality to quickly find a specific widget. Click the filter icon in the top right
corner of the Shape palette and type the name of the widget into the search field (e.g. text ).
|
To make the fields mandatory, select a field and click the red star icon. Do this for both Fields.
You can also achieve the same result by clicking the Required
attribute in right side panel.
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 at how data is stored and managed within edoras one.
The basic structure to manage anything within edoras one is called a work item
.
A work item is an object of a particular type (e.g. a case, a task, a process or a document),
its behavior is driven by its type and model (e.g. a process work item is driven by its process model, which in our case is modeled with BPMN 2).
Besides its behavior, every work item is able to store arbitrary data, called variables
.
Variables hold different types of data, such as text, numeric value, a date or a boolean value.
Variables can even hold lists of data or maps or even lists of maps with unlimited nesting.
In order to enter or display the data of work items, its variables can be mapped (bound) to fields.
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 tell the form engine where to save and load the data for a particular field.
Let’s save the origin in a variable named travelOrigin
and destination in a variable named travelDestination
, respectively.
Bindings are specified using expressions, which start with a double curly brace {{
and end with a double curly brace }}
.
If we don’t specify any prefix to the variable name, the data is stored and retrieved from the same work item the form is associated with.
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 & drop two Date
fields on the form and name them Outward trip date
and Return trip date
, respectively.
Make the fields mandatory and set the bindings to {{outwardTripDate}}
and {{returnTripDate}}
.
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 rule to the date picker.
You can do so by selecting the date field and then clicking on the Minimum date
attribute on the right side under Specific attributes
.
Select a relative date validation by choosing Today + 0 Days
.
For the Return trip date
we also want to add a validation rule. Here we want to ensure that the selected date is not before the Outward trip date
.
To achieve this, we simply add {{outwardTripDate}}
to the Minimum date
attribute of the Return trip date
widget.
Save the form by clicking the Save
icon in the designer menu on the left.
2.3. Create case model
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:
-
Set
Travel Request
as the name -
Choose the
Travel Request Form
as both the init form and the work form of the case -
Everything else can be left as it is by default, we will make changes to that later in the tutorial
Click Create
to create the new case model.
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 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.
2.5. Test the App
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.
- NOTE
-
A copy of the tutorial App at this point is availble in the distribution bundle as
ModelerTutorialApp1.zip
.
2.6. Getting familiar with 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
-
lets you specify the owner and current assignee of the work item
- Share
-
lets you share the work item with one or more groups
- Start Process
-
starts 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 for 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 to 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
-
(only available to modelers) shows the JSON representation of the current work item, which can also be modified. Great care needs to be taken as you could break data of the work item by incorrectly modifying its JSON representation.
3. Basic process modeling
In this chapter you will learn how to create your first process, attach it to the case model created previously, and then to start it automatically when 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 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.
3.2. Getting familiar with the process modeler
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.
3.3. Add a pool and lanes to the process
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.