Human Workflow in 11g

Update:  If you are interested in Human Workflow, you may also find this post interesting.  It’s not about workflow per se, but it does show how to use a simple workflow in a BPMN process on 11g.

I am often asked about the Human Workflow included in the Fusion Middleware 11g platform – what is provided out of the box?  How are human tasks developed or designed?  How flexible is the user interface?  How are tasks queued/assigned to people/groups?  These are some of the most common questions.  I will attempt to address these in several posts.

In this first post on Human Workflow, I will provide a simple example, that you should be able to follow in your own environment, that shows how a human task is defined and used in a process.  Following these steps should get you a human task up and running in your own environment in less than 15 minutes.  Subsequent posts will build on this one to explore additional features of the human workflow engine.

You will need SOA Suite 11g and JDeveloper 11g to follow this example.  I used version 11.1.1.2 of both, running on Windows 2003 Server R2 in this example.

We will start by creating a new Service Component Architecture (SCA) Composite in JDeveloper.  The Composite is used to group together all of the components that make up our application.  It is the unit on which we do version control, deployment and so on.

Select New from the File menu.  I called my composite “SimpleTask.”  Select the “SOA Application” Application Template.  Note:  If you don’t see the SOA Application template, it probably means you have not added the SOA tools into your newly installed JDeveloper.  If this is the case, select Check for Updates from the Help menu and find and install the SOA tools from Oracle.

When you have filled out these details, click on Next to go on to the Project Name page in the wizard.  I also called my project “SimpleTask.”  Then click on Next to configure the SOA settings.

Choose the default (Empty Composite) and click on Finish.  We will add our components in the next steps.

You should now see your new Application (and SOA Project) opened in JDeveloper.  The composite will be opened in the assembly diagram in the centre.  On the right hand side, you can see a palette of the various components that can be used in a composite, and on the left hand side, you see the various files that make up the project.

We will start by defining a data structure that we will use later on in the human task and our process.  We are going to take the example of a simple Expense Claim.  Right click on the xsd folder and select New… from the popup menu.

You may need to switch to the All Technologies tab.  Then locate the XML entry under General in the Categories tree on the left, and select XML Schema on the right.

I called my schema “ExpenseClaim.xsd.”  Click on OK to continue.

You can now use the visual tools to define the XML Schema, or you can switch to the source view, using the tabs at the bottom left of the main pane.  I won’t provide all the steps to define the XML Schema using the graphical editor here, as it is a bit off topic.  Rather, I will just give you the source that you can copy and paste into JDeveloper.  When you have copied it in, you can switch back to the design view, and it should look like this:

Here is the XML Schema source to copy and paste:

<?xml version="1.0" encoding="windows-1252" ?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns="http://www.example.org"
  targetNamespace="http://www.example.org"
  elementFormDefault="qualified">
  <xsd:element name="expenseClaim">
    <xsd:annotation>
      <xsd:documentation>
        A sample element
      </xsd:documentation>
    </xsd:annotation>
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="employeeNumber" type="xsd:string"/>
        <xsd:element name="expenseDescription" type="xsd:string"/>
        <xsd:element name="expenseLineItems">
          <xsd:complexType>
            <xsd:sequence>
              <xsd:element name="expenseDate" type="xsd:date"/>
              <xsd:element name="expenseAmount" type="xsd:decimal"/>
              <xsd:element name="expenseReason" type="xsd:string"/>
            </xsd:sequence>
          </xsd:complexType>
        </xsd:element>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
</xsd:schema>

Now that we have defined our data item, we are ready to go on and define our human task.  In this example, the human task will obtain an approval (or rejection) for a given expense claim, represented by this data item we have just defined.

To create the human task, we return to the composite assembly diagram, and drag a Human Task from the palette on the right, and drop it on to our composite.  A dialog box will open to collect more information:

I called my human task “ApproveExpenseClaim.”  Note that there is an option to create SOAP bindings.  Doing so would enable this task to be accessible from outside of the composite that it belongs to.  We do not want to do this right now.  Just click on OK to finish.  You should now see the new human task on the assembly diagram, as shown below.  Human tasks are shown in green.

Double click on the human task to open up the human task editor, where we can provide more details about the task, as shown below.  The first page (“General“) lets us specify a title and description for the task.  I have left all of the other fields at their default values.  Note that the Outcomes field is used to set the list of allowed outcomes for this task.  These can be completely arbitrary and as many or as few as you like.  I have kept the defaults, “Approve” and “Reject.”

