Tutorial10 - Building your First Workflow Process

Documentation home

 

Introduction. 1

Part 1: Design the Workflow Process. 2

Part 2: Prepare the Forms. 3

Part 3: Define Activities for the Interactive Tasks. 6

Part 4: Define Process Attributes and Mappings. 9

Part 5: Add an Email Resource to the process. 11

Part 6: Define Activities for the System Tasks. 12

Part 7: Testing the Laptop Process in the Designer 13

Part 8: Testing the Laptop Process outside of the Designer 18

 

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 Completion State for this form: value COMPLETE. Click on the ‘+’ icon next to the ‘Workflow completion states’ box and type in ‘COMPLETE’.

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 Completion States will be imported automatically from the LaptopRequest workflow properties:

 

 

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 Completion State returned by the LT_APPROVE task, and then sends the email.

 

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 Completion State of REJECTED to the workflow process.

 

 

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