Functional Testing Business Processes In Oracle BPM Suite 11g

Over the last couple of projects, I have been trying to establish a set of methodologies around initiation, development, deployment and management of business processes using Oracle BPM Suite 11g. In a series of posts, I will be taking about a lot of problem areas that can be effectively tackled in order to deliver a highly successful BPM project using this technology. The areas I intend to cover are around design and modelling best practices, team development, delivery methodologies, testing, troubleshooting, automation, performance tuning and operational management to name a few. However in terms of priority and the nature of pain experienced in each of these aforementioned areas, I am of the opinion that a great chunk is attributed to testing and maintaining code quality. Business processes are in constant need to be truly dynamic more than ever so that planned as well as ad-hoc changes can be promoted seamlessly. Also with Oracle BPM Suite 11g promising greater involvement of business users in terms of making deployable changes to the processes, ensuring that functionality and quality of the build/changes is maintained is very crucial. In the previous blog post, I had elaborated on unit testing strategies for business processes and methods of achieving them from the Oracle BPM Suite 11g studio. Proper unit testing is important in terms of validating that the core logical outcomes of a business processes are executed as expected. This ensures that all sequence flows and paths in a business process are tested and conformant. The post can be accessed here:

https://beatechnologies.wordpress.com/2013/05/05/unit-testing-business-processes-in-oracle-bpm-suite-11g/

However, apart from testing the basic process paths a lot of other things demand testing too. Business processes can populate data in downstream systems, integrate with services, create events, send notifications, assign workflow tasks which may have their own lifecycle, etc. From a quality perspective all of these steps must be verified too. The overall functionality of the business processes must be thoroughly tested to determine their reliability before being deployed to the actual IT infrastructures. Organizations do invest in quality measures to evaluate features of business processes by employing a comprehensive testing strategy, involving analysts, developers, functional testers and business users. However they begin to invest in test automation very late in the project lifecycle. This poses a significant threat and concern, particularly when the business processes are continuously changing and evolving. An increasing pace of business process changes as well as applications growing more complex means that many functional testing teams are reaching the breaking point. Change management becomes difficult as there is always a risk of introducing new bugs down the way. As much as we all would like to have agility, the process is defeated by having improper developer operations. Having a regression functional testing suite very early in BPM project development cycle is, by my opinion a must have thing for any successful and timely implementation. More often than not, it is not the choice of technology that is responsible for this but rather the lack of some important know-how’s.

Typical Problem Areas and how Automating Functional Testing can help

In my interactions with different project teams, here are some typical questions they have, especially with respect to testing business processes in Oracle BPM Suite 11g.

• Is it possible to really approach functional testing early in the project cycle considering the nature of composite applications involved (business processes, services, rules, etc.).
• Human tasks components in business processes need to have user interfaces (which may have their own development lifecycle). How can functional testing be achieved before a fully operational UI?
• Are their any developer tools, approaches or frameworks that can be utilized to automate functional testing?
• What kind of a functional testing strategy is suitable, cost efficient and good to contain a wide variety of problems in the project lifecycle?

If we begin to investigate the possibilities, they may be endless. I, am particularly aware of many custom products which promises to take care of all of these. However hey tend to be expensive, have a steep learning curve and may not always fit the bill. This act as a big deterrent. However, in this article, I am keen on presenting an approach that is quick, easy, developer friendly and can be easily catered in the development phase of the project. The best way to begin with functional testing is to base it on the business process design. Model driven functional testing ensures that critical processes and their paths are covered and that any variation of those tests can easily be amended and rerun without adding to significant time to the test cycle. Functional testing can start earlier and better quality tests are produced and maintained in a test repository. This can then be part of the continuous build and integration iterations to ensure sufficient test coverage in accelerated delivery cycles. A part of model driven testing strategy was described in details with respect to ascertaining the cyclomatic complexity factor of the business processes and deriving test cases based on that. This approach is a very good starting point, especially because this can be used to build unit tests too. Once the basic process paths are determined, the functional test suites can incorporate a lot of test steps to cover the functional aspects such as validate business logic and rules, verify data across systems, check events and notifications, etc..

With all this being said, however, automation of functional testing will only be successful if an organization’s underlying quality fundamentals are solid and everyone clearly understands how testing can continuously support process iterations. Another big advantage to automate early is potential time savings. Considering that multiple stakeholders will need to repeat their testing task, every time something changes, doing them manually becomes a burden sooner or later. Have a look at the sheet I’ve compiled based on various time and frequency of performing functional tests and the effort involved in each case.

The columns marked in green in the above sheet reflects the most likely scenarios in terms of the amount of time spent on testing in various Oracle BPM Suite 11g projects. The effort involved in manual testing can range from 20 days to 4 months for a very simple and less frequently changing business process to a complex and often changing business process. This effort does not accounts for test planning but simply reflect the time spent in test execution. The columns in red represents scenarios that can be applicable for certain project types too and in those cases the amount of time spent in manual testing can be even 8 months. This offcourse is under the assumption that all quality standards of software functional testing are maintained. 

Approach and Tooling

As indicated before, there are many players in this field providing varied approaches and option. This article will not debate their merits here. In the course of my involvement with BPM projects, I seems to incline towards SOAPUI. This is particularly due to the fact that it is pretty inexpensive (there is also a freeware if ~$350 license cost seems significant) and does most of the basic functional testing that can be considered acceptable from a quality perspective. It is fairly straight forward too and the learning curve is minimal. Chances are also high that in most projects there will be developers with considerable amount of experience using SOAPUI, if they have been involved in a SOA project in the past.

Having said that, this article will talk about how to plan and implement a comprehensive and automated functional testing suite for business processes developed using Oracle BPM Suite 11g.

The Employee Expense Approval Business Process

I will use the same employee expense approval business process that was discussed in my previous blog. This process has primarily all the ingredients that any complex business process has i.e it is fairly unstructured, have business rules, human workflow components, arbitrary cycles, gateways, events and writes to external applications.  As a refresher, the process map looks like below in the JDeveloper studio.

Technology Prerequisite(s)

The modelling workspace and the version of Oracle BPM Suite used in this demonstration is 11gR1PS5 i.e 11.1.1.6. The version of SOAP UI being used is 4.5.0 (excuse my backwardness in terms of working with the latest versions of these tools). I use the open source version of SOAPUI but for better productivity and ease of use you may consider using the Pro version too. A connection to the database is also necessary to be able to create certain database objects that the project requires. The version of the database, though, can be any generic with the only exception that it has to be Oracle database.The concepts discussed in this blog are however generic and applicable to any version of the above products.

Project Setup

In order to import the implemented expense approval project in JDeveloper, obtain the composite (ExpenseApprovalComposite.zip), unzip it and open the application (.jws) file in the studio. As can be noticed from the BPMN mode, the process populates some database tables with expense and payment records at various stages. To be able to deploy and execute the project, a database schema and certain tables needs to be created. On the Weblogic server side, there is a need to create a data source and add a new connection factory to the database resource adapter.

Doing this set-up is pretty simple. I have created some SQL and ANT scripts that can do all of this. Follow the instructions below to execute these scripts to create the required resources.

Create the Database Artefacts

• Download and unzip the DatabaseSchema.zip file in a local directory.
• Open the edit the create_expense_structure.bat and simply substitute the sys password with the one for the database you are using. This script assumes that a local XE flavour of the database is running. If this is any different then modify the bat file accordingly.
• Open a command prompt and cd to the directory containing the bat file. Simply run the batch file in the prompt.
• This will create a database user “EXPENSE” and two tables in it called EMPLOYEE_EXPENSE_PAYMENT and EMPLOYEE_EXPENSE_RECORD.
• Verify that the scripts ran okay and the database artefacts were created.