On the Data page we can add information to the “payload” of the task.  These are the data that the task will present to the user/approver to assist them in completing any necessary manual work, choosing the correct outcome and also there is an option to allow the user to make changes to these data.  We are going to add just one data item, which we will define using our expense claim type.  Click on the little green plus sign to add a data item to the payload, and choose Add other payload.

The dialog box allows us to choose the type for this data item.  Leave the selection on Element and click on the little magnifying glass to the right of the Element field.  Note that we are not selecting the Editable via worklist checkbox at this time.  If we were to select that checkbox, it means that users would be able to update this data item when they are processing this task.

A popup box allows us to select the type for the data item.  We want to look in our Project Schema Files, in the file we created earlier, ExpenseClaim.xsd, at the type called expenseClaim.  Select it and click on OK.

The next page, “Assignment“, allows us to set the routing information for this task.  The simplest case, which we are going to use now, is to send it to a single person for processing.  There are many other options available that we will explore in subsequent posts.  For now, click on the <Edit Participant> box to highlight it, and then click on the Edit button.

The popup allows us to set the user or group to route the task to.  Again there are various options available, and we are going to select the simplest in this example. Click on the green plus and select Add User to add a user for the task to be routed to.

You may not have a lot of users defined in your test environment, but the user weblogic will always be present, so let’s use that one.  Enter weblogic in the value field as shown.

Once more, you may notice there are various other options, including the ability to provide an expression to work out the user/group dynamically at runtime.  Scroll down in this window and we will set an expiry time for the user.  Open up the Advanced settings as shown.  Tick the checkbox for Limit allocated duration to: and set a time period.  I chose 5 minutes for this example.  This is long enough to give us time to look around, and not too long that we will get tired of waiting for it to expire.

This setting means that the user weblogic will get 5 minutes to process this task.  If they do not process it in this time, it would move on to the next person in the list (if there were one).  Click on OK to continue.

That is enough human task definition for now.  We have set up a fairly ordinary or basic human task.  In later posts, we will explore the more advanced options that are available in human tasks.

Now, let’s create a process that uses this human task.

Return to the composite assembly diagram and drag a BPEL Process from the palette on to the composite.  When you drop it, a dialog box will appear where we call fill in some more details.  I called my BPEL Process “ExpenseClaimProcess.”  Don’t press OK just yet!

We want to set the input for this process to be an expense claim, using the data type we defined earlier.  To do this, we click on the little magnifying glass to the right of the Input field in the dialog box.  This will open a Type Chooser, just like the one we saw earlier when we were adding a data item to our human task.  Choose the expenseClaim type again, as shown, then press OK in the Type Chooser, and then OK again in the Create BPEL Process dialog box.

Now you will see your BPEL Process along with the Human Task on the composite assembly diagram.  BPEL Processes are shown in blue.  You may also note that the BPEL Process is connected to an interface in the Exposed Services part of the diagram.  This is because we accepted the default selection of the Expose as a SOAP Service setting in the Create BPEL Process dialog box just a moment ago.  This creates a web service interface that allows the process to be accessed from outside the composite.  We will use this interface later on to test the composite.  For now, let’s double click on the BPEL Process to open it up and provide some details.

When the BPEL Process opens in the editor, you will see the graphical representation of the process in the main pane, as shown below.  You may notice that the palette changes to show items that make sense in a BPEL Process.  There is also a Thumbnail view that makes it easier to navigate around large processes.

Because we set the input of the process to our expenseClaim type, the process will already collect an expense claim for us when it is started.  We will see this later on.  So the next step in our very simple process is going to be to use the human task to get an approval for this expense claim.  To do this, we drag a Human Task from the palette and drop it into our process right between the receiveInput and the callbackClient.  When you drag the Human Task from the palette, a little drop target will appear in between these two activities.

When you drop the Human Task in to the process, a dialog box will appear, as shown below, where you can select which task to use.  Select the ApproveExpenseClaim task that we defined earlier.

Some additional fields will appear now (based on the task that you selected).  Provide a Task Title as shown below.  We also need to tell it where to get the task’s payload variables from.  Click on the … button beside the expenseClaim parameter (highlighted in the red rectangle).

