Rule Design Guidelines Introduction

Introduction

This document contains instruction how to design java rules in Comflow. 

General Rule design

Rules are the name for code that manages logic in the context of Comflow workflows and/or processes. They are supposed to manage the logic that is related to the context of the workflow or the process. Logic that relates to the data oriented logic shall be managed in services, which rules can call. 

There are 3 different types of rules:

• Workflow - extends AbstractRuleExecute
• Process - extends AsynchRule
• Job scheduler - extends JobMonRule

Declare relations

All definitions or relations to other artifacts in Comflow shall be declared in the beginning in the Rule. This can be done as a local constant or, which is preferred, via an application constant class. For example you declare a datamodel as DM_1 = "DMItemList1",  transition event as TE_APPROVE = "TE_APPROVE" or a logical id as LI_10 = "LI_STATUS_10".

You shall do this for the following artifacts with suggested prefix in parenthesis for typing the artifact:

• Task (TA_)
• Process (PR_)
• Role (RO_)
• Workflow (WF_)
• RenderModel (RM_)
• Segment (SG_)
• Tab (TB_)
• Complex model (CM_)
• Simple model (DM_, SM_)
• Transition event (TE_)
• Logical id (LI_)
• Event (EV_)

The reason for this to simplify understanding of the relations for the rule, as well as supporting name changes of artifacts. See example below:

    private static final String DM_D = "DMEmailCenterDetail";
	private static final String DM_AA = "DMEmailCenterDetailAddAttachment";
	private static final String DM_A = "DMEmailCenterDetailAttachments";
	private static final String SG_ID_ATTACHMENTS = "EmailCenterDetail214";
	
	private static final String TE_SEND_MESSAGE =  "SendMessage";
	private static final String TE_CREATE_MESSAGE =  "CREATE";
	private static final String TE_CREATECOPY_MESSAGE =  "CREATECOPY";
	private static final String TE_DELETE_MESSAGE =  "DeleteMessage";
	private static final String TE_ADD_ATTACHMENT =  "AddAttachment";
	private static final String TE_REMOVE_ATTACHMENT =  "RemoveAttachment";
	private static final String LI_ADD_ATTACHMENT =  "AddAttachment";

	private static final String ATTACHMENT_SUBFOLDER =  "EmailAttachments";

This gives the reader of the rule a clear picture of relations within this rule whit out the need to read the whole rule.

There is also a recommendation to use CAPITAL letters if you are working with a declaration. So a transition event TE_APPROVE = "TE_APPROVE" is better than for instance "TE_APPROVE = "Approve", since it more obvious that it is a declaration in the context of a process or a workflow.

Constant class

If entities like logical ids, transition ids, processes, which can be managed in multiple rules, they should rather be declared in a constant class, so they can be referenced from multiple locations. See example below.

	//Processes
	private final String PR_CG = ClaimConstants.PROCESS_CLAIM_GLOBAL; 
	private final String PR_CI = ClaimConstants.PROCESS_CLAIM_INVESTIGATE; 

public class ClaimConstants {
	// Organization units
	public static final String DEFAULT_ORGUNIT_TRANSPORT = "Q_TRP";
	public static final String DEFAULT_ORGUNIT_PURCHASE = "Q_PUR";
	public static final String DEFAULT_ORGUNIT_ADMINISTRATION = "Q_ADM";
	//Transition Events in Processes
	public static final String TE_COORDINATED = "Coordinated";
	public static final String TE_MOREINFORMATION = "MoreInformation";
	public static final String TE_REGISTRED_SOLVE = "RegistredSolve";
	public static final String TE_COMPLEMENT_INVESTIGATE = "ComplementInvestigate";
	public static final String TE_IMPLEMENTED = "Implemented";
	//Processes
	public static final String PROCESS_CLAIM_GLOBAL = "ClaimGlobal";
	public static final String PROCESS_CLAIM_LOCAL = "ClaimLocal";
	public static final String PROCESS_CLAIM_INVESTIGATE = "ClaimInvestigate";
	//Start Events
	public static final String SE_CLAIM_INVESTIGATE = "start";
	
}

Workflow rule (AbstractRuleExecute)

Naming of rule and package

The package shall end with ".rule". The rule itself shall be named as the related portlet, possibly with some additional naming for the context, since a portlet can exist multiple times in one workflow or in multiple workflows.

Rule structure

Rules can be executed via execution or exit points at several states in the dialog processing for a portlet, when it transits from another portlet or to another portlet. They are generally divided into the ones that executes before displaying the portlet, the “out-processing” or the one after the portlet has been displayed, the “in-processing”.

The picture below shows the flow for a single portlet in a transition flow, and all the possible exit points.

PreDMProcOut is an execution point for managing data before you access the data source, like managing keys for a data request.

PostDMProcOut is an execution point for managing data directly after receiving the data result set.

Sametime is an execution point for managing data before starting a sametime portlet.

PreDialogOut is an execution point for managing data before the data is processed for creating the user dialog. In this point you should do UI changes such as setting segments and/or fields visible or hidden.

PostDialogOut is an execution point for managing the data after the user dialog has been created, but before the portlet is rendered. In this point you should do UI changes associated with styling such as setting fonts, background colors or text colors.

PreDialogIn is an execution point for managing the data in the dialog, before the system starts processing it.

PreDMProcIn is an execution point for managing data before the data is processed against the data sources.

PostDMProcIn is an execution point for managing the data after it has been processed against the data sources, but before the processing of the next portlet starts.

Stack is an execution point for managing the portlet stack like controlling the dialog event.

PreDocumentOut is an execution point for managing UI changes such as setting segments and/or fields visible or hidden.

ChildClose is an execution point for managing what shall happen when a child is closed (like a sametime), which can be to change the dialog event.

Rule example

A rule shall follow the pattern of these execution points. The main methods shall thereby extend the abstract one's, like protected boolean postDMProcOut() {...}. Then you get a clear overview at what execution point the rule is acting on. See example below.

      public boolean preValidation() {
		String transEvent = getTransitionEvent();

		if (transEvent.equals(TE_ADD_ATTACHMENT)) {
			return addAttachment();
		}

		return true;
	}

	public boolean preDMProcIn() {
		String transEvent = getTransitionEvent();
		
		if (transEvent.equals(TE_CREATE_MESSAGE) || transEvent.equals(TE_CREATECOPY_MESSAGE)) {
			return create();
		}
		
		if (transEvent.equals(TE_SEND_MESSAGE)) {
			return send(processData);
		}
		if (transEvent.equals(TE_DELETE_MESSAGE)) {
			return delete(processData);
		}
		if (transEvent.equals(TE_REMOVE_ATTACHMENT)) {
			return removeAttachment(processData);
		}

		return true;
	}

Do's and don'ts

Here is a list of do's and don'ts.

Do's

• A method shall be visible in one screen. If it longer, break it down in several methods
• Use constants for defining values. Either in the actual rule, but preferably in a constant class. The constant class can be per application or for the customer.
• All references in a rule to components "outside" the rule shall be declared as constants in the rule or in a constant class.

Don'ts

• Avoid "string coding"!! Work with typed definitions for all type of definitions and values.