Tutorial10
- Building your First Workflow Process
Part
1: Design the Workflow Process
Part
3: Define Activities for the Interactive Tasks
Part
4: Define Process Attributes and Mappings
Part
5: Add an Email Resource to the process
Part
6: Define Activities for the System Tasks
Part
7: Testing the Laptop Process in the Designer
Part
8: Testing the Laptop Process outside of the Designer
See also: Workflow
Index, Workflow Concepts, Xi
Assignment Handler
Introduction
Prerequisites for
running this tutorial:
1.
The Ebase Xi Workflow Server and Ebase
Xi Workflow Client modules are both licensed. To check, start the Server Administration Application and
click License on the home page > check Details tab
Installed Features:
Ebase Xi Workflow Server [x]
Ebase Xi Workflow Client [x]
2.
Server property Enable
authentication of new users is enabled. This is done using the Server Administration Application and
click Server Properties > Security Properties.
3.
At least one email account must exist
and this is created using the Server
Administration Application. If you don’t yet know the parameters to configure
an email account,
set up a dummy account with hostname localhost.
4.
The distributed Logon and Workflow
Assignment System Services have not been modified. If you have modified
these, you can still use this tutorial, but you will need to change the part
where the approval task is assigned to a Manager (in Part 3)
– this would need to match whatever user authentication and assignment
logic has been implemented.
If you
don’t understand what this instruction means, you are almost certainly
using the distributed System Services, so carry on.
This tutorial will lead you step by step through the process
of creating a simple workflow process. The process has three steps:
·
A user makes a request for a new laptop via an
electronic form.
·
The request is routed to another user who is
responsible for approving or rejecting such requests.
·
The originating user is informed of the approval
or rejection decision via an email.
In terms of workflow, this process will be implemented as two interactive tasks i.e. the laptop request step and the subsequent approval/rejection step, and one system task
responsible for issuing the email notification back to the requesting user. The interactive tasks will be implemented as Ebase Xi forms. The tutorial assumes that the reader is
familiar with Ebase Xi development
concepts such as forms, resources and writing Javascript
scripts.
Part 1: Design the Workflow Process
Start the Ebase Xi Designer
1.
If
the Tutorials
project doesn’t already exist, create it by right clicking in the
Entities
tree panel and selecting New > Project, then link the new
project to
the ebaseSamples project (right click on the project name, then
select Properties).
2.
Create
a new folder for the tutorial: right click on the Tutorials project and select New > Folder, name the folder Tutorial10.
3.
Right click on the new folder and create a new
workflow process (New > Workflow > Workflow Process) called LaptopWF.
4.
Click once on the interactive task node icon 
.
Click anywhere on the page to add the task node. Double click on it to change
the name
to LT_REQUEST.
Repeat this to create a second interactive task node and name it LT_APPROVE.
5.
Click once on the system task node icon 
and place it on the page. Double click on
it to change its name to LT_EMAIL.
6.
Link the tasks Start -> LT_REQUEST ->
LT_APPROVE -> LT_EMAIL -> FINISH by clicking the 
icon
and dragging the arrow between the task nodes.
Make sure they are linked correctly so when you move a task node the left or right, the arrow moves along with it.
Right-click on each link and select Configure to rename the links from the default to ‘start’, ‘request’, ‘approval’ and ‘completion’ respectively.
Position each link name in the
middle of the link by right clicking on the link and selecting Link...
>select Label Link in the middle.
(Hint: you can achieve vertical alignment by selecting everything – draw
a rectangle around all items – then right click and choose Align…
> Align centres vertically).
Your process should now look like this:
7.
Change the task descriptions:
·
Edit the LT_REQUEST task configuration by
double-clicking the icon. Set the description to be ‘Laptop
Request’
·
Edit the LT_APPROVE task configuration. Set the description to be ‘Laptop
Approval’.
Save the process.
Part 2: Prepare the Forms
The Laptop process requires two Ebase Xi forms to operate:
one to enable a user to request a Laptop and one to enable Bob (we’ll define
this user in a moment) to approve or reject the request.
1.
Import the forms by selecting Tools > Migration > Import from the menu at the top of the screen.
Click the Browse..
button and select the file at location UfsServer/samples/Workflow/laptop_forms.zip
within the Ebase Xi distribution,
then click the Next in the
import wizard. On the next panel, leave the target project name as Tutorials then click the Import button
– this will create a folder named Laptop
containing
the two forms: LaptopRequest and LaptopApproval and various other entities. The
forms are fully functional but must now be configured to work with the Laptop
workflow process:
2. Navigate to the new Laptop folder in the designer Entities tree, and open form LaptopRequest. On submission the form must start a new Laptop process and complete the first task defined in the
Laptop process
at the same time. In addition, relevant data must be passed to the
Laptop process so it may be passed later on to other defined tasks. The form
collects the following data:
|
APPLICANT_EMAIL |
- the email address of the user making the request |
|
APPLICANT |
- the name of the user making the request |
|
APPLICATION_ID |
- a unique reference number allocated to the request |
|
ID |
- the product identifier of the selected Laptop |
|
PRICE |
- the price of the Laptop |
|
DESCRIPTION |
- the description of the Laptop |
These fields
must be defined as ‘Workflow out
parameters’ i.e. their values will be passed to the Laptop workflow
process:
3.
Click the Form Properties icon on the toolbar,
select the Workflow tab and add the above form
fields to the ‘Workflow out parameters’ box.
(Hint: You can control-click to select multiple fields).
We will also define a single
Save the form.
4.
We must also workflow enable the LaptopApproval form. This form receives data
values from the LaptopWF process i.e. that
describe the item requested, and passes back an approved or rejected status.
If the request is rejected
the form also passes back a rejection reason. To enable this we must define:
APPLICANT
APPLICATION_ID
PRICE
DESCRIPTION
ID
as ‘Workflow in parameters’.
Also add
‘REJECTION _REASON’ as a ‘Workflow out
parameter’. We will also define two ‘Workflow completion states’:
APPROVED
and REJECTED.
Save the form.
Part 3: Define Activities for the Interactive Tasks
We must now define Activities to associate each of the interactive workflow tasks LtRequest and LtApprove, with the LaptopRequest and LaptopApproval forms.
Right click on the Tutorials9
folder and select New > Workflow > Interactive Activity. Name the new activity
LtRequest.
In the activity editor, leave the Activity Type as ‘Ebase Form Activity’ – this means an Ebase Xi form is going to be the activity. Click the … button to the right of the ‘Form’ box and
select
the LaptopRequest form
in the Laptop project. The Input Parameters, Output Parameters and
Save the
Activity – click the save icon 
on the toolbar.
Return to the LaptopWF workflow process, double click on the LT_REQUEST interactive task to display its properties. On the General tab, click the … button to the right of ‘Activity’ and select the LtRequest activity.
Save the process.
Now repeat the exercise to create
a second Interactive Activity named LtApprove linked
to form
LaptopApproval , and connect this activity with interactive activity LtApprove in the
process.
We have now associated the Ebase Xi forms LaptopRequest and LaptopApproval with the tasks LT_REQUEST and LT_APPROVE. The association is implemented
via the interactive
Activities LtRequest and LtApprove
respectively.
We will now configure the assignment of the approval task. For simplicity, we will allocate this task to a role called MANAGER. In the real world we might want to be more specific and restrict this to just the requestor’s line manager.
This type of dynamic allocation of resources to tasks is fully supported by the Ebase Xi workflow system. We will use the Server Administration Application to create the role and a single user.
Click the Manage Local Server icon 
at the top right of the designer and
select Start Server Admin App from the dropdown. This will launch the
application in your default browser.
Then select Ebase Security System
from the menu on the application’s home page.
·
Click
on the Roles tab and create a new role named MANAGER (Don’t add any authorizations to the role).
·
Then click on the Users tab and create a
new user
named Bob, password Bob. Add roles of SUPER_USER,
MANAGER.
In the LaptopWF Workflow Process, double click on the LT_APPROVE interactive task to configure it. Select the Resources tab and assign the task to the MANAGER role by,
selecting Custom assignment and entering ‘MANAGER’ in the Assignment key field.
Assignment logic i.e. who can perform each task, is controlled by the Resources tab for each task. When Custom is selected, the decision is delegated to the Xi Assignment Handler –
this is a customizable system process that runs an Ebase script that you can change to meet almost any assignment requirement. In this example we are using the default behaviour
of this supplied script which is to treat the Assignment key field as a role name; any users that have this role can perform the task and it will appear on their task list.
Click on the link above for more
information on this subject.
Part 4: Define Process Attributes and Mappings
We must now define the Process Attributes that will hold the data being passed in and out of the process via the Ebase Xi forms.
In the Workflow Process’s Attributes View panel (usually in the top right of the process editor),
add attributes as follows:
Confirm the Attribute types of all attributes are set to Character in the Properties view panel (this is the default).
Change the PRICE attribute to type Currency.
Save the LaptopWF
process.
Note: the process
attributes EMAIL_FROM and APPROVAL_MESSAGE: these will be used
subsequently in a System Task to issue notification email.
We must now map task node Input and Output Parameters to the Process Attributes. Double-click the LT_REQUEST task node and select the Mappings tab.
Map the parameters and process attributes as follows by clicking the Auto-map button above the Output parameters panel. Check that all parameters are mapped;
if they aren’t you may have typed a name incorrectly:
Repeat the exercise for Task LT_APPROVE. Again check all input and out parameters are mapped:
Note that the LT_APPROVE task has both Input and Output parameters i.e. the input parameters describe the Laptop request to Bob
and the output parameter contains a rejection reason (if the request is rejected).
The LT_REQUEST task however is the starting point of the process and therefore has no input parameters.
Part 5: Add an Email Resource to the process
Our workflow process contains one System Task, called LT_EMAIL. The function of this task is to automatically send an email notification to the originator of the Laptop request.
Create a new Email Resource by right clicking on the Tutorials9 folder and selecting New > Email Resource, name the new resource LtApprovalEmail.
Connect the resource to an Email Account, and configure the
resource as shown below – Hint: having completed the top section, you can
click the 
icon on the Resource fields
toolbar to create the fields automatically.
Note that this tutorial can still be completed, even with an invalid Email Account.
Save the Email Resource.
Add the new resource LtApprovalEmail to the workflow process LaptopWF: in the LaptopWF process editor, click on the Resources tab to show the Resources View
(this
panel is usually in the top right-hand corner). Add the Email Resource LtApprovalEmail just created by clicking on the 
icon the Resources View toolbar.
Map the Email Resource fields to
the Process
Attributes by clicking the 
icon
on the Resources View toolbar, as follows (hint: click Auto-map):
(See Working with Email for more
information)
Save the process LaptopWF.
Part 6: Define
Activities for the System Tasks
We must define a new System Activity to send an email. Right click on the Tutorials9 folder and select New > Workflow > System Activity. Name the new activity LT_EMAIL
and use
programming language Javascript. Enter the code by
cutting and pasting the following:
importPackage(com.ebasetech.xi.api);
importPackage(com.ebasetech.xi.services);
// create text to
substitute into email...
//
if (system.variables.$COMPLETION_STATE.value ==
"APPROVED")
{
fields.APPROVAL_MESSAGE.value
= "Your application Reference No. "
+ fields.APPLICATION_ID.value
+ "
for a LAPTOP - "
+ fields.DESCRIPTION.value
+ "
has been approved.";
}
else
{
fields.APPROVAL_MESSAGE.value
= "Your application Reference No. "
+ fields.APPLICATION_ID.value
+ "
for a LAPTOP - "
+ fields.DESCRIPTION.value
+ "
has been rejected: "
+ fields.REJECTION_REASON.value
+ ".";
}
// send the
notification email...
//
fields.EMAIL_FROM.value =
"Test";
resources.LtApprovalEmail.sendmail();
Save the System Activity LtEmail.
Return to the LaptopWF workflow process, double click on the LT_EMAIL interactive task to display its properties. On the General tab, click the … button to the right of ‘Activity’ and
select
the LtEmail Activity just created.
Save the process.
The LtEmail
Activity constructs a notification message based on the
Part 7: Testing the Laptop Process in the Designer
The LaptopWF
process may be tested by clicking the 
icon on the Workflow Process designer
toolbar. Click OK on the Process Input Parameters dialog (there are no input
parameters for the process);
the
Process Tester will then appear:
Click Start to begin the
process. Each task will be processed in turn. For each Task, you will be able
to enter values for input and output parameters, and choose Completion States.
The first Task is LT_REQUEST and this is indicated in the flow diagram in the
right-hand panel: enter values for the output parameters as follows and click
the Complete task and Step button:
A popup will appear asking you to select the actor for the next task LT_APPROVE; this is testing the dynamic assignment logic.
The dropdown list will only
contain one entry showing the MANAGER role, so select MANAGER
and click
OK.
The panel for the second Task, LT_APPROVE, will appear. Choose a Completion State of REJECT and enter a Rejection reason as ‘Sorry, no budget’.
Click the Complete task and step button.
The process now moves on to the
System task LT_EMAIL.
Click the Step button to continue.
The LT_EMAIL
task is executed i.e. an email is sent to the originator of the Laptop request
with an appropriate notification message. The process is now complete:
Note: The Process Tester actually executes the process for real i.e. it is not a simulation. As a result of executing the test an email will be despatched to the email address entered
during the
completion of the LT_REQUEST task.
Click the Finished button to
terminate the tester.
Part 8: Testing the Laptop Process outside
of the Designer
Important! The following steps require
user authentication to be enabled on the server – see prerequisite 2 at
the top of this tutorial.
The Laptop process may now be
tested directly from the web browser. Start a web browser and enter a URL
to run the LaptopRequest form
e.g.
http://localhost:3030/ufs/LAPTOP_REQUEST.eb
At the authentication prompt enter any valid username and password e.g. ebaseuser. Note if you have previously signed on by running another form, the authentication prompt will not be shown.
The LaptopRequest
form will appear.
Enter a value for name and email address, choose a laptop and click Submit. The form starts a job for the LaptopWF process passing in the relevant data.
Close the web browser completely
– this is required because userids are
associated with browser sessions and we now need to sign on again as a different user
(the
manager).
The next task in the process is LT_APPROVE. This task is assigned to the MANAGER role and we have created a user named Bob with this role. This means that it will appear as a task item on Bob’s task list.
We must therefore run the WF_TASKLIST
form, which is shipped with the Ebase Workflow product as a sample task
list application. Start a web browser and enter a URL to run the WF_TASKLIST
form e.g.
http://localhost:3030/ufs/WORKFLOW_TASKLIST.eb
At the authentication prompt we must sign in this time as user Bob (password Bob) N.B. Usernames and passwords are case sensitive. Note that the authentication prompt is only displayed for new sessions,
so you may need to close all open browser windows then open a new browser and enter the URL for the WF_TASKLIST form.
The sample task list will appear
containing any tasks that can be performed by Bob:
The task is waiting for a user with the MANAGER role to complete it. Clicking the Task Name in the list will automatically invoke the LaptopApproval form, passing in the data describing the Laptop requested.
Bob must now decide whether to approve or reject the request. Enter a rejection reason of ‘Sorry, no budget.’ and click the Reject button.
The form will pass the rejection
reason and a
The final task, LT_EMAIL,
will now execute and the process execution is complete. That completes this
tutorial.
Solution
The complete solution to the tutorial may be imported from the following export files shipped with the product in folder UfsServer/samples/workflow,
or by downloading it from the Resource
Centre/Sample > +Completed Tutorials Apps section of the ebastech.com
website:
|
laptop_forms.complete.zip |
the LAPTOP_REQUEST and LAPTOP_APPROVE forms including input and output parameters, and defined Completion States |
|
laptop_process_complete.zip |
the Laptop process; LT_REQUEST, LT_APPROVE and LT_EMAIL Activities and LT_APPROVAL_NOTIFICATION Email Resource |
|
Tutorial10-Building your First Workflow Process - Solution.zip |
Tutorial10 – complete solution |