Create the Weblogic Server Artefacts

• Unzip the ResourceAdapter.zip in a local directory.
• Open the build.properties file and substitute the middleware home location with the one being used. Also modify the values of the database server, weblogic server, domain, connection credentials etc. Properties that needs to be changed are marked in the build.properties file through comments.
• Open a command prompt and cd to the local directory where the contents of the .zip file are placed.
• Type ant makeDataSource to create the required datasource in the weblogic server to connect to the EXPENSE schema created in the step before.
• Once the build is successful type ant createResourceAdapterEntries in the same command prompt.
• This will create the database adapter connection factory and update it with the datasource created before. It also updates the DbAdapter deployment plan to commit all these changes onto the server.
• Verify that the script executes successfully. If it doesn’t then there may be a problem in substituting values in the build.properties file.
• As a last resort, you may configure these resources manually on the server or alternatively send me your configuration files along with the error(s).

Creating the Functional Test Suite

Once the project has been set-up and the required artefacts are created, it is time to look into creating a functional testing suite for the expense approval processes. Once we create the functional tests, they can be used for regression every time there are changes made to the business processes. A good practice is to always accept any changes when it is accompanied by a functional test case and when all existing test cases pass the regression. However the dynamics here may be dependent upon the level of business user’s involvement in creating ad-hoc changes to the business process after it is deployed. If business users are empowered to make dynamic changes, then it cannot be expected of them to create/modify the functional test cases supporting their changes. This situation demands a change control process in place. I am of the personal opinion that to ensure the quality of business processes running on the production environment, changes must always be supported with regression. Whether business analysts and process analysts create these tests or whether they get it done from developers is a matter of having a governance around the change control.

Nevertheless it is pertinent to have an initial set of functional tests. If you managed to read the previous blog post on unit testing business processes in Oracle BPM Suite 11g, you must have noticed how we employed cyclomatic complexity to determine the number of unique test cases required to provide a cent percent test coverage. From the functional testing perspective, we will still create the same number of test cases but also have a series of test steps to validate that the business process is indeed doing all the right things.

As determined before the following test cases shows the various routes a process can take from all the conditional nodes. To ensure the utmost quality, we will have as many functional test cases too.

Test Case 1: Submit, Auto Approve, Finance Approve, Approve
Test Case 2: Submit, Auto Approve, Finance Reject, Refer
Test Case 3: Submit, Refer, Manager Approve, Finance Approve, Approve
Test Case 4: Submit, Refer, Manager Approve, Finance Reject, Refer
Test Case 5: Submit, Refer, Manager Reject, Reject

The following section will demonstrate a series of test steps that will be created to fully functionally test one of the test cases (here Test Case 3: Submit, Refer, Manager Approve, Finance Approve, Approve). Other test cases can be created in the similar lines.

• Deploy the ExpenseApprovalComposite to a BPM server and grab its wsdl  from the enterprise manager (since the business process has a message start event it can be invoked as a web service)
• Launch soapUI and create a new soapUI project. Put ExpenseApprovalTest as the project name and copy the wsdl localtion in the Initial WSDL/WADL field. Also check the option to create sample requests for all operations.

• This will create a soapUI project in the existing workspace. Now right click on the project and click on New TestSuite to create a new test suite inside the project. Name it as Expense Approval Functional Tests.
• A test suite can have multiple test cases that can be run either individually or all together as part of the test suite (either sequentially or in parallel). Once the test suite is created, right click on it to create a New TestCase inside it. Name the test case as T3_Refer_ManagerApprove_FinanceApprove_Approve.

• A test case is constituted of a series of test steps that are executed in sequence one after another. Testing a business process will involve initiating the business process through the message based event, capturing data in the human tasks, simulating user behaviour on the workflow screens and verifying that once the process is completed, it is in the right state, populates the right statuses in the end systems and follow the expected process path.
• A test case in its due steps may need to refer some constant values or store values intermittently to be used in later steps.  soapUI allows creation of global, test suite level as well as test case level properties. While properties at the test suite level are more appropriate to hold any constants (or pass them between multiple test cases), properties in the test cases are used primarily for passing information between multiple steps. Create the following properties at each level. You will notice that the test suite properties have been set to some constant values.

• The properties can then be accessed as variable using the below construct.

${#TestSuite#TASKSTATE}

${#TestCase#CONVERSATION ID}

• It is commonly believed that a business process with human tasks will need a functional user interface in order to test it. However it is not true. Oracle BPM Suite 11g offers both Web Services as well as JAVA based API’s to interact with the workflow tables. The operations in these API’s can be used to search and query for tasks, update task payloads and outcome, attach comments and attachments etc. Access the following posts to be able to get a glimpse of the human workflow API’s.

http://beatechnologies.wordpress.com/2011/08/24/using-java-apis-for-oracle-human-workflows

http://beatechnologies.wordpress.com/2011/08/22/oracle-human-workflow-web-service-apis

• In this article I will be using the Web Service API’s to simulate the human tasks when building the functional test steps. The first step in the test case is to create a unique identifier (random number) that can be used to set the conversation id while invoking the business process. Setting up a conversation id is important as the composite/component instances ID’s can be determined by querying the dehydration store against it. In soapUI a Groovy Script based test step can be used to generate a random number. Name this step as Create Conversation Identifier and paste the following groovy code snippet in the code editor.

testRunner.testCase.setPropertyValue("CONVERSATION ID", "${java.util.UUID.randomUUID()}")

log.info(java.util.UUID.randomUUID())

• The groovy script dynamically populates the CONVERSATION ID property in the test case with the uniquely generated number.
• Add a new SOAP Test Request and name it as Submit Employee Expenses – submit expense application. When needing to specify the operation to invoke select ApproveEmployeeExpenseBinding –> submitExpenseApplication from the available options. As a matter of best practices, I typically append the name of the process model object that is being interacted with in the name of the test step. This is important to maintain a visibility of which event in the process is invoked or which human task is updated/actioned.

• Copy the following payload to trigger the business process. The combination of business unit and expense total will force the business rule activity in the business process to send this instance to a manager review.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:app="http://www.rubiconred.com/ApproveEmployeeExpense" xmlns:empl="http://www.rubiconred.com/bpmtest/empl">
<soapenv:Header/>
<soapenv:Body>
<app:submitExpenseApplication>
<empl:Expense>
<empl:Employee>
<empl:EmployeeID>988977698</empl:EmployeeID>
<empl:FirstName>Arrun</empl:FirstName>
<empl:LastName>Pareek</empl:LastName>
<empl:Email>arun.pareek@rubiconred.com</empl:Email>
<empl:PhoneNumber>0424987673</empl:PhoneNumber>
<empl:ManagerID>6312313</empl:ManagerID>
<empl:DepartmentID>132313</empl:DepartmentID>
<empl:BusinessUnit>3</empl:BusinessUnit>
</empl:Employee>
<!--1 or more repetitions:-->
<empl:ExpenseList>
<empl:Amount>80000</empl:Amount>
<empl:Type>Travel</empl:Type>
<empl:Date>2013-02-06</empl:Date>
<empl:Justification>Travel on Business</empl:Justification>
<empl:Authoriser>Matt</empl:Authoriser>
</empl:ExpenseList>
<empl:ExpenseList>
<empl:Amount>40000</empl:Amount>
<empl:Type>Travel</empl:Type>
<empl:Date>2013-02-07</empl:Date>
<empl:Justification>Travel on Business</empl:Justification>
<empl:Authoriser>John</empl:Authoriser>
</empl:ExpenseList>
</empl:Expense>
</app:submitExpenseApplication>
</soapenv:Body>
</soapenv:Envelope>

• It is also very important to note here that the business process, by the virtue of message based start and end events, is implemented as an asynchronous web service. When the process completes it will send an asynchronous call-back to the initiator at a call-back address. Basically Oracle BPM Suite 11g supports WS-Addressing. The conversation id generated in the previous step can be used as the unique correlation identifier when invoking the submitExpenseApplication operation. Also the initiator can define a call-back address (Reply To in the addressing header) where the engine can send the call-back response.
• In soapUI WS-Addressing related headers can be added by clicking on the WS-A tab in the test step. The WS-A addressing enabled option has to be selected and the must understand flag is to be set to TRUE. The MessageID field is populated with the CONVERSATION ID test case property. Also provide a reply to address like below to let the BPMN engine register the the call-back address for this instance. This will be used in a future step.

http://rubiconred-pc:2222/ApproveEmployeeExpensePortTypeCallBackBinding

• The first test to be performed is to be able to successfully determine whether the soap request was successfully delivered to the end point. Since it is an asynchronous request, the response is not received in the same thread. Hence the only way to determine a success is to verify that the HTTP status code received is correct. To do that, add a status assertion for a Valid HTTP Status Code. Enter 202 (Accepted) as the expected status code. This status code reflects that the request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed or fault out when processing actually takes place. The 202 response does not requires an initiator’s connection to the server persist until the process is completed.

• The above test step will create an instance of the expense approval process which can be seen and verified through the enterprise manager.  The next test step to add is to retrieve the composite instance, ecid and the composite state from the CUBE_INSTANCE and COMPOSITE_INSTANCE tables in the dehydration store against the conversation id. The conversation id supplied by the initiator is stored in the CUBE_INSTANCE table. This will correctly grab the instance metadata for the instance that was created in the test steps above.
• Add a new JDBC Request test step and name it as Retrieve Composite Instance ID. A JDBC test step will require a JDBC driver and connection string and an SQL query to be specified. But before this can event work, you will need to copy the ojdbc5.jar under the $soapUIHome/bin/ext folder. This jar facilitates the connection to an oracle database from soapUI. The following values can be specified for the different properties in the JDBC request test step. Be careful to substitute the database connection details with the ones reflecting your environment.

Driver : oracle.jdbc.driver.OracleDriver
Connection String : jdbc:oracle:thin:ps5_soainfra/welcome123@localhost:1521:xe
SQL Query :SELECT COMPOSITE_INSTANCE.ECID, COMPOSITE_INSTANCE.ID, CUBE_INSTANCE.COMPOSITE_NAME, CUBE_INSTANCE.COMPOSITE_REVISION, COMPOSITE_INSTANCE.STATE FROM COMPOSITE_INSTANCE,
CUBE_INSTANCE WHERE COMPOSITE_INSTANCE.CONVERSATION_ID =CUBE_INSTANCE.CONVERSATION_ID AND CUBE_INSTANCE.CONVERSATION_ID= '${#TestCase#CONVERSATION ID}'

• The SQL query returns important metadata with respect to the composite instance that is created. soapUI allows adding assertions to each test steps in a test case. Assertions are a very good way to add functional validation at each test steps. The following screenshot shows the four different assertions that are added to this test step. The composite name and version are validated against the values of these properties specified in the functional test. The state value of 0 indicates that the process instance has been initiated.

• The instance might not be created immediately and available to be queried against the dehydration store. It may take a couple of seconds for the instance to be initiated. It may be required to add a Delay test step in between the SOAP and JDBC request test steps.
• The values retrieved from the JDBC request test step and the original payload passed in the SOAP test request can be saved to the test case properties so that they can be used in the next test steps. A Property Transfer test case can be added for this purpose. Name the step as Capture Process Properties and add four test step properties viz. ECID, INSTANCE ID, PAYLOAD and EMPID. For each of the properties the appropriate values can be captured by specifying the source test step, the variable (request, response or raw request, etc.) and the target test step property. When the property transfer test step is executed the test suite properties will have the most current values depending upon the payload entered and the results retrieved by querying the database schemas.

• Once the process is triggered/initiated it creates an entry in the EMPLOYEE_EXPENSE_RECORD table with the relevant employee and expense details. The EXPENSE_APPROVAL_STATUS column at this stage should be marked with a SUBMITTED status, assuming it is used for tracking the state of expenses. From a functionality standpoint it should be verified whether this is indeed the status. To be able to do that is soapUI will mean creating another JDBC Request test step. Name this as Verify Expense Record – Create Expense Record (here Create Expense Record is the name of the BPMN activity in the process model which executes the database update).
• In the JDBC test step, the connection string this time should be specific to the Expense schema that was created initially. The SQL query to fetch the record for a given employee is determined uniquely by the employee id and the record reference (populated with ECID).

SELECT * FROM EMPLOYEE_EXPENSE_RECORD WHERE EMPLOYEE_ID ='${#TestCase#EMPLOYEEID}' AND RECORD_REF='${#TestCase#ECID}'

• In the same test step, assertions can be added to verify the expense approval status and also the expense approver, if applicable. A JDBC status validation assertion is also added as this is something that should preferably added to each JDBC Request step.

• For this particular test case, the business rule will determine that a manager approval is required before the expense is presented to the finance user. The business process instances initiates a workflow task that is available to the designated user in his in-tray. In the most basic scenario the task is available to be be actioned by the user(s) assigned to the process swimlane role.
• At this stage if the audit trail of the instance is viewed it will correctly represent that the process has initiated and is waiting at the Approve Employee Expense human task activity.

• Interacting with the task is very easy and straight forward. Fortunately there is no need for a properly designed UI to be able to test the user interactions with the business process. Oracle BPM Suite 11g provides Human Workflow web services that can be invoked with the proper operations to simulate the UI behaviour.
• When an instance reaches any human task activity the human workflow engine initiates a task with the appropriate task metadata along with a unique taskId and number.
• The workflow engine captures this metadata in the WFTASK table in the dehydration store. Querying this table against the task definition name, composite instance id and the ECID will return a task identified for the initiated task.
• Create a JDBC Request test step yet again and name it as Retrieve Task Identifier – Approve Employee Expense. Use a connection string specifying the details of the SOAINFRA schema and the following sql query to uniquely determine the task identifier for the initiated human task.

SELECT WFTASK.TASKID FROM WFTASK WHERE WFTASK.TASKDEFINITIONNAME='${#TestSuite#MANAGERTASK}' AND WFTASK.ECID = '${#TestCase#ECID}' AND WFTASK.STATE = '${#TestSuite#TASKSTATE}' AND WFTASK.COMPOSITEINSTANCEID= '${#TestCase#INSTANCEID}'

• The task identifier that is fetched as a result of the sql query will be used in the future test steps to query and update task details using the workflow APIs. In order to use it forward, a property transfer step (Capture Human Task Identifier – Approve Employee Expense) has to be created to copy this value to the TASKID property of the test case.

• This task id will now be used in the forthcoming test steps to operate on the human task. In order to do so, first of all we will need to add two more WSDL files to our soapUI test project. These WSDL files can be located at the following end points after substituting the appropriate values for the host and port where the soa server is running. This will add all the operations in these services to the soapUI project catalogue.

http://<host>:<soaserverport>/integration/services/TaskQueryService/TaskQueryService?wsdl

http://<host>:<soaserverport>/integration/services/TaskService/TaskServicePort?wsdl

• Once the WSDLs have been added, add another SOAP Request test step. When prompted for a name put Get Task Details from Task Indetifier – Approve Employee Expenses (long but very descriptive, pinning down the actual human task activity in the process model for which this test step is performed).
• Select the getTaskDetailsByID operation in the TaskQueryService wsdl in order to retrieve the task details by providing the task identifier. Invoking this operation also requires appropriate credentials. The task identified is captured in the test case property TASKID. The operation returns the entire human workflow task consisting of the payload as well as additional task metadata. In order to ascertain that all functionality requirements are met, a couple of assertions could be added. As this is a synchronous service invocation, add assertions for a valid soap response, schema compliance and that no soap fault is encountered. These assertions are available in the Compliance, Status and Standards tab of the Add Assertion window.
• Apart from the web service assertions, also verify that the task state is correctly set to a value of Assigned. Also verify that the task version reason is equal to TASK_VERSION_REASON_INITIATED confirming that the task is in an initiated state at this stage. These elements are child of the systemAttributes element in the task data and can be queried with the following XPath expressions.

/*:Envelope/*:Body/*:task/*:systemAttributes/*:state

/*:Envelope/*:Body/*:task/*:systemAttributes/*:versionReason

• The task metadata returned from the service call has a section called task payload. This represents the initial arguments passed to the human task when it is initiated. As part of a manager approval or any other interaction with a form based user interface, process participants may change data in the forms (editable arguments) after which they may action the task (reassign, delegate, approve, reject, suspend etc.). Depending upon the functional requirements of task management, we may have to create appropriate steps at this point and validate the behaviour. For instance, tasks may always be reassigned to a team leader who may then reassign them to actual participants who have to then action them. In this case a test step to invoke the reassignTask operation in the TaskService service may be required. This test case assumes that a team lead simply puts in his comments (which is part of the payload here and saved to the expense record table) and approves the expenses.
• Add a property transfer step and name it as Capture Human Task Payload – Approve Employee Expense. The purpose of this step is to take the task payload from the response of the previous step, modify the comments child in the approval status element (replace it with a value such as “Manager Approved”) and transfer this to the TASKPAYLOAD property in the test case. In this example, an XQuery function is used to achieve this however any other smarter way can be employed too.

• Once the payload has been modified (mimicking the user’s behaviour in the form), the task metadata has to be updated in the dehydration store so that the workflow engine is aware of the changes made. This can be done by passing the modified task data to the updateTask operation in the TaskService. Add another SOAP Request test step to call it as Update Human Task – Approve Employee Expense. Choose updateTask as the operation from the TaskService. soapUI will populate the default request but the service will work with only the credential of the user trying to perform the update and the task itself (which is now available in the TASKPAYLOAD property). Apart from the usual soap based assertions an important assertion to be determined here is the state of the verionReason element in the task. Verify that it is now modified to TASK_VERSION_REASON_UPDATED.

• The final step in moving this task out of the manager’s inbox is to emulate his action, which can either be approve or reject. Task outcomes can be committed to the workflow engines through the updateTaskOutcome operation in the TaskService. Once an outcome has been received by the human task engine it will send a call-back to the business process with the response, which is waiting for it at the human task step. The business process will then proceed ahead, update the expense record table with the status of manager’s decision and evaluate the manager’s outcome at the exclusive gateway. As we are interested in the scenario where the manager approves the expenses the business process will initiate a task for the finance approver.
• The operation only requires the outcome flag and the task identifier along with the user credential in able to submit the request. There is one important thing to be kept in mind in this test step. Only those users who have been mapped to the swimlane role to which the task is assigned or reassigned to can update the task outcome.

• Create another JDBC Request step to verify that the expense record is updated with the expected value.
• As the task moves to the Finance Approver’s inbox, the WFTASK table can be again queried to determine the task id corresponding to this task. The following query (similar to the one used before) can be used to retrieve the new task identifier. The only difference in this query is the TASKDEFINITONNAME filter, which basically have to be set with how the finance approval task is called.

SELECT WFTASK.TASKID FROM WFTASK WHERE WFTASK.TASKDEFINITIONNAME='${#TestSuite#FINANCETASK}' AND WFTASK.ECID = '${#TestCase#ECID}' AND WFTASK.STATE = '${#TestSuite#TASKSTATE}' AND WFTASK.COMPOSITEINSTANCEID= '${#TestCase#INSTANCEID}'

• At this point, a few of the test steps that were created to fetch the task id from WF task table, copy it to the test case TASKID, retrieve the task payload, modify it and then update the task outcome has to be repeated for the finance approval task too. To maintain visibility, append the name of the human task i.e Administer Expense Payment to each of these steps. After these steps are created the functional test case will reach a point where it has emulated all human steps in the business process, asserted the functional points, and verified that the instance is behaving as expected.

• Once a member of the finance approval team approves the expenses, notice that the business process model updates the payment register as well as the expense record tables. The business process then ends with a message based event viz. expense paid. This triggers an asynchronous call-back to the client calling the business process if it is waiting for one.
• As a next logical step in the functional testing scenario is to verify that the updates to the end systems has correctly happened and also to somehow receive the process end response to assert if it has the right status. It is also recommended to have some additional test steps to even verify that the instance state is marked as completed in the dehydration store to fully satisfy all functional aspects.
• To begin with these assertions, add a Mock Response test step in the test case and name it Receive Process Callback Response – expenses paid. Select the expensePaid callback operation from the ApproveEmployeeExpensePortTypeCallBackBinding interface.
• The port and the path has to be 2222 and ApproveEmployeeExpensePortTypeCallBackBinding respectively. This however depends upon what was entered in the original/initial soap request in the Reply To field. This step will automatically be populated with the callback response containing the approval status of the expense. Add the normal web services assertions to this test step as well an Xpath assertion to verify that the approval status is equal to FINANCE APPROVE

• It is also worth while to add a property transfer step to Capture the Expense Amount total and assign it to the EXPENSETOTAL test case property. This is done by summing all the amounts in the expense list submitted by the employee.

• As indicated earlier, the final steps in the test case is to create a couple of additional JDBC test steps to verify that the updates to the tables are consistent with the instance data by adding the necessary assertions.

• Optionally it can also be verified that the process instance has successfully completed. This can be queried against the dehydration store tables. The CUBE_INSTANCE and the COMPOSITE_INSTANCE table stores the process instance header and the state data. The state column has a numerical value which can be translated into a very informative physical state of the instance. The given query can be executed to retrieve and decode the status from these two tables.

SELECT (CASE

WHEN CU.STATE=0 THEN 'INITIATED'

WHEN CU.STATE=1 THEN 'OPEN AND RUNNING'

WHEN CU.STATE=2 THEN 'OPEN AND SUSPENDED'

WHEN CU.STATE=3 THEN 'OPEN AND FAULTED'

WHEN CU.STATE=4 THEN 'CLOSED AND PENDING'

WHEN CU.STATE=5 THEN 'CLOSED AND COMPLETED'

WHEN CU.STATE=6 THEN 'CLOSED AND FAUTED'

WHEN CU.STATE=7 THEN 'CLOSED AND CANCELLED'

WHEN CU.STATE=8 THEN 'CLOSED AND ABORTED'

WHEN CU.STATE=9 THEN 'CLOSED AND STALE'

WHEN CU.STATE=10 THEN 'NON-RECOVERABLE'

ELSE CU.STATE || 'UNKNOWN'

END) AS CUBE_INSTANCE_STATE, (CASE

WHEN CO.STATE=0 THEN 'RUNNING'

WHEN CO.STATE=1 THEN 'COMPLETED'

WHEN CO.STATE=2 THEN 'RUNNING WITH FAULTS'

WHEN CO.STATE=3 THEN 'COMPLETED WITH FAULTS'

WHEN CO.STATE=4 THEN 'RUNNING WITH RECOVERY REQUIRED'

WHEN CO.STATE=5 THEN 'COMPLETED WITH RECOVERY REQUIRED'

WHEN CO.STATE=6 THEN 'RUNNING WITH FAULTS AND RECOVERY REQUIRED'

WHEN CO.STATE=7 THEN 'RUNNING WITH FAULTS AND RECOVERY REQUIRED'

WHEN CO.STATE=8 THEN 'RUNNING WITH SUSPENDED'

WHEN CO.STATE=9 THEN 'CLOSED WITH SUSPENDED'

WHEN CO.STATE=10 THEN 'RUNNING WITH FAULTS SUSPENDED'

WHEN CO.STATE=11 THEN 'COMPLETED WITH FAULTS SUSPENDED'

WHEN CO.STATE=12 THEN 'RUNNING WITH RECOVERY REQUIRED AND SUSPENDED'

WHEN CO.STATE=13 THEN 'COMPLETED WITH RECOVERY REQUIRED AND SUSPENDED'

WHEN CO.STATE=14 THEN 'RUNNING WITH FAULTS, RECOVERY REQUIRED AND SUSPENDED'

WHEN CO.STATE=15 THEN 'COMPLETED WITH FAULTS, RECOVERY REQUIRED AND SUSPENDED'

WHEN CO.STATE=16 THEN 'RUNNING WITH TERMINATED'

WHEN CO.STATE=17 THEN 'COMPLETED WITH TERMINATED'

WHEN CO.STATE=18 THEN 'RUNNING WITH FAULTS AND TERMINATED'

WHEN CO.STATE=19 THEN 'COMPLETED WITH FAULTS AND TERMINATED'

WHEN CO.STATE=20 THEN 'RUNNING WITH RECOVERY REQUIRED AND TERMINATED'

WHEN CO.STATE=21 THEN 'COMPLETED WITH RECOVERY REQUIRED AND TERMINATED'

WHEN CO.STATE=22 THEN 'RUNNING WITH FAULTS, RECOVERY REQUIRED AND TERMINATED'

WHEN CO.STATE=23 THEN 'COMPLETED WITH FAULTS, RECOVERY REQUIRED AND TERMINATED'

WHEN CO.STATE=24 THEN 'RUNNING WITH SUSPENDED AND TERMINATED'

WHEN CO.STATE=25 THEN 'COMPLETED WITH SUSPENDED AND TERMINATED'

WHEN CO.STATE=26 THEN 'RUNNING WITH FAULTED, SUSPENDED AND TERMINATED'

WHEN CO.STATE=27 THEN 'COMPLETED WITH FAULTED, SUSPENDED AND TERMINATED'

WHEN CO.STATE=28 THEN 'RUNNING WITH RECOVERY REQUIRED, SUSPENDED AND TERMINATED'

WHEN CO.STATE=29 THEN 'COMPLETED WITH RECOVERY REQUIRED, SUSPENDED AND TERMINATED'

WHEN CO.STATE=30 THEN 'RUNNING WITH FAULTED, RECOVERY REQUIRED, SUSPENDED AND TERMINATED'

WHEN CO.STATE=31 THEN 'COMPLETED WITH FAULTED, RECOVERY REQUIRED,SUSPENDED AND TERMINATED'

WHEN CO.STATE IN (32,64) THEN 'UNKNOWN'

ELSE CO.STATE || ''

END) AS COMPOSITE_INSTANCE_STATE FROM CUBE_INSTANCE CU, COMPOSITE_INSTANCE CO WHERE CU.ECID=CO.ECID

AND CU.ECID='${#TestCase#ECID}'

AND CU.CMPST_ID='${#TestCase#INSTANCEID}'

• As a last step verify that the state in the cube instance table is CLOSED AND COMPLETED and COMPLETED in the composite instance table.

The test case is now complete in a way that it can successfully test all the major functionality of the business process. This increases operational as well as developer efficiency since continuous changes to business processes can be supported without too much worrying about them breaking existing logic. From here it is also possible to create functional test cases to test all possible paths of the business process. These test cases can be ran together as part of an integrated test suite. Creating additional test case is very easy as it mostly involves cloning an existing test case and making some necessary modifications with test data and steps. Once they are created they can be run together as part of the original Expense Approval Functional Tests suite either sequentially or in parallel.

Conclusion

soapUI also provides a way to run and extract reports out of these tests through ant/maven and hence it is extremely easy to incorporate them in the release cycle. If you can use soapUI pro, you have the out of the box ability to generate a wide variety of reports for the executed tests too. The basic version can be used to publish JUnit type tests, which I believe are good enough if considering running these tests in a continuous integration fashion.

Business process testing covers how well the system executes the functions it is supposed to execute; including user actions, data manipulation and integrations. It is done to validate the solution as defined in the business requirements and detailed technical specifications document for each processes. It may often contain the highest overall number of test cases, as it is focused on testing the entire system, not just small bits or units of code. Business processes are tested to ensure that the edits, changes, and outputs conform to the required specifications and/or expectations. Business process testing is also often the most complex area of testing as it involves testing processes during development cycles as it occurs and also when processes evolve through multiple changes post deployment. Automating this testing process will provide extreme productivity, quality and add dynamism to business processes. This article can be used as a reference to carve out a strategy to do so. Off course there may be may way but in my experience, I have found out this way to be effective, easy and without any financial obligation to invest in expensive tools.

The composite project, setup scripts, soapUI projects and some sample reports used in this article can be found here. Please feel free to share opinions, feedback and suggestions and I will be glad to provide any help.

Open a Workflow Task or Instance Trail from Oracle BAM 11g

An interesting requirement that I have recently seen a lot of clients demanding in their BAM dashboards is the ability to action or monitor process instances. Oracle BAM 11g typically provide means to create real time dashboard for process metrics to business process stakeholders. However a lot of organizations are beginning to prefer to also use it as a starting point to get more insight into instance details (such as in-flight status, flow trail, fault information, etc.). One of my reputing requirement in the past was so much as to provide a mechanism to open actionable task forms directly from BAM. And then sometime back I had the same question asked again as how to open a process instance trail directly from Oracle BAM 11g to view its fault details. This is a natural demand for process owners typically in the support role who are alerted of fault notifications from BAM and would not like to go through the trouble of going back and forth the BAM dashboard and the Enterprise Manager console to correlate instances together. This eventually led me to believe that, it is in fact a sought after requirement and hence this article will aim to provide a detailed and step by step guide to define and implement this use case.

In a nutshell, this article will demonstrate creation of actionable links in a BAM dashboard to view and instance trail of a composite instance and from there dig into its audit trail or flow trace. Another useful feature demonstrated will be the use of Action Buttons in Oracle BAM 11g dashboard to launch instances of human workflow tasks of a BPMN composites awaiting to be actioned from designated process users. When such an instance is clicked the user is taken to the BPM workspace UI and take an action on the selected task.

This allows business users to seamlessly monitor business applications and processes and be able to correlate them with instances appearing across different UI’s of the Oracle SOA Suite 11g product suite such as BPM Workspace and EM Fusion Middleware Control console. It is essentially useful for organizations that intend to use Oracle BAM as an operational dashboard for process users in addition to it being used as a real time business metrics monitoring and alerting dashboard.

Take a Sneak Peak at the Use Case

The following video will show a sneak peak of the use case intended to be demonstrated in the course of this article.

During the course of implementing the use case, the article will also describe the following activities in detail:

• An Overview of creating and assigning values to a business indicator and publishing it to Oracle BAM data objects at runtime.
• Configuration changes involved in sending the process metrics data from a BPM process to BAM data objects such as activating sampling points, enabling data targets, configuring the OracleBAMAdapter and altering BPMN engine MBeans .
• Create Streaming Action Lists in an Oracle BAM reporting view to track in-flight instances of a composite that are assigned to process owners, waiting to be actioned. and a list of completed instances.
• Create an action list of completed instances and define an action to launch their audit trail in the Enterprise Manager console. This concept is useful as this can be extended/customized to instead create a list of faulted instances for users to gain detailed insight into the fault details from the Enterprise Manager Fusion Middleware Console.
• Configure External Data Objects and create lookup fields in BAM.
• Create and configure action buttons in Oracle BAM to open an external URL and pass the value(s) of a column in an action list for a selected instance to the URL term.

To gather process metrics and activity instance data in BAM to be able to build the reports, an existing BPMN based composite will be used. The composite project can be downloaded from the example demonstrated in an earlier BPM post on event based gateways. The article also describes the use case the project tries to address in details.

http://blog.rubiconred.com/2012/05/understanding-event-based-gateways-in.html

The download link for the application workspace is provided in the aforementioned article. The soapui project to create sample instances and thus populate the BAM reports is provided at the end of this article.

Prerequisite(s)

The modelling workspace and the version of Oracle BPM and BAM Suite used in this demonstration is 11gR1PS5 i.e 11.1.1.6 although the concepts discussed are generic and applicable to all versions.

Creating the Business Indicator(s)

Import the application workbench consisting of the modelled process in JDeveloper. To begin with the article describes adding a business indicator to capture the credit card approval status as the instance progresses through multiple activities.

In the JDeveloper menu click on View > BPM Project Navigator and open the AccountOpeningProcess business process. You will notice a Structure pane visible in the bottom left hand side of the editor. If the structure pane is missing then click on View > Structure to be able to see it. Expand Business Indicators > Dimension and right click on it to be able to add a new dimension of type String. Name the dimension as cardApplicationStatus. For simplicity this article just has a single business indicator, though in real business processes you may end up having multiple KPI collecting indicators.

Once an indicator has been defined, it has to be assigned a certain value to depict a business friendly state of the process instance is currently in. Have a look at the red information rectangles for the AccountOpeningProcess as depicted in the screenshot below. They may well represent the various business friendly stages of the application status. For example, when a New Application request is received  by the process the business indicator may be set to “PPLICATION IN PROGRESS indicating that it is being currently processed upon. If the customer for any reasons wants to terminate his application midway while his initial request is in-flight, the application status may be transitioned to “REQUESTED CANCELLATION”. Similarly there may be other intermediate statuses that can be captured in a long running business processes and be presented to business stakeholders or process owners.

Populating a business indicator with a pre-determined value is straightforward. It is in a similar way as a value is assigned to any other process variable. Double click on the New Application start message event and then on the Data Associations link. Simply drag the Expression icon on the cardApplicationStatus metric variable under OnlineAccountOpenin>DataObjects on the right hand side of the Data Association wizard and assign it a static value of “APPLICATION IN PROGRESS”.

Similarly, double click the Cancel Application intermediate event and then assign REQUEST FOR CANCELLATION to the same business indicator from the Data Associations link. When the business processes receives an intermediate request for cancellation while the task is still in progress, the cancel application intermediate event is invoked and the latest status of the process instance (determined by the cardApplicationStatus business indicator) is replaced. Use the same technique to assign other possible approval states to the business indicator for other activities.

Configuring Sampling Points and Data Targets

Now that the business indicators are assigned appropriate values describing meaningful process states, the next thing is to publish these indicators to BAM. Readers familiar with Oracle SOA Suite will know that sensors can be defined for the BPEL engine to automatically publish their data to BAM data objects in real time as soon as their values in the business process changes. Unfortunately as of now, sensors cannot be defined in Oracle BPM Suite. Instead there is a concept of Sampling points.  The BPMN Service Engine uses the defined sampling point configuration to decide when and where to publish process analytics information. Process analytics sampling points can be created for all activities, just interactive activities or disabled altogether. The process metrics can be published internally to the in-built cube star tables in the SOAINFRA schema or externally to BAM data objects. The process sampling points can be configured by right clicking on the BPM process from the BPM Project Navigator view and then clicking Project Preferences . This article needs sampling points to be generated for all activities in the business process, hence Generate for All activities from the Project Sampling Points radio options is selected. Sampling points capture a host of other information in addition to capturing the values of defined business indicators such as performance and workload metrics. Also note that choosing Generate for All Activities will generate a lot of data to be published to BAM. More information about Process Analytics and Sampling points can be read at the official Oracle documentation site at

http://docs.oracle.com/cd/E28271_01/doc.1111/e15176/monitoring_proc_act_bpmpd.htm

By default the sampling point only publishes process metrics to the internal CUBE_* tables in the SOAINFRA schema. To publish these analytics data externally to BAM click on the Data Targets tab and check Enable BAM option. Also change the default Data Object Path to something like /Customer/AccountInitiation. This ensures that all data objects pertaining to a project are created in the folder hierarchy entered in the data object path field.  This external publishing of the BPMN engine data to BAM data objects in the active data cache is taken care by the OracleBAMAdapter. This adapter has two predefined connection factories. It allows either publishing the data to the BAM engine either through a RMI interface or through a web service interface.  The BAM Adapter JNDI name for these interfaces is either eis/bam/rmi or eis/bam/soap respectively. The eis/bam/rmi provides a better performance as this doesn’t employ the BAM web service interface and used preferably if the BAM and BPMN engine reside in the same JVM.

Configuring the OracleBAMAdapter

The integration glue that binds and permeates instance metrics information to pass from the BPMN engine to the BAM active data cache is the OracleBAMAdapter. The  BAM adapter needs to have the same JNDI (one that was selected in the previous step) configured that is pointing to the correct instance of the BAM active data server. Oracle Weblogic Server administration server console provides the mechanism to view and edit BAM adapter configuration properties. Login to the administration and navigate to Summary of deployments > OracleBamAdapter > Configuration > Outbound Connection Pools and click on the eis/bam/rmi connection pool to view its default configuration properties. These properties may have to be changed to point to the correct instance of the BAM active data cache server. It is also important to note that any change in these adapter properties are applicable only when they are saved and the adapter configuration is updated. This typically happens when the adapter is either redeployed with the changes in the plan file or updated with  the saved changes.  Proper configuration of all of the above settings is important for the BPMN engine to be able to plug with the BAM server.

On an Oracle BPM Suite 11g PS3 and above, with only these changes in place, simply deploying the BPM project will create the necessary data objects in the BAM active data cache. Open the Oracle BAM console and click on the BAM Architect view to be able to see the list of data objects existing in the BAM active data cache server. Notice the AccountInitiation subfolder created under DataObjects > Customer folder. Under this hierarchy will be the data objects containing the instance metrics data published from the BPMN engine. Later parts of this article will show how these data objects will be used to create interactive reporting view in BAM.

BPMN Engine MBean configuration Alteration to Allow the engine to post data to BAM

As discussed earlier, the above set of configuration changes are sufficient to create the data objects when the business process composite is deployed to the application server. Now when an instance is created and executed it is expected that these data objects will have process metrics value populated at near real time. However the contents of the data objects are not be populated unless a certain disable action to supress process measurements to be sent to the BAM engine is turned off. Login to Oracle Enterprise Manager Fusion Middleware console and navigate to soa-infra > SOA Administration > BPMN Properties > More BPMN Configuration Properties to view the configurable BPMN engine MBean properties. Scroll down the list to see the DisableActions property. The default value for this property is BAMCommand, which supresses measurement actions to be sent to BAM. Clear this field (leaving it blank) and save the settings. If another instance of the BPMN process is now executed, the BAM data objects will being to be populated with measurements obtained for the  various process activities.

Creating the Reporting Dashboard in BAM

With the data objects being able to receive measurement data from the business processes, the next thing to do would be to create the BAM reporting dashboard. The dashboard to be developed in this article will have two horizontal regions each displaying a streaming action list of its own. The idea is to have one of the horizontal view displaying recently completed instances and have a hyperlink defined to launch its detailed audit trail in a pop-up while displaying the list of in-flight instances in another. The view showing the in-flight instances will also provide an action button to launch the approval task form for the the selected instance.  As a desirable feature a similar  streaming list of displaying the faulted instances can also be created that leads process users enlisted as support stakeholders to the flow trail to know the exact point and reason of failure.

Login to the Oracle BAM 11g console and from the landing page click on Active Studio (this is where reports and alerts are create in BAM). Click on the Create a New Report link to open the tiled report template selection screen. Select the template titled Two equal horizontal tiles with thin separator. From the list of various report types in each of the horizontal tiles select Action List and  title the report as Credit Card Approval Scoreboard. Each of the report views will prompt for a data object to be selected from which the view will sources its data content.

The upper horizontal tile is used to display a list of completed instances. For this view select BI_default_OnlineAccountOpening_AccountOpeningProcess as the data object and then click on the Fields tab. This lists all the fields in the data object. From a reporting standpoint, it may not necessarily make sense to display all the fields in the data objects but only a few important ones.  For the report in this article, the selected fields are COMPOSITE_INSTANCE_ID,  BI_NAME, COMPONENT_START_TIME, COMPONENT_END_TIME, COMPONENT_INSTNANCE_STATUS, COMPOSITE_NAME, COMPOSITE_REVISION, DOMAIN_NAME and METRIC_cardApplicationStatus. These fields however will appear in the report in their alphabetical order. To change this check the select-boxes corresponding to these fields and use the Arrange icon to rearrange them to be displayed in a custom order. Optionally the report can also be pre-sorted based on values a particular field by moving the field under the Sorted Fields panel in the Sort tab.

Another important thing worth mentioning here that if the view configuration is left just as it, a whole lot of duplicate instances will appear in the list. They are not necessarily duplicate as the process measurement data is published for every activity. Therefore the same composite instance will have as many rows in the data object as the number of activities in the original business process. There will however be only one row with the latest snapshot of the process. In order to show only the unique and non duplicated list of composite instances in the streaming list the Filter tab can be used to and add a filter expression to discard the non-latest snapshot of an instance. Add a new filter entry and for the filter expression select the field as LATEST from the data object fields, the comparison type as is equal to and equate it to a value of Y. For the report in this article, yet another filter is added to display only the approved instances by adding a filter expression to equate the METRIC_cardApplicationStatus field to a value of APPROVED. The list can be narrowed further by adding more filters to the list.

The Properties tab allows to change the view name, fonts and other visual aspect of the streaming list.The final streaming list view should resemble something as shown in the below screenshot.

Hyperlinking a Column in the Report with an Action

Well, the teaser video above showed that the composite instances in the view were hyperlinked which when clicked pops up the audit trail (as seen from the composite dashboard of Enterprise Manager Fusion Middleware Console) for the selected instance. Now for the creamy part of this article, it will be described to create and implement action buttons in Oracle BAM and how they can be used in a report. Select the Completed Instances streaming list report tile and then click on the Change Report Properties link under the report Actions menu. This opens the Report Properties popup dialog. Click the Actions tab and then the New button to create and configure a new action for the report. Provide a name and optional description for the action name and hit Next.

The Action Type lists various action that can be performed on data in a report such as executing a read/write action on data input, selections from that action list or form, open an external URL etc. From the options in the select the Open a URL radio box and then click on Next to open the Action Editor. The action editor provide a very convenient feature to construct a URL by creating a combination of terms term which can be concatenated in the end to form the final URL. These terms can be configured to either have constant values or represent dynamic columnar values from any selected view in a report.

Before being able to configure the URL term, it is required to know how to open the link to the audit trail of an instance. The audit trail of any composite instance can be directly viewed in the browser by using the link below.

http://<hostname>:<portName>/em/faces/ai/soa/messageFlow?target=/Farm_<domain_name>/<domain_name>/soa_server1/<partition>/<composite_name>%20[<version>]&type=oracle_soa_composite&soaContext=<partition>/<composite_name>!<version>/<instance_id>

The link, however is made up of a lot of instance specific information such as the host, port and partition of the soa server where the composite is deployed to, its version and the instance id. Interestingly all but the host name, port name and the domain name (Weblogic server domain name) can be figured out from the default data object itself. They can either be hard coded for each instance of the BAM server to have the corresponding value of the SOA server or the other ingenious way is to create a table in the database and read the values from it. The instance specific information can be directly derived as values of the selected row from the view list. There are other ingenious ways to do it if you dont want to hard code these values. Entering constant values for a URL term is pretty simple. Simply choose the Mapping Type as Constant Value to be able to enter the hard coded part of the URL.

The dynamic part of the URL value can be added in a two step process. First select the choose Value from a List View radio buttonin the Mapping Type and then select the view from the report skeleton containing the streaming list to populate a drop down of the data object columns used in the list. Select the appropriate column value that is needed in the URL. For instance, the COMPOSITE_NAME, COMPOSITE_REVISION, DOMAIN_NAME (this is the partition contrary to the Weblogic domain name) and COMPOSITE_INSTANCE_ID may be required as dynamic values in the URL. There is no restriction on the number of terms that can be created as a combination of constant and lookup values to form the complete URL.

The final Open a URL configuration screen will contain multiple entries that are a combination of constant hard coded values and dynamic values from the list. These are concatenated together to form the actual URL for the hyperlink to be launched when the composite instance column is clicked in the list view. The wizard also allows editing the features of the popup. Click on the Click here to edit Windows features link and choose Full screen for both the width and height of the popup window to display it in full screen mode.

Now that the action is defined the last remaining bit is to configure the action button itself. Click on Next to be presented to the Button Formatting screen. Select the Display the button in a view radio button and from the visual empty report  skeleton select the streaming list view to which the URL action needs to be added. As a hyperlink is desired on the composite instance id column for the view check the Display as a column of formatted links in the selected view option and from the Column to format dropdown choose COMPOSITE_INSTANCE_ID. Click OK on all the screens to save the changed report properties.  With this the configuration changes required for the Completed Instances view of the reporting dashboard is complete. The article will shortly demonstrate how the final view looks like and what does the configured action list do.

Adding the SOAINFRA Schema as an External Data Source

In the following part of the article, another interesting aspect of the use case that is to view the task form of an instance that is awaiting an action from a process user will be demonstrated. But before going ahead with creating the report view there is something else that has to be taken care of. In order to open a task form corresponding to a particular instance id, its taskId is required. Unfortunately the default business indicator metrics data object does not contain the task id. The easiest way to lookup taskId for a composite instance is to query the WFTASK table in the SOAINFRA schema.

select taskid,state from wftask where compositeinstanceid=?;

However the problem is that composite instance id and taskId share a one to many relationship. The query to retrieve taskdId from compositeInstanceId my return more than one row and not all of them can be used to open the task form. Another important thing to know would be that only the taskId row that has the value of the state column as ASSIGNED indicates the current task(s) that are pending actioning from process users. This is achieved by simply appending a filter on the state column.

select taskid,instanceid,ecid from wftask where compositeinstanceid=? and state=’ASSIGNED’;

It is therefore required that there is some sort of mechanism available in BAM to lookup these required field from the database table. This is facilitated in Oracle BAM using external data sources. To begin with open the BAM Architect view from the landing page and click on External Data Sources. Click Create to configure an external data source, provide a suitable name, say SOA_INFRA and connect to the [PREFIX]_SOAINFRA schema. Check out the screenshot below to see as how to provide the schema name, password and the connection string. Verify that the connection to the schema is established by clicking the Test button at the bottom.

Creating an External Data Object with the WFTASK table

The external data source can now be used to create an external data object. Browse to the AccountInititation subfolder and click on the Create Data Object link to create a new data object. Name it as TaskDetails. Check the option box beside External Data Object  indicating that this data object sources its content from a database table instead. Select the external data source that was created in the previous step and then select WFTASK from the dropdown under External Table Name. The columns of this database table are now available to be added as fields for the data object by clicking on the Add a field link. The fields that are added from database table are COMPOSITEINSTANCEID,TASKID,PROCESSDUEDATE,ACCQUIREDBY,ASSIGNEES,ASSIGNEEUSERS,CREATOR,STATE,INSTANCEID,ECID. Note that only a few of these fields will be needed to configure the report view. After the fields are added click on Save Changes to save the data object. View the Contents tab of this data object to see the selected columns for all the rows in the database.

Adding Lookup Fields in the Business Indicator Data Object from the External Data Object

As discussed earlier the streaming action list view to display the in-flight composite instances with human tasks will need to source its reporting data from the BI_default_OnlineAccountOpening_AccountOpeningProcess data object. But somehow this data object would need the additionally  required fields too such as the TASKID, STATE. These fields can be looked up from the TaskDetails data object. This is straight forward as Oracle BAM data objects allows creating look up fields that can be created to look up data from different data objects. Open the BI_default_OnlineAccountOpening_AccountOpeningProcess data object and click on Layout > Edit Layout to be able to add lookup fields to it. Once in the edit mode, click on the Add one or more lookup fields link at the bottom to open the lookup field definition popup. Select the TaskDetails data object and from the list of Lookup Fields click on the TASKID field. This lookup however will be based on some common fields in both these data objects. Select COMPOSITEINSTANCEID from the list under Fields to match from Lookup Data Object  and COMPOSITE_INSTANCE_ID from the list under Fields to match from this Data Object. Click Add to define the lookup criterion. More than one such lookup criterions can be added if needed be. Similarly add another lookup field i.e the STATE from the TaskDetails data object. Keep the lookup criterions based on the COMPOSITE_INSTANCE_ID and COMPONENT_INSTANCE_ID. Now the  BI_default_OnlineAccountOpening_AccountOpeningProcess will also have the values for TASKID and STATE for a given composite instance.

Configuring the Streaming Action List for Inflight Instances

Make sure everything is saved for the moment. Edit the  original report template and for the next horizontal tile too select the view type as Action List. The streaming list view will have to be now configured to show the relevant in-flight live instances. Open the report in the Edit mode. For the data object field select the same data object as used in the previous view i.e BI_default_OnlineAccountOpening_AccountOpeningProcess. Go to the Fields tab to select and arrange the following fields in their order: COMPOSITE_INSTANCE_ID, BI_NAME, COMPONENT_NAME, METRIC_cardApplicationStatus, STATE, TASKID. From the Sort tab add BI_NAME and METRIC_cardApplicationStatus under the Sorted Fields.

As stated earlier if no filters are applied to this data object list, it will end up displaying all the instances against all executed activities in the business process. In order to view non-duplicated composite instances only the ones that are latest are to be filtered out. and just those that are assigned to process users. Having such filters is easy. Click on the Filter tab and click on Add Entry. This opens the Filter Expression wizard. Add a filter for the STATE field having a value of ASSIGNED. Similarly add another filter for the LATEST field to have a value of Y. This would do the work.

The display settings of a report are configured from the menu tabs under for the Properties button. Click on the Properties button and under the General tab enter Live Instances for the View Title. By default the streaming action list shows checkboxes against all the rows in the report. Change these to radio buttons so that only an instance is selected at a time. Go to the Actions tab and select Single Select (radio buttons) options.

Once these settings are applied and saved the streaming list will show the in-flight instances along with their task identifier and the pending action. Optionally, the task creators, assignees, task expiration time, priorities etc. can also be shown in this list to have a better visibility as to which tasks are assigned to which process and which tasks needs urgent attention. Also note that the column titles displayed in the screenshot below is different from the data objects fields. This can be done by overriding their default names from the Text and Align tab under the Properties button.

Define an Action Button for the selected instances of the List

The final piece in the hook is to define an action button for a selected row in the report view. What is desired here is that when a row is selected the action button should take the users to the approval form for the selected instance. This would effectively mean launching the business process workspace view of the task form allowing it to be actioned if needed be. Opening the task approval form is easy. The URL to be used to launch the task form simply needs the HOST and PORT on which the business process workspace is running and the task id of the composite instance (which is obtained already and displayed in the list).

http://HOST:PORT/integration/worklistapp/faces/home.jspx?taskId=TASKID

The same set of steps that were discussed earlier to create an action button can be executed once again to create another action button. Open the report once again in the Edit mode, select the view and click on Change Report Properties.  Click on the Actions tab and then the New button to open a new action editor wizard. Name this action button as View Approval Page. In the next screen define the type of action as Open a URL. The URL for the action button can be configured by adding constant or dynamic strings (here referred to as Terms) which when concatenated will give the complete URL string.

Create a New Term with constant value by passing the entire URL string except the TASKID in it. Be sure to replace the value of the HOST and PORT with that of the server instance running the business process workspace user interface. Add another New Term but this time choose Value from a List View from the mapping type action list. The next screen displays the report skeleton from where select the live instances view in the report. This will show all the selected data object fields configured for the list as dropdowns under Select a column from this view column. Select TASKID and then click OK. 

In the following Button Formatting screen simply select the Display the button in a view radio button under the Button Location panel. This will add the action button in the same view. For rest of the screens simply click on OK to save the report property changes.

Appreciating the End Result

Well, that’s it! After all these changes your BAM users will be able to see two streaming lists of completed/historical instances and in-flight instances. The users will also be able to view the instance audit trail by clicking on an instance in the list and if they happen to be process users then also action in-flight instances by selecting it and clicking the View Approval Page action button. This also allows you to create a seamlessly correlated view of instances across the multiple dashboards that Oracle SOA Suite 11g has to offer. It is important to note that not everyone in the organization will be able to view the task-form for the instance. Only users who are assigned to the process roles to action the task will be able to do so. This ensures that the security aspects of this implementation methodology is also covered

Downloadable Resources for the Project

• BAM Data Objects and Reporting Dashboard

You can import these data objects and reports into your BAM server by running the ICommand utility. The easiest way is to copy all the dataobjects and reports in the DataObjects.zip file to the <MIDDLEAWARE_HOME>\Oracle_SOA1\bam\bin directory and then run  icommand –cmdfile import.xml in the command line. Before running the Icommand utility make sure that the BAMIcommandConfig.xml file under the <MIDDLEAWARE_HOME>\Oracle_SOA1\bam\config directory is configured to point to the correct instance of the BAM server. A detailed explanation of working with the ICommand utility can be read here at http://docs.oracle.com/cd/E14571_01/integration.1111/e10224/bam_app_icommand.htm

• 
  

  Composite Project with the BPM Process
• 
  

  SOAP-UI Project to create Instances of the Project

Feel free to post comments and suggestions, and possible improvements and I will be glad to incorporate them here. If you have a similar requirement and are struggling to re-create a reporting dashboard similar to what is proposed, send us a message.