Customization Workbench

Introduction

The Customization Workbench is an Integrated Development Environment (IDE) for implementing custom code for crafting workflows to fit any business process requirements. You can integrate custom code directly into PROCESSIT.

The Customization Workbench makes customization options available through different exposed interfaces. For each interface, certain programming language are enabled, PLSQL or/and Groovy. In order to write custom code you must conform to the adopted interface.

To gain access to the Customization Workbench, log in to PROCESSIT with the user SETUP , and the configured password, by default welcome. Select the Customization Workbench in the module menu.

It is assumed that any user using the Customization Workbench has experience with the chosen coding language, and is able to write and maintain custom code.

Interface Positions in the Workflow

In the Workflow Overview Diagram, you can see a graphical representation of where the interfaces are invoked during the invoice Workflow.

Working with Custom Code

Supported Coding Languages

The customization workbench supports two coding languages, Groovy (Java) and PLSQL. Not all interfaces accept code written in both languages. To see which language is supports, select an interface in the UI and see the selected checkboxes in the Supported Languages box.

Groovy Code

When supplying groovy code, you must implement the mentioned java interface. Groovy code can be compiled in the Customization Workbench.

The test code when writing in Groovy must extend the class com.readsoft.processit.custom.api.CustomGroovyTester. You must override the run method that is invoked when you click Run test. The class also exposes a setLog(String) method. Use this to add your debug messages during the test.

The concept of the test class is that you get the interface name in the interfacename parameter in the run method, and you use that to retrieve your custom code from the database by invoking the getGroovyClass method from the test class. You can then cast the retreived class to the specific interface and then execute the methods on it.

PLSQL Code

When supplying plsql code, you must ensure that you have the correct input and output parameters.

The concept of testing the plsql code is that your custom code is passed to your test code through parameter :1. You can then use execute immediate to execute it.

Creating new custom code for an interface

You can supply custom code via the web-based Customization Workbench. For each interface, you can write custom source code to be executed when the interface is invoked. The source code is written in the Source Code tab.

You can define any number of custom source codes for any given interface, but only a single custom source code can be active for an interface.

1. Navigate to the Customization Workbench.
2. Select the appropriate interface where you want to invoke your code.
3. Select the Seeded Custom Code that you want to copy.
4. Click Copy to New Source.
5. Supply a unique name for the source code.
   1. Locate the General box in the Source Properties accordion tab.
   2. The field Source Code Name defines the source name. Change the name from Please change name.
6. Edit your code in the Source Code tab.
7. Click Save.

The Customization Workbench currently does not support syntax highlighting.

Importing custom code

You can select to import already written source code from a file.

1. Select the appropriate file in the Import source from file file.
2. Click Import Source.

Source Properties

You can view and set various properties for each source in the boxes available in the accordion tab Source Properties.

Standard Seeded Code: Determines if the source code is considered standard seeded code, meaning it is the default custom code when opening the interface and copying to new source codes.

Database pool name: Shows where in the database PLSQL code is executed, so you can use this database link for the interface. This is not relevant when using Groovy, since you can create database connections in Groovy. This is not relevant if you are writing Groovy code.

Programming Language Used: Select the language used to write this custom code.

Writing code

Include import com.readsoft.processit.custom.api.CustomApi; for Groovy.

Test Source Code

You can also setup test snippets and run them in order to ensure that the custom code works before actually enabling it.

Output from the test code is redirected and displayed in the log area in the bottom of the window. dbms_output is supported in plsql and in groovy you extend a test class that expose a setLog method.

Emulate the code and replace variables with actual testing values.

Interfaces

Customization Interfaces designates the locations in the workflow code where you can supply custom code. The supplied code is run when the workflow reaches the designated point.

Interface Properties

Each interface has a Description and a Name defined in the Identification box. The description is a short summary of when the interface is invoked. The name also relates to the position in the workflow. The summary description can be changed by a developer user.

The Supported Languages box shows the supported languages for the interface.

The Activation box controls whether the interface is activated, and which custom code to run.

The Description accordion tab contains a more thorough description of how the interface can be used and when it is called and invoked.

Seeded Examples

Preexisting customizations are available with customized code. These seeded examples are described in the Customization Workbench and serves to demonstrate how the interface works. The examples are all valid customizations.

The seeded examples for Groovy language contains imports for the java classes you can use for writing your own custom code. The classes imported in the examples are the core classes for writing useful custom code for the interface in question.

The best practice when creating a new Source Code for an interface is to copy one of the seeded source code examples.

Activating an Interface

To activate a particular interface:

1. Locate the Activation box in the Interface Properties accordion tab.
2. Select the Source Code Name to run when the workflow invokes the interface in the Use Source Code Name list.
3. Check the checkbox Enable Interface in the Activation box.
4. Click Save.
5. Click Commit.

For each interface, only a single source code can be active at any given time.

Interface List

Validate the invoice inserted into payable interface tables.

Groovy/PLSQL

The flow for calling this interface is:

1. Data is inserted into payable interface.
2. The procedure is called.
3. In case status code ERROR is returned, the import job is not started. A notification is send to the super user. The content of the status desc parameter is presented in the PROCESSIT payable interface correction form. If import is retried, the procedure is called again prior the import.
4. In case status code OK is returned, the import job is scheduled as a concurrent job in Oracle EBS.
5. If any rejections are raised as a result of the import job, and the invoice is not imported, a notification is send to the superuser who tcan correct data in Payables Interface Maintenanceand then retry the import. The process then repeats from step 3.

Seeded Example: Groovy Example Map Columns

Contains a Groovy code example of how to update a field in Accounts Payable interface with a value from PROCESSIT invoice header.

Useful Classes

• CustomApi
• CustomValidateApInterface
• CustomValidateApInterfaceResp

Validate the invoice line when invoice is saved.

Groovy

This interface is invoked when user has inserted or changed an invoice line in the invoice accounting form. It will also be invoked when user submits the page.

Seeded Example: Groovy example of line validation

Contains a Groovy example where only line items with the line type ITEM are accepted as valid when an invoice is saved, otherwise the error returned by code is displayed in the accounting form.

Useful Classes

• CustomResponseType
• CustomInvoiceLineType
• CustomInvoiceType
• CustomStatusCodes

Get additional approver

Groovy

This inteface is invoked after the standard approval has completed. The interface is only invoked once. The user you return must have priviliges to approve the invoice otherwise the flow will send an error notfication to the super user.

Seeded Example: New Additional Approver

Useful Classes

• CustomInterfaceType
• CustomUserType

Check scanned bank account number

Groovy/PLSQL

The interface is invoked once during scanned bank account check.

Get match user

Groovy/PLSQL

Get match user is called after trying automatic matching for an invoice without success. The returned user is responsible for manual match of the invoice, i.e. acts as Manual Match Receiver.

Seeded Example: Get match user from requisition

Standard plugin written in groovy. Retrieves the user that should be responsible for manual matching.

If this source code is active, and the interface is enabled, it is invoked from the BPEL service d4_dispatching, and the match user retrieved from the parameter Default user for PO matching is passed in as parameter, so it can be used as a default value.

All purchase orders referenced on the invoice lines are located in Oracle Purchasing to verify that they are valid purchase orders, and if that is not the case, the default match user passed in to this method is returned.

Based on the referenced purchase orders all requestors are retrieved. In case there is only one unique occurence of requestor, it is used as match user, otherwise the default match user passed in is returned. All database connections are taken from the connection pool in weblogic.

The requestor id from the purchase order distributions is transformed into user name, by invoking the IdentityApi in PROCESSIT.

Seeded Example: Seeded Groovy Sample

This is not a complete example and should not be used in production environment.

The code implements a java interface named CustomMatchUser and extends class "CustomApi" and therefore inherits the methods available in that class, such as the "setLog()" method.

The interface states that no exception is thrown from the method "getMatchUser" and therefore a surrounding try catch is neccessary.

It connects to database through a connection it gets from the connection pool in weblogic.

Return status should be set to either "S" for success or "E" for error. The status desc can be set according the the outcome.

Useful Classes

• CustomMatchUserResponse

Pre match rule

Groovy/PLSQL

Pre match rule is invoked during the automatic matching process, before each match rule is executed for an invoice. The interface can force the rule to be skipped, and it can also manipulate invoice- and purchase order data which are passed in. The data returned by this interface is used as the basis for the match rule.

Seeded Example: Match All pre condition check

This is an customization made to support specific matching rules. This source code is implements an extension to the Match All matching rule by introducing a MATCH_ALL pre-condition check.

Useful Classes

• CustomPreMatchWithRuleResp

Get next approval

Groovy/PLSQL

Custom code to override getting next approval.

Seeded PLSQL example

See the code in the source code for details.

Seeded example: Get Approval

Invoked when the invoice is send for approval. looks up a custom approval field (attribute20) from the invoice header and returns it to the approval flow. This overrides the hierarchy and approval authority in PROCESSIT. The next time it is invoked it checks to see if the current approver passed in is the same as the one from the custom field. If that is the case, it is the second time, and the current user can approve, and that ends the hierarchy and the approval flow.

