Dynamic Approval Group – Fusion Financials

A White Paper on Dynamic Approval Group

usage for Fusion Financial Approval Use cases
<REVIEW IN PROCESS>

Author: [email protected]

Financial Technology Team, Fusion Financial Applications

Oracle Corporation

Disclaimer: The following document is intended to show an example of how Dynamic

Approval Group functionality can be leveraged in Fusion Financial Application Approval use
cases. It is intended to show a sample example only, and may not be incorporated into any
contract. It is not a commitment to deliver any material, code, or functionality, and should
not be relied upon in making purchasing decisions. The development, release, and timing of
any features or functionality described for Oracle’s products remains at the sole discretion of
Oracle. The contents of this document are subjected to change without notice. This
document is not warranted to be error-free, nor subject to any other warranties or
conditions
 Dynamic Approval Group – Fusion Financials

1. Introduction

2. Custom Web Service to return Approvers

3. Dynamic Approval Group Client Program

4. Configuring Rule using Dynamic Approval Group

5. Things TO-DO and NOT-TO-DO

6. Useful documentation for reference

Audience: This document is intended for technical consultants who implement approval rule
customization for Fusion Financial use cases.

Abbreviations:

SOA – Service Oriented Architecture

BPEL – Business Process Execution Language

HWF – Human Workflow

AMX – Approval Management Extensions

OBR – Oracle Business Rules

DT@RT UI – BPM Worklist Rule Configuration UI

DAG – Dynamic Approval Group

 Dynamic Approval Group – Fusion Financials

1.0 Introduction
Fusion Financial Applications uses SOA 11g Components like BPEL, Mediator, HWF, AMX,
OBR to handle the Approval flows. Out of these technology stack components,
HWF/AMX/OBR together handles the routing, assignment and approval of various approval
tasks like Expense Report Approval, Invoice Approval etc. Out of the box, in Fusion Financial
Applications, the approvers can be fetched from HCM tables based on the Supervisory/Job
level hierarchy or it can be based on a Static Approval Group or it can be based on a hard
coded set of users by modifying approval rules on BPM Worklist DT@RT UI. If approvers
have to be fetched from different sources like below mentioned examples, those are not
supported by any of the out of the box sources given above. Hence we need alternate
mechanism to bring approvers from these wide varieties of sources into the approval list.

 Fetch approvers based on custom non-Fusion apps tables

 Fetch approvers based on excel sheet

 Fetch approvers based on custom web service

To meet these use cases, Dynamic Approval Group feature in HWF can be used in following
pattern and this involves additional coding and customization at customer end. From
Approval Rule, use Approval Group List builder type. Use a Dynamic approval group in that
approval rule. This dynamic approval group will have programming logic to fetch approvers
from required sources.

Approval Rule

Dynamic Approval Group

Web Service

In the above chart, Dynamic Approval Group and Web Service have to be developed,
deployed and maintained by customers. Dynamic Approval Group is a simple java program
from which various approval list customization use cases can be met. But at the same time,
best practices have to be kept in mind during development – if used wrongly, it could
adversely affect performance. Hence below approach is recommended.

NOTE: Dynamic Approval Group is in turn an out of the box feature delivered by HWF. But
to use that, customers/consumers have to write java code as given on this white paper.
Hence this can be done on Fusion V1 GA, V1 RUP1, V1 RUP2 or even earlier releases since
SOA/HWF has been supporting Dynamic Approval group for a very long time now.
 Dynamic Approval Group – Fusion Financials

2.0 Custom Web Service to return Approvers

Write a custom web service which would look up appropriate source [tables or excel or
invoke custom web service] and return the users in a pre-defined format – Eg, list of
strings which would have approver usernames. The returned set of users must be existing
on Fusion system – else Approval flow would error. In this example, we will develop this
custom web service application in ADF Technology Stack and it will be deployed to a
Weblogic Server – Going forward, this document will talk only in ADF Context – however
customers can choose their own technology stack for writing this web service. If approvers
have to be fetched from Fusion Apps tables or from custom table owned by customer on
“fusion” schema of Fusion Data base, then ApplicationServiceDB data source connection can
be used for the ADF BC Service. Else customers have to create a data source connection to
the DB where the custom table is present. This document takes an example of how to fetch
approvers from non-Fusion Apps table on “fusion” schema and add them to the approval
chain. Following is the detailed steps on how this can be done.

Step 1: Create a New Application from Jdeveloper and a Generic Project as shown below.

Application Name: DynamicApprovalGroupApplication

Application Package Prefix:

oracle.apps.financials.commonModules.approvalCustomization

NOTE: Ideally when such customization classes are created in customer instance, the package prefix should not
start with “oracle”. Hence customers should choose to use a different package prefix name. Refer Fusion
Applications Extensibility Guide.

Project Name: DynamicApprovalGroupWebService

Default Package for the Project:

oracle.apps.financials.commonModules.approvalCustomization.model

NOTE: These names can be modified as required.

Dynamic Approval Group – Fusion Financials
Dynamic Approval Group – Fusion Financials
 Dynamic Approval Group – Fusion Financials

Step 2: Add required libraries.

Right click on Project -> Project Properties -> Libraries and Classpath.

Add “Applications Core” and “JAX-WS Client” Libraries.

 Dynamic Approval Group – Fusion Financials

In case if a file named “ADF Library Dependencies” gets created, select the file, choose Edit
-> Delete and remove that file.

Navigate to Project Properties again -> Business Components. Select “Initialize Project for
Business Components” and select ApplicationDB Data Source connection by entering
appropriate connect string.

NOTE: If jdev prompts for any secondary imports, just ignore and skip them.
 Dynamic Approval Group – Fusion Financials

Step 3: Create BC Components.

In this demo application, a custom table called SOA_EMP is used, from where employees
with IS_APPROVER set to “Y” will be used as approvers of the submitted document.
Assumption for this sample is that SOA_EMP table is present in fusion schema of fusion data
base.

Right click on the project -> New -> ADF Business Components -> Business Components
from Tables.
 Dynamic Approval Group – Fusion Financials

This will connect to the Data base used for ApplicationDB connection to lookup tables and
create appropriate ADF business component objects. Query for tables and create Entity
Object, View Object and Application Module.
Dynamic Approval Group – Fusion Financials
 Dynamic Approval Group – Fusion Financials

Step 4: Run and Test AM.

Right click on AM, select Run and make sure the created business components are working
fine.
 Dynamic Approval Group – Fusion Financials

Step 5: Implement Business Logic.

Write a custom method which would fetch users for approval list as per the requirement and
would return a list of usernames. Generate an AMImpl java file for the AM, wrap the
business logic in it and expose the method through the Service Interface.
Dynamic Approval Group – Fusion Financials
 Dynamic Approval Group – Fusion Financials

Step 6: Create Service Interface for the Application Module.

Now let’s expose the above method through Service Interface to expose it as a web service.
Dynamic Approval Group – Fusion Financials
 Dynamic Approval Group – Fusion Financials

Step 7: Change Data Source, Context Root and Test the service.

Since Fusion Apps uses ApplicationServiceDB data source connection for Web Services, the
data source JNDI name has to be updated. Also the project context root can be updated to
have more user-friendly path.

Expand Application resources -> Connections -> Data base. Create a new Data base
connection.
Dynamic Approval Group – Fusion Financials
 Dynamic Approval Group – Fusion Financials

Open Application Module XML -> Navigate to Configurations section and select the Default
Configuration as <AMName>Service – the configuration with Type as SI. Plus edit the
<AMName>Service configuration and make that to use ApplicationServiceDBDS data source
JNDI.

Add this new ApplicationServiceDBDS data source reference to the ejb-jar.xml.

 Dynamic Approval Group – Fusion Financials

Navigate to Project Properties -> Java EE Application -> Java EE Web Context Root. Change
the context root to small camel case of project name –
“dynamicApprovalGroupWebService”. Right click on ServiceImpl file and select run to run
the service in test mode on Integrated Web Logic Server.
 Dynamic Approval Group – Fusion Financials

Paste the WSDL URL on browser and test the service.

 Dynamic Approval Group – Fusion Financials

Step 8: Defining deployment profile and deploying.

Define Business Component Service Interface Deployment Profile for service project and
Enterprise Archive Profile [EAR] for the Application, add the BC Deployment Profile to EAR
and finally deploy the EAR to a standalone web logic server.
 Dynamic Approval Group – Fusion Financials

NOTE the highlighted settings below.

Dynamic Approval Group – Fusion Financials
Dynamic Approval Group – Fusion Financials
Dynamic Approval Group – Fusion Financials
 Dynamic Approval Group – Fusion Financials

Once deployment is completed, the service should be available in appropriate end

point.

http://host:port/dynamicApprovalGroupWebService/DynamicApprovalGroupService
 Dynamic Approval Group – Fusion Financials

NOTE: Fusion Apps Domain is secured with GPA. So a global policy like
“wss_saml_or_username_token_service_policy” might get applied to the deployed
service. Hence appropriate user name password has to be passed to the service in
end point tester WS-Security section.
 Dynamic Approval Group – Fusion Financials

3.0 Dynamic Approval Group Client Program

Now we will be creating a new java program that would implement IDynamicApprovalGroup
Interface. This java class would be used while creating Dynamic Approval Group on DT@RT
BPM Worklist UI Approval Group section. This java program would invoke the above ADF BC
Service using JAX-WS Proxy and get the list of approver users and add them to the approval
group at runtime. This approval group can be used in any participants with any participant
types on rule configuration UI with Approval Group List Builder Type. The assignment mode
will be based on the type of participant [Serial/Single/Parallel] this approval group is used
in. Now let’s create this java program.

Step 1: Create client java code.

Create a new Generic project and add required libraries. Then create a new java program –
say “FintechDemoDynamicApprovalGroup” that implements
oracle.bpel.services.workflow.task.IDynamicApprovalGroup.
 Dynamic Approval Group – Fusion Financials

Step 2: Create JAX-WS Proxy.

Now create the JAX-WS Proxy to invoke the service that was created in Section 2.0 [Custom
Web Service to return Approvers] and get the response with list of approver ids.

Package: oracle.apps.financials.commonModules.approvalCustomization.proxy

Types: oracle.apps.financials.commonModules.approvalCustomization.proxy.types
 Dynamic Approval Group – Fusion Financials

Since Fusion Applications uses Global policy sets for WS Security, no client policy has to be
applied. Client policy would be applied at runtime through GPA.
 Dynamic Approval Group – Fusion Financials

Step 3: Invoke and process the service from client java code.

Below is a java code that invokes the service and prints the list of approver names. This
uses JAX-WS Proxy.
 Dynamic Approval Group – Fusion Financials

getMembers is the mandatory method that’s implemented from the interface. This method
would invoke above getApprovers method, get the approvers, add them to a java.util.List as
mandated by Dynamic Approval Group schema and return the list.

There are two key advantages of this approach. First obvious is that approvers can be
fetched based on dynamic sources like web service, excel sheet, custom tables, pl-sql etc.
Second advantage is that the “task” object that is sent as a parameter to this getMembers
method would carry the list of payload attributes and its values that are exposed to
configure approval rules on DT@RT UI. These values can be derived in the DAG java code
and can be passed to the service to be used as foreign key and retrieve values from
tables/custom tables that Fusion Apps does not expose through DT@RT. It would be a good
 Dynamic Approval Group – Fusion Financials

practice having this client java code as simple as possible – just simply invoke the service
with required parameters, get the list of usernames and add them to the List and return
from getMembers method. Details of few of the methods used in getMembers API is below.

iterateNode: This API is invoked from getMembers as

“this.iterateNode(task.getPayloadAsElement().getChildNodes());”. FIN Approval Projects
have a complex payload that carries various other attributes that are exposed to customers
to configure rules based on them on DT@RT BPM Worklist Rule Configuration UI. Below API
would print all the payload items and their values that are exposed to the customers.

NOTE: System.out.println can be used only during development and debugging purpose.
Don’t apply the code with System.out.println to a production system as it might have
negative impact on performance of the system.

getTagValueFromNodeList: As mentioned above, Fusion FIN Approval flows have very

complicated data model exposed using SDO architecture to customers to configure rules on
top of them. In case if any of those attributes has to be read in this client java program,
then it can be done as shown below.

Sample case: In this case, I would want to retrieve “Providing organization name” in this
client java program. I can do this by executing iterateNode code once to read the list of
attribute node names and use them along with below APIs to retrieve the node value.

String providerOrgName =
this.getProviderOrgName(task.getPayloadAsElement().getElementsByTagName("IntercoOrg
Name"));
 Dynamic Approval Group – Fusion Financials

Step 4: Create profile and deploy this code.

Every time a dynamic approval group is created or updated, it has to be applied to SOA
Server - oracle.soa.ext shared library and SOA Server has to be bounced. That’s why to
avoid a bounce on SOA Managed Server, we do not recommend adding too many business
logic in DAG Client Java program – instead business logic can be wrapped inside the Web
service which could be redeployed as and when the code in the web service is modified.

Navigate to Client Project Properties and create an ADF Library Jar Deployment Profile.
Right click on the project and deploy this ADF Library jar.
 Dynamic Approval Group – Fusion Financials

Deploy this jar and copy this to

$MW_HOME_STANDALONE/soa/soa/modules/oracle.soa.ext_11.1.1. Run “ant” from the
same location so that the ADF Library jar is included in this shared library.

Restart the FIN SOA Managed Server.

 Dynamic Approval Group – Fusion Financials

4.0 Configuring Rule using Dynamic Approval Group

In this section, let’s create a Dynamic Approval Group on BPM Worklist UI and use that in
FUN Intercompany Transaction Approval use case as a sample.

BPM Worklist -> Administration -> Approval Groups -> Create Dynamic.

Enter Dynamic Approval Group name and Class name in <package_name>.ClassName

pattern.

To refer this approval group in an approval rule, from here, navigate to Task Configuration -
> Data Driven tab and select FinFunTransactionApproval [choose one task of your
requirement]. Now Edit -> Modify the rule -> Save and Deploy the rule.
Dynamic Approval Group – Fusion Financials
 Dynamic Approval Group – Fusion Financials

5.0 Things TO-DO and NOT-TO-DO

This section lists some of the good practices that need to be followed and some of the bad
practices that should not be followed.

S.No Description Impact

1 Do not have System.out.println on Java This would have negative impact on the
Code or Web Service code. system.

2 Error Handling: Add Logger statements This will make debugging simpler in
wherever required. Use appropriate log production instance to debug any issues
levels to report exceptions. SEVERE log with DAG Java code or the Web Service.
level is required when there are
exceptions. Handle the exceptions
gracefully.

Reference Document

3 Avoid making any JDBC Calls from This wouldn’t go through the App Server
Dynamic approval group java program. services like JDBC connection caching
and might impact performance of the
system.

4 Avoid using any custom classes or open This would require the additional classes
source classes in Dynamic approval to be available on class path of the SOA
group java program. server and might impact SOA server
startup. Hence it would be recommended
to use such classes in custom web
service code and add required jars to the
classpath.

5 As much as possible, have only the web Reason being, every change on DAG
service invocation logic and addition of code requires bounce on FIN SOA Server
users to the List logic in Dynamic after applying the jar to SOA Extension
Approval Group program. package. Hence do the business logic in
custom web service so that just
redeploying the web service is fine.

6 Handle duplicate users gracefully as per When there are duplicate users returned
the requirement by the DAG, Human task is going to
assign the task based on participant
type. Eg, when duplicate participants are
present on single/parallel participant
type, the user has to approve once. If it
is used on Serial participant type, then
the user might get multiple notifications.
 Dynamic Approval Group – Fusion Financials

6.0 Useful documentation for reference

How to create a Web service.

How to create a Data source connection in weblogic.

Administering Approval Groups.

Using Dynamic Approval Groups.

The END!!

Thank you!!