In the popup box, we select where the data will come from.  We want to get the expense claim that was passed into the process as its input.  This is in the variable called inputVariable, as shown in the diagram below.  This variable was automatically created for us by the wizard when we created the BPEL Process.  Highlight the variable as shown and press OK.

The Create Human Task dialog should now look like this:

Press OK to return to the process.  You may notice that the final activity in the process has a little yellow exclamation point marker on it, indicating a warning.  In this case, we are returning a variable that has not been initialised yet.  We can fix this by setting a value in the output variable.  Let’s use the outcome of the task.  This will be “APPROVED” or “REJECTED” depending on how the task is processed by the user.  To assign this value to the output variable, we use an Assign activity.  Drag an Assign from the palette and drop it in the process right before the callbackClient activity as shown.

Double click on the Assign to open its settings, which appear as in the diagram below.  Click on the green plus to add a new Copy Operation.

A Copy Operation is used to copy data from one variable to another.  In the popup box, you can select the data to be copied.  On the left hand side (the source) navigate to the task:outcome.  The full path is shown in the diagram below.  On the right hand side, navigate to the result in the outputVariable.  Check your paths against the diagram, then press OK to close the Create Copy Operation dialog, and then OK again to return to the process.

Now our process will have no more errors or warnings.  If you wish, you can click on the build icon to check.  This is the small icon in the task bar (right under the menu bar) which has two little green arrows pointing down.

The Human Workflow Engine provides a fairly comprehensive out-of-the-box web user interface, which we will see later.  This interface includes the option of having a custom details page for each task.  On this page you can display anything you wish to.  Typically, you would want to display information about the task, perhaps the path it has already followed to get to the current approver, the data included in the task, maybe some documentation or instructions, and so on.

For this example, we will go ahead and generate the default details page, and deploy it as is.  This will let us see what we get “out-of-the-box,” with no additional effort.  In later posts, we will look at how to build on this to include additional functionality, e.g. multiple screens/pages, or including a scanned document.  For now, right click on the human task icon in the process (as shown below) and select Auto-Generate Task Form… from the popup menu.

The task forms are kept in a separate project, as they have different dependencies and deployment requirements.  You need to provide a name for this project.  I called mine “TaskFormForExpenseApproval.”

When you click on OK, several actions will be taken, including creating the new project, and all of the necessary files.  This can take a few minutes on some machines, so you need to wait until it is done.  When it is finished, you will see a screen like this:

Now is an excellent time to select Save All from the File menu, to make sure all of your work so far is saved!

Once that is taken care of, we are ready to deploy our work to our server and test it.  We need to do two deployment actions – one for the task form we just created, and one for the composite.  In a real production environment, these may be to different servers.  In my case I have a single server set up on the same machine as JDeveloper.  I have already set up the connections in JDeveloper to be able to deploy to the servers.  You should do this now if you have not already done it.

To deploy the task form, you need to click on the Application pulldown menu.  This is done by clicking on the little icon to the right of the project name as shown in the diagram.  You can also use the Application menu in the menu bar.  Either way, you then select Deploy and then TaskFormForExpenseApproval…

The deployment wizard will open.  Select Deploy to Application Server and then click on Next.

Select your application server connection from the list.  Make sure you deselect the option to Deploy to all server instances in the domain.  Not all of the server instances in a domain will necessarily have the same configuration, libraries, etc. so we want to choose just the one server instance that we want to deploy to.  Click on Next.

JDeveloper will connect to the server and retrieve a list of server instances.  You want to select your SOA Server instance.  In a default install, it will most likely be called soa_server1.  Then click on Next.

A summary page will display, like the one below.  Click on Finish to start the deployment.

You can watch the deployment progress in the Deployment Log, as shown below.

Next, we will deploy the composite.  This is done by right clicking on the composite project (SimpleTask) and selecting Deploy then SimpleTask… from the popup menu.

A similar deployment wizard will start.  Again, we select Deploy to Application Server and then Next.

As this is our first deployment of this composite, we can take the defaults on the next page.  If you need to deploy it again, you will need to provide a new revision ID, or check the box next to Overwrite any existing composites with the same revision ID.  Click on Next.

Select your application server connection and click on Next.

Select you soa_server1 instance and click on Next.

Review the summary page and click on Finish to start the deployment.

You may be prompted to log on to the server, if this is your first deployment in this JDeveloper session.  If so, provide the appropriate details and click on OK to continue.

Again, you can review the progress and results in the Deployment Log window as shown below.

Now that we have completed the deployment, we are ready to test our composite and the human task!

We can start an instance of the composite using the test facility in Oracle Enterprise Manager.  This is accessible on the server using the address http://server:7001/em.  You will need to change server to the name of your server.  You will see a page as shown below.  You need to use Internet Explorer 7+ or Firefox 3+ to access Enterprise Manager.  Chrome and Safari seem to work quite well too.  Log on to Enterprise Manager as shown below.

In the menu on the left hand side, navigate to SOA and then soa-infra.  You will see a screen like the one below.  Notice on the right hand side, in the Deployed Composites area, you will see SimpleTask.  Click on the name SimpleTask to view more details of this composite.

You will see a screen like the one below.  Click on the Test button near the centre at the top of the main area, just under the blue header.  This will allow us to start a test instance of the composite.

The test form is generated for us automatically from the input data structure, so we can just fill out the form.  Notice that there are a lot of options for security, quality of service, etc.  We don’t need any of these right now, so just scroll down until you find the input data.

Fill out the input data as shown below, then click on the Test Web Service button to start a test instance of the composite.  The button is in the lower right corner, you may need to scroll down further to see it.

When the instance has started (should be practically immediately) you will see a screen like this.  Click on the Launch Message Flow Trace link so that we can see some information about the instance of the composite.

This screen is telling us that in this particular instance of the composite, it was started using the expenseclaimprocess_client_ep interface, that is the SOAP interface we saw in the assembly diagram earlier, ir is running the BPEL Process called ExpenseClaimProcess, and that process has started a Human Task called ApproveExpenseClaim.  Let’s click on the ExpenseClaimProcess to see details of the BPEL Process.  Click on the link.

Here we see the Audit Trail view of the BPEL Process instance.  You can see from this view that the instance is waiting for a reply from the Human Workflow engine to let it know that the human task was completed.  Click on the tab labeled Flow to see a graphical view of the process instance.

The graphical view provides the same information.  You can click on the activities to see detailed information about each one.

Now, let’s use the out-of-the-box human workflow web user interface to view and process this task!  This is the moment of truth!

The “Worklist” application is available at http://server:8001/integration/worklistapp.  Again, change server to the name of your server.  Log in as user weblogic (remember that we assigned the task to user weblogic earlier.

Here we see the standard worklist application interface.  You will notice that our Approve Expense task is listed in the inbox for the user weblogic.  Click on the line to view more details.  Note that the first time we do this for a particular type of task, the system needs to compile some JSP files, so there will be a short delay.  The second and subsequent times we view details for a task of this type, there will be no such delay.

The task details appear in the lower half of the screen, as shown below.  You may want to adjust the divider so you can see more of the details page at once.  You can also scroll to view more information.

This task details page that we are viewing now in the lower right hand pane is the task form that we generated earlier and then deployed.  What you see here is what you get with no additional effort.  If we wanted to customise the look and feel of this details page, or add extra information, then we would need to do a little more work.  We will see examples of this in future posts.  There is also a lot more out-of-the-box functionality in this application that we will look at in later posts.  Feel free to explore yourself now, but remember that you only have five minutes before your task will expire!

When you have seen enough, click on the Approve button to approve this task.  The screen will refresh and you will see that your worklist is now empty.  If you want to explore further, try using the pulldown filters at the top of the worklist to view completed tasks too.

When you are ready, return to the Enterprise Manager window, which we left on the graphical representation of the process instance.  We would expect that now we have processed the human task, the BPEL process should have moved on to completion.  Click on the Audit Trail tab again to refresh the window.

If you scroll down, you will see here that the human task was completed, and the final “callbackClient” activity was executed and the process instance completed.  You can open up the payload of the callbackClient as shown in the diagram above and you will see the outcome of the task in the outputVariable.

This completes our introduction to the basic features of the human workflow engine, and how to design tasks and use them in processes.  There are many more features that have not been touched on at all in this post.  You will have seen indications of many of them if you were watching carefully and reading the other fields as you worked through this example.  We will explore more of these features in additional posts.  If there are any that you are particularly interested in, feel free to comment on this post and let us know!