The user found in attribute 20 is verified by a call to the PROCESSIT identity service. If the user is invalid, a superuser acts as approver.

Useful classes

• import com.readsoft.processit.custom.api.CustomApi;
• import com.readsoft.processit.custom.api.interfaces.CustomApprovalCheck;
• CustomApprovalResponse
• import com.readsoft.processit.config.api.ConfigAPI;
• import com.readsoft.processit.identity.api.model.types.User;
• import javax.sql.DataSource;

Get default tax code

Groovy

Default tax code could either be tax classification code or tax code, depending on EBS version. In case tax is enabled in PROCESSIT user interface, and defaulting is set to custom, this api will be invoked from task detail (accounting, approval, manual match) and from automatic match.

Seeded Example: Tax Rate Base defaulting

Gets the default tax classification code based on tax rate. This is an alternative to the standard defaulting of tax code in PROCESSIT, based on tax hierachy and supplier setup.

The requirement is that PROCESSIT integrates to Oracle EBS R12.

Useful Classes

• import com.readsoft.processit.custom.api.CustomApi;
• import com.readsoft.processit.custom.api.interfaces.CustomDefaultTaxCode;
• import com.readsoft.processit.custom.api.types.CustomDefaultTaxCodeResponse;
• import com.readsoft.processit.custom.api.types.CustomInvoiceLineType;
• import com.readsoft.processit.custom.api.types.CustomInvoiceType;
• import com.readsoft.processit.custom.api.types.CustomAccountSegmentType;
• import com.readsoft.processit.config.api.ConfigAPI;

Post match rule

Groovy/PLSQL

Post match rule is invoked after each match rule has been called, and this interface can force to skip further matching, it can update the Invoice and finally it can try to match the invoice and return a match flag.

Seeded Example: Copy Tax Code to lines

Extension that makes the MATCH_ALL rules copy the tax rate from invoice header to all invoice lines that have been matched by a MATCH_ALL rule. (MATCH_ALL rules drop the transferred invoice line information).

Useful Classes

• import com.readsoft.processit.custom.api.CustomApi;
• import com.readsoft.processit.custom.api.interfaces.CustomPostMatchWithRule;
• import com.readsoft.processit.custom.api.types.CustomPostMatchWithRuleResp;
• import com.readsoft.processit.invoices.api.model.types.Invoice;
• import com.readsoft.processit.invoices.api.model.types.InvoiceLine;
• import com.readsoft.processit.purchasing.api.model.types.PurchaseOrder;
• import com.readsoft.processit.config.api.ConfigAPI;
• import com.readsoft.processit.identity.api.model.types.User;

Custom Code Before Export

Groovy/PLSQL

Perform custom code prior to calling the export to ebs process.

Seeded Example: Custom code prior to Export to EBS

See the code in the source code for details.

Custom Code get approval level for GE and PO invoices

Groovy/PLSQL

Perform custom code to determine the approval level.

Useful Classes

• import com.readsoft.processit.custom.api.CustomApi;
• import com.readsoft.processit.custom.api.interfaces.CustomApprovalLevel;
• import com.readsoft.processit.custom.api.types.CustomApprovalLevelResponse;
• import com.readsoft.processit.config.api.ConfigAPI;
• import com.readsoft.processit.identity.api.model.types.User;

Validate the Descriptive Flexfields when invoice is saved

Groovy/PLSQL

Custom code to override or default descriptive flexfield attributes and/or the attribute context values based on invoice and attribute data which is invoked when the user clicks the Save () icon from the descriptive flexfield popup. This interface is an alternative and can be used to perform custom validations on the descriptive flexfield data. For the invoice header’s descriptive flexfield, all invoice header and flexfield data is passed to the interface. When saving the invoice line descriptive flexfield, all invoice header, invoice line, and flexfield data is passed to the interface.

Seeded PLSQL Example

See the code in the source code for details.

Seeded Example: Validate the Descriptive Flexfields when invoice is saved

Defaults One-Time to the invoice header attribute context when saving the flexfield.

Useful Classes

Custom interface to the descriptive flexfields prior to accessing dff data

Groovy/PLSQL

Custom code to override or default descriptive flexfield attributes and/or the attribute context values based on invoice and attribute data which is invoked when the user open the descriptive flexfield popup. This interface is an alternative and can be used to address hidden attributes which are defaulted through the ebs form. For the invoice header’s descriptive flexfield, all invoice header and flexfield data is passed to the interface. When saving the invoice line descriptive flexfield, all invoice header, invoice line, and flexfield data is passed to the interface.

Seeded PLSQL Example

See the code in the source code for details.

Seeded Example: Custom interface to the descriptive flexfields prior to accessing dff data

Sets the invoice line attribute context to the invoice type.

Useful Classes

• import com.readsoft.processit.custom.api.interfaces.CustomDFFForm;
• import com.readsoft.processit.custom.api.types.CustomDFFFormType;
• import com.readsoft.processit.custom.api.CustomDFFFormAPI;
• import com.readsoft.processit.custom.api.types.CustomDFFFormResponse;
• import com.readsoft.processit.custom.api.types.CustomInvoiceLineType;
• import com.readsoft.processit.custom.api.types.CustomInvoiceType;
• import com.readsoft.processit.custom.api.types.CustomStatusCodes;

Custom interface for overriding descriptive flexfields valuesets

Groovy/PLSQL

Custom code to override the table validation valuesets used for a given flexfield segment. This is done by supplying an alternative sql statement which is then used in the auto suggest. The alternative query should be in the following format: select <meaning> as flex_value, <description> as flex_desc, <id> as flex_id, <org_id> org_id,' || <flexfield valueset id> || ' as flex_value_set_id from <table(s)> <where statement>

This interface is an alternative and can be used to address valuesets which use form data to construct valuesets. The interface uses the flex field value set id, invoice id, and invoice line id to query and found data which could be used to construct the overriding sql statement.

Overriding Descriptive Flexfield Valuesets Stipulation

If any valueset is overridden for a required flexfield segment, PROCESSIT will not perform the standard oracle flexfield validation, but PROCESSIT will perform conditional validations on the descriptive flexfield data.

Seeded PLSQL Example

See the code in the source code for details.

Seeded Example: Custom interface for overriding descriptive flexfields valuesets

Provides an alternative query for valueset 1017063 which is used instead of the valueset found in ebs. This example returns the sql statement below. The invoice id is used to query the vendor information in the d4 invoice table.

				
	'select vendor_site_code as flex_value, vendor_site_code as flex_desc, vendor_site_id as flex_id, org_id,' || to_char(l_value_set_id) || ' as flex_value_set_id from po_vendor_sites_all@ebsdb where vendor_id = ' || to_char(l_vendor_id) || ' and org_id = ' || to_char(l_org_id)
				
                

Useful Classes

• import com.readsoft.processit.custom.api.interfaces.CustomFlexField;
• import com.readsoft.processit.custom.api.types.CustomFlexFieldResponse;
• import com.readsoft.processit.custom.api.CustomFlexFieldAPI;
• import com.readsoft.processit.custom.api.types.CustomStatusCodes;
• import com.readsoft.processit.custom.api.CustomApi;
• import javax.sql.DataSource;
• import groovy.sql.Sql;

Custom Classes for Flexfields

CustomDFFFormType

				
	public class CustomDFFFormType {
		private String invoiceId;
		private String invoiceLineId;
		private String attribute1;
		private String attribute2;
		private String attribute3;
		private String attribute4;
		private String attribute5;
		private String attribute6;
		private String attribute7;
		private String attribute8;
		private String attribute9;
		private String attribute10;
		private String attribute11;
		private String attribute12;
		private String attribute13;
		private String attribute14;
		private String attribute15;
		private String attributeCategory;
		private BigDecimal invoiceId;
				
                

CustomFlexFieldResponse

				
	public class CustomFlexFieldResponse {
		private String invoiceId;
		private String invoiceLineId;
		private int orgId;
		private int flexFieldId;
		private String attachedLOVSql;
		private String attachedLOVReadOnlySql;
		private String status;
		private String msg;
				
                

Classes

Generic Classes useful for custom code

Some JAVA classes in PROCESSIT are particularly useful when writing custom code for the interfaces. These classes have methods that concern important aspects of the workflow data handling:

• import com.readsoft.processit.invoices.api.model.types.Invoice;
• import com.readsoft.processit.invoices.api.model.types.InvoiceLine;
• import com.readsoft.processit.purchasing.api.model.types.PurchaseOrder;
• import com.readsoft.processit.config.api.ConfigAPI;
• import com.readsoft.processit.identity.api.model.types.User;

CustomAPI class

The following methods are available from the super class CustomAPI:

		public User getUserFromId(
			Integer userId, 
			String logId) throws Exception {
		}
		
		public User getUserFromName(
			String userName, 
			String logId) throws Exception {
		}
		
		public User getUserFromEmployeeId(Integer employeeId,
										  String logId) throws Exception {

		}
		
		public void setLog(String log) {
		
		}
		

Custom classes

These JAVA classes are specific to the Customization Workbench interfaces. They can be used to set and get parameters, so you can use input and output values that are useful when writing custom Groovy code.

Class CustomInvoiceType Parameters

				public class CustomInvoiceType {
					private BigDecimal invoiceId;
					private BigDecimal orgId;
					private String invoiceType;
					private String invoiceNum;
					private Date invoiceDate;
					private Date receivedDate;
					private String supplierNum;
					private String supplierLocation;
					private BigDecimal supplierId;
					private BigDecimal invoiceAmount;
					private BigDecimal vatAmount;
					private String currencyCode;
					private String contactPerson;
					private String remarks;
				

public class CustomAccountSegmentType

					public class CustomAccountSegmentType {
					String segmentName;
					Integer segmentSequence;
					String segmentLabel;
					Integer segmentValueSetId;
					String validationType;
					Integer parentSegmentValueSetId;
					String  parentSegmentName;
					Integer segmentNum;
					Integer parentSegmentNum;
					Integer orgId;
					boolean balancingSegment;
					boolean costCenterSegment;
					boolean naturalAccountSegment;
					boolean interCompanySegment;
				

CustomApprovalLevelResponse

				public class CustomApprovalLevelResponse {
					/*
					 * APPR,ACCT,ACCT_APPR,NONE
					 */
					private String approvalLevel;
					/*
					 * S=Success, E=Error.
					 */
					private String statusCode;
					private String statusDesc;
				

CustomApprovalResponse

				public class CustomApprovalResponse {
					private User nextUser;
					private String currentCanApprove_Y_N;
					private String message;
					private User delegatedUser;
					private String delegated_Y_N;
					private String status;
					private String msg;
				

CustomBankAccountCheckResponse

				public class CustomBankAccountCheckResponse {    
					private String accountToCheck;
					private String accountCheckedAgainst;
					private String checkPassedY_N;
					private String msg;
					private String status;
					private boolean interfaceEnabled;
			

CustomBeforeErpExportResponse

				public class CustomBeforeErpExportResponse {				
					private boolean linesAdded;
					private String statusCode;
					private String statusDesc;
					private BigDecimal invoiceId;
			

CustomDefaultTaxCodeResponse

				public class CustomDefaultTaxCodeResponse {
					private String statusCode;
					private String statusDesc;
					private String taxCode;
			

CustomInvoiceLineType

				public class CustomInvoiceLineType {
					private BigDecimal lineNum;
					private String lineType;
					private BigDecimal quantity;
					private BigDecimal unitPrice;
					private BigDecimal amountTotal;
					private String description;
					private String currentActionUser;
					private BigDecimal ccId;
					private String expenditureType;
					private BigDecimal orgId;
					private String accountString;
					private String projectString;
					private BigDecimal amountLocalCurrency;
					private Date accountingDate;
					private String taxCode;
					private BigDecimal taxRate;
					private String shipToLocationCode;
					private BigDecimal shipToLocationId;
				

CustomMatchUserResponse

				public class CustomMatchUserResponse {
					private String matchUserName;
					private String statusCode;
					private String statusDesc;
			

CustomPostMatchWithRuleResp

				public class CustomPostMatchWithRuleResp {    
					private String statusCode;
					private String statusDesc;
					private boolean matched;
					private boolean stopMatching;
			

CustomPreMatchWithRuleResp

				public class CustomPreMatchWithRuleResp {
					private String statusCode;
					private String statusDesc;
					private boolean matchWithRule;
			

CustomResponseType

	
				public class CustomResponseType {
					private String msg;
					private CustomStatusCodes statusCode;  
			

CustomUserType

				public class CustomUserType {
					private String userName;
			

CustomValidateApInterfaceResp

				public class CustomValidateApInterfaceResp {
					private String statusCode;
					private String statusDesc;
			

Additional Notes

Customization List

Details concerning some of the seeded example customization extensions:

• Custom Invoice Validation. Validate invoice data in payable interface before it is imported to payable. The Payables Interface Maintenance window is used in case any errors are returned. The erros are displayed in the form.
• Additional approver. Get an extra approver based on Organization Id, invoice Id, owner User Name and current User Name.
• Validate invoice line in accounting form before it is saved. You will get access to the invoice header and the actual line and you return an error code and message.

Upgrading

Customizations created and deployed through the Customization Workbench are encapsulated and preserved in order to

Buttons

BackReturns you to the Console Worklist

CommitCommit the custom code and the settings for active interfaces.

Run TestRun a test using the source code provided in Test Source Code.

Copy to new sourceCopy the currently selected source code to a new source for the chosen interface.

Delete sourceDelete the currenly selected source for the chosen interface.

Create new interface

SaveSave you work.

Import SourceImport source code from the selected file.

Export SourceExport the currenly selected source code to a file.