This section describes how a process run definition can be implemented.
What does this section cover?
In order to implement a process run definition, you need to:
- Create a new data object class extending com.crm.dataobject.ViewObject class.
- Create five new summary pages.
- Create a new data entry page.
- Create a new user interface class extending com.crm.process.processrun.CRMUIProcessRunDefinitionBean class.
- Create a new class extending com.crm.businessobject.processrun.ProcessRunDefinitionXMLUtilBean class, to save and load any criteria, action inputs and/or scheduling settings.
- Define the process in modules metadata file.
In the example below, we will implement a Rewards Settlements Run Definition which is used to evaluate customer events and spend transactions in order to debit or credit the related Organizational Unit's Accounts Receivable. The accounts receivable to be debited and/or credited are retrieved based on a set of criteria defined by the user. Rewards Settlements Run Definition, just like any other process run definition, can be executed ad hoc or on a recurring basis, based on the scheduling settings.
1. Create Data Object Class
The new data object class must extend com.crm.dataobject.ViewObject class and must implement both getViewMandatoryFields() and getAssociatedObjects() methods. The associated objects will be used by setMandatoryFields() method of com.crm.dataobject.ViewObject for mandatory field calculation. This method calculates the associated objects' mandatory fields and along with the ones defined in getViewMandatoryFields() method it constructs the new data object's defaultMandatoryFields linked hash map.
A com.crm.process.utilities.SchedulerTask object must be defined as well, in order for the process run definition to be handled by the scheduler mechanism.
public class RewardSettlementRunDefinition extends ViewObject {
/**
*
*/
private static final long serialVersionUID = 1L;
private CRMDOProcessRunDefinition processRunDefinition;
private SchedulerTask schedulerTask;
//input settings
private RewardSettlementType rewardSettlementType;
//criteria
private Set<RewardSchemeCriterion> schemeCriteria;
private Integer daysAgo;
public CRMDOProcessRunDefinition getProcessRunDefinition() {
return processRunDefinition;
}
public void setProcessRunDefinition(CRMDOProcessRunDefinition processRunDefinition) {
this.processRunDefinition = processRunDefinition;
}
public SchedulerTask getSchedulerTask() {
return schedulerTask;
}
public void setSchedulerTask(SchedulerTask schedulerTask) {
this.schedulerTask = schedulerTask;
}
public RewardSettlementType getRewardSettlementType() {
return rewardSettlementType;
}
public void setRewardSettlementType(RewardSettlementType rewardSettlementType) {
this.rewardSettlementType = rewardSettlementType;
}
public Set<RewardSchemeCriterion> getSchemeCriteria() {
return schemeCriteria;
}
public void setSchemeCriteria(Set<RewardSchemeCriterion> schemeCriteria) {
this.schemeCriteria = schemeCriteria;
}
public Integer getDaysAgo() {
return daysAgo;
}
public void setDaysAgo(Integer daysAgo) {
this.daysAgo = daysAgo;
}
@Override
protected LinkedHashMap<String, CRMDO> getAssociatedDataObjects() {
LinkedHashMap<String, CRMDO> dataObjects=new LinkedHashMap<String, CRMDO>();
dataObjects.put("processRunDefinition", getProcessRunDefinition());
return dataObjects;
}
@Override
public LinkedHashMap<String, String> getViewMandatoryFields() {
LinkedHashMap<String, String> viewMandatoryFields = new LinkedHashMap<String, String>();
viewMandatoryFields.put( "rewardSettlementType", "key_reward_settlement_type");
return viewMandatoryFields;
}
2. Create Summary Pages
Five new summary pages need to be implemented in order to give the user all the necessary information about the process run definition, its runs, and their results.
2.a. Process Run Definition Summary Page
The first summary page to create is the process run definition summary page, which is the main summary page that will display all the process run definition records.
As you can see, two drill-down summary pages must be created and included in the main summary page: process runs and previous version pages.
2.a.i. Process Runs Drilldown Summary Page
Process runs summary page shows all the process runs created by a specific process run definition.
As you can see, two drill-down summary pages must be created and included in process runs summary page: processed successfully and processed with errors pages.
2.a.i.1. Processed Successfully Summary Page
Processed successfully summary page shows all the entities that were processed successfully by a specific process run.
Processed with errors summary page shows all the entities that their processing, by a specific process run, failed.
2.b. Previous Version Summary Page
Previous version summary page shows the previous version of a specific process run.
3. Create Data Entry Page
A new data entry page must be implemented to give the user to create, view, modify, delete or apply other operations on a process run definition.
4. Create User Interface Class
The new user interface class must extend com.crm.process.processrun.CRMUIProcessRunDefinitionBean class.
When creating a new process run definition, the process and module attributes to set on the new data objects must be the same as the ones defined in modules metadata file. setMandatoryFields() method calculates the associated objects' mandatory fields and along with the ones defined in getViewMandatoryFields() method it constructs the new data object's defaultMandatoryFields linked hash map.
@Stateless
@LocalBean
public class CRMUIRewardSettlementRunDefinitionBean extends CRMUIProcessRunDefinitionBean {
/**
*
*/
private static final long serialVersionUID = 1L;
private static final String PROCESS_RUN_LOG_ENTRIES_EXIST = "PROCESS_RUN_LOG_ENTRIES_EXIST";
private static final String IS_PROCESS_RUN_DEF_LATEST_VERSION = "IS_PROCESS_RUN_DEF_LATEST_VERSION";
private static final String LATEST_PROCESS_RUN_DEF_ID = "LATEST_PROCESS_RUN_DEF_ID";
private static final String PROCESS ="REWARD_SETTLEMENT_PROCESSING";
private static final String MODULE ="REWARDS";
@EJB private CRMBOProcessRunDefinitionBean processRunDefinitionBean;
@EJB private RewardSettlementProcessRunDefinitionXMLUtilBean rewardSettlementProcessRunDefinitionXMLUtilBean;
@EJB private CRMBOProcessRunLogBean processRunLogBean;
@EJB private CRMBORewardSchemeBean rewardSchemeBean;
@EJB private CRMValidatorBean validatorBean;
@EJB private CRMBORewardDefinitionBean rewardDefinitionBean;
@EJB private RewardDefinitionXMLUtilBean rewardDefinitionXMLUtilBean;
/**
* @see CRMUIProcessRunDefinitionBean#CRMUIProcessRunDefinitionBean()
*/
public CRMUIRewardSettlementRunDefinitionBean() {
//do nothing
}
/**
* Loads a reward settlement run definition form.
*
* @param id - the reward settlement run definition id to load
* @return the loaded form
* @throws Exception
*/
public RewardSettlementRunDefinition loadForm(String id) throws Exception {
//Load the process run definition from db
CRMDOProcessRunDefinition definition = (CRMDOProcessRunDefinition)processRunDefinitionBean.load(id);
//Set process run definition additional information
definition = processRunDefinitionBean.loadAdditionalInformation(definition);
//Create new RewardSettlementRunDefinition instance and set process run definition object
RewardSettlementRunDefinition rewardSettlementRunDefinition = new RewardSettlementRunDefinition();
rewardSettlementRunDefinition.setProcessRunDefinition(definition);
//Load criteria input and scheduling settings from XML
rewardSettlementRunDefinition = rewardSettlementProcessRunDefinitionXMLUtilBean.loadFromXML(rewardSettlementRunDefinition);
//Initialise criteria
rewardSettlementRunDefinition = rewardSettlementProcessRunDefinitionXMLUtilBean.initialize(rewardSettlementRunDefinition);
//Set aliases
if (processRunLogBean.exists(rewardSettlementRunDefinition.getProcessRunDefinition()))
{
rewardSettlementRunDefinition.setAlias(PROCESS_RUN_LOG_ENTRIES_EXIST, "1");
}
else
{
rewardSettlementRunDefinition.setAlias(PROCESS_RUN_LOG_ENTRIES_EXIST, "0");
}
String latestVersionID = getLatestVersionID(rewardSettlementRunDefinition.getProcessRunDefinition());
if (latestVersionID==null || ( latestVersionID!=null && latestVersionID.equals(id)))
{
rewardSettlementRunDefinition.setAlias(IS_PROCESS_RUN_DEF_LATEST_VERSION, "1");
rewardSettlementRunDefinition.setAlias(LATEST_PROCESS_RUN_DEF_ID, latestVersionID);
}
else
{
rewardSettlementRunDefinition.setAlias(IS_PROCESS_RUN_DEF_LATEST_VERSION, "0");
rewardSettlementRunDefinition.setAlias(LATEST_PROCESS_RUN_DEF_ID, latestVersionID);
}
//Set mandatory fields
rewardSettlementRunDefinition.setMandatoryFields();
return rewardSettlementRunDefinition;
}
/**
* Creates a notification run definition.
*
* @return a notification run definition
* @throws Exception
*/
public RewardSettlementRunDefinition createButton() throws Exception {
RewardSettlementRunDefinition rewardSettlementRunDefinition = new RewardSettlementRunDefinition();
//Initialise attributes
rewardSettlementRunDefinition.setProcessRunDefinition((CRMDOProcessRunDefinition)processRunDefinitionBean.construct());
rewardSettlementRunDefinition.setSchedulerTask(new SchedulerTask());
rewardSettlementRunDefinition.setSchemeCriteria(constructRewardSchemeCriterion());
//Set process = process id as defined in modules metadata file
rewardSettlementRunDefinition.getProcessRunDefinition().setProcess(PROCESS);
//Set module = module id as defined in modules metadata file
rewardSettlementRunDefinition.getProcessRunDefinition().setModule(MODULE);
//Set type default value
rewardSettlementRunDefinition.setRewardSettlementType(RewardSettlementType.BOTH);
//Set the definition's mandatory fields
rewardSettlementRunDefinition.setMandatoryFields();
return rewardSettlementRunDefinition;
}
private Set<RewardSchemeCriterion> constructRewardSchemeCriterion() throws Exception {
Set<RewardSchemeCriterion> schemeCriteria = new HashSet<RewardSchemeCriterion>();
//schemeCriteria.add(new RewardSchemeCriterion());
return schemeCriteria;
}
/**
* Saves a reward run definition.
* @param rewardSettlementRunDefinition - the reward run definition to save
* @return the saved reward run definition
* @throws Exception
*/
public RewardSettlementRunDefinition saveButton(RewardSettlementRunDefinition rewardSettlementRunDefinition) throws Exception {
//Set and validate the definition's mandatory fields
rewardSettlementRunDefinition.setMandatoryFields();
validateMandatoryFields(rewardSettlementRunDefinition);
//Convert criteria, input settings and scheduling settings to XML and set them to process run definition data object.
rewardSettlementRunDefinition = rewardSettlementProcessRunDefinitionXMLUtilBean.constructXML(rewardSettlementRunDefinition);
CRMDOProcessRunDefinition processRunDefinition = rewardSettlementRunDefinition.getProcessRunDefinition();
//Validate process run definition
if(processRunDefinition.getCode()==null)
{
processRunDefinition.setCode(processRunDefinitionBean.getNextSequenceNumber(SequenceNumber.PROCESSRUNDEFINITIONCODES));
}
validateCriteria(rewardSettlementRunDefinition);
validateActionInput(rewardSettlementRunDefinition);
validateSchedulingSettings(rewardSettlementRunDefinition);
CRMDORewardDefinition rewardDefinition= (CRMDORewardDefinition)rewardDefinitionBean.loadActiveDefinition();
rewardDefinition = rewardDefinitionXMLUtilBean.initialize(rewardDefinition);
if(rewardDefinition.getSettlementAutomation()==null || rewardDefinition.getSettlementAutomation().getInvoiceType()==null || rewardDefinition.getSettlementAutomation().getInvoiceProduct() == null)
{
throw new CannotExecuteSettlementNoConfigurationInRewardDefinitionException(getCRMSession());
}
processRunDefinitionBean.validateAndSave( rewardSettlementRunDefinition.getProcessRunDefinition() );
String latestVersionID = getLatestVersionID(rewardSettlementRunDefinition.getProcessRunDefinition());
//if process run definition is modified
if (latestVersionID==null || ( latestVersionID!=null && latestVersionID.equals(rewardSettlementRunDefinition.getProcessRunDefinition().getId())))
{
rewardSettlementRunDefinition.setAlias(IS_PROCESS_RUN_DEF_LATEST_VERSION, "1");
}
else
{
rewardSettlementRunDefinition.setAlias(IS_PROCESS_RUN_DEF_LATEST_VERSION, "0");
}
return rewardSettlementRunDefinition;
}
/**
* Validate the criteria of the notification run definition
*
* @param notificationRunDefinition - the notification run definition to validate the criteria of
* @throws Exception
*/
protected void validateCriteria(RewardSettlementRunDefinition rewardSettlementRunDefinition) throws Exception{
if (ServiceUtil.isInitialized(rewardSettlementRunDefinition.getSchemeCriteria()) )
{
validatorBean.validateUniqueRecord(
"Scheme",
new ArrayList<CRMDO>(rewardSettlementRunDefinition.getSchemeCriteria()),
new String[]{"scheme.name"},
new String[]{"Name"});
}
}
/**
* Validate the scheduling settings of the notification run definition
*
* @param notificationRunDefinition - the notification run definition to validate the scheduling settings of
* @throws Exception
*/
protected void validateSchedulingSettings(RewardSettlementRunDefinition rewardSettlementRunDefinition) throws Exception{
}
/**
* Loads a reward run definition form.
*
* @param rewardSettlementRunDefinition - the reward run definition to load
* @return the loaded form
* @throws Exception
* @throws CannotModifyException
*/
public RewardSettlementRunDefinition editButton(RewardSettlementRunDefinition rewardSettlementRunDefinition) throws Exception, CannotModifyException {
CRMDOProcessRunDefinition definition = (CRMDOProcessRunDefinition)processRunDefinitionBean.load(rewardSettlementRunDefinition.getProcessRunDefinition().getId());
if(definition==null)
{
definition = processRunDefinitionBean.loadLatest(rewardSettlementRunDefinition.getProcessRunDefinition().getCode());
}
rewardSettlementRunDefinition = loadForm(definition.getId());
if(rewardSettlementRunDefinition.getAlias(PROCESS_RUN_LOG_ENTRIES_EXIST).equals("1"))
{
rewardSettlementRunDefinition = amendButton(rewardSettlementRunDefinition);
}
return rewardSettlementRunDefinition;
}
/**
* Amend a reward run definition.
*
* @param rewardSettlementRunDefinition - the reward run definition to amend
* @return the amended reward run definition
* @throws Exception
* @throws CannotModifyException
*/
public RewardSettlementRunDefinition amendButton(RewardSettlementRunDefinition rewardSettlementRunDefinition) throws Exception {
CRMDOProcessRunDefinition processRunDefinition = rewardSettlementRunDefinition.getProcessRunDefinition();
CRMDOProcessRunDefinition newProcessRunDefinition = (CRMDOProcessRunDefinition) processRunDefinition.clone();
newProcessRunDefinition.setVersion(new Integer(processRunDefinition.getVersion().intValue()+1));
rewardSettlementRunDefinition.setProcessRunDefinition(newProcessRunDefinition);
rewardSettlementRunDefinition.setAlias(PROCESS_RUN_LOG_ENTRIES_EXIST, "0" );
rewardSettlementRunDefinition.setAlias(IS_PROCESS_RUN_DEF_LATEST_VERSION, "1");
return rewardSettlementRunDefinition;
}
/**
* Submit a reward run definition.
*
* @param rewardSettlementRunDefinition - the reward run definition to submit
* @return the submitted form
* @throws Exception
* @throws CannotModifyException
*/
public RewardSettlementRunDefinition submitButton(RewardSettlementRunDefinition rewardSettlementRunDefinition) throws Exception {
CRMDORewardDefinition rewardDefinition= (CRMDORewardDefinition)rewardDefinitionBean.loadActiveDefinition();
rewardDefinition = rewardDefinitionXMLUtilBean.initialize(rewardDefinition);
if(rewardDefinition.getSettlementAutomation()==null || rewardDefinition.getSettlementAutomation().getInvoiceType()==null || rewardDefinition.getSettlementAutomation().getInvoiceProduct() == null)
{
throw new CannotExecuteSettlementNoConfigurationInRewardDefinitionException(getCRMSession());
}
CRMDOProcessRunLog processRunLog = (CRMDOProcessRunLog) processRunLogBean.construct(rewardSettlementRunDefinition.getProcessRunDefinition());
submit(processRunLog);
return rewardSettlementRunDefinition;
}
/**
* Validate the action input of the reward settlement run definition
*
* @param definition - the reward settlement run definition to validate the action input of
* @throws Exception
*/
protected void validateActionInput(RewardSettlementRunDefinition definition) throws Exception{
if (definition.getRewardSettlementType()==null)
{
throw new MandatoryFieldException(getCRMSession(),"key_reward_settlement_type");
}
}
/**
* Delete a reward run definition.
*
* @param rewardSettlementRunDefinition - the reward run definition to delete
* @return the deleted form
* @throws Exception
* @throws CannotModifyException
*/
public RewardSettlementRunDefinition deleteButton(RewardSettlementRunDefinition rewardSettlementRunDefinition) throws Exception {
processRunDefinitionBean.validateAndDelete(rewardSettlementRunDefinition.getProcessRunDefinition());
return rewardSettlementRunDefinition;
}
/**
* Adds a list of reward schemes to the reward definition run.
*
* @param entityIDs - the ids of the reward schemes
* @return the list of reward schemes
* @throws Exception
*/
public ArrayList<CRMDO> addRewardSchemeCriterionButton(ArrayList<String> entityIDs) throws Exception {
ArrayList<CRMDO> dtos = new ArrayList<CRMDO>();
if (entityIDs!=null && entityIDs.size() > 0)
{
for (int i=0; i<entityIDs.size(); i++)
{
CRMDORewardScheme scheme = (CRMDORewardScheme)rewardSchemeBean.load(entityIDs.get(i));
RewardSchemeCriterion schemeCriterion=new RewardSchemeCriterion();
schemeCriterion.setScheme(scheme);
dtos.add(schemeCriterion);
}
}
return dtos;
}
/**
* Removes a list of reward scheme criteria from a reward run definition.
*
* @param dtoList - a list of reward scheme criteria to delete
* @return the updated list
* @throws Exception
*/
public ArrayList<CRMDO> removeRewardSchemeCriterionButton(ArrayList<CRMDO> dtoList) throws Exception {
return setDeleted(dtoList);
}
/**
* Loads the reward settlement type options.
*
* @return the reward settlement type options
* @throws Exception
*/
public LookupBuilder getRewardSettlementTypeOptions() throws Exception {
return getRewardSettlementTypeOptions(null);
}
/**
* Loads the reward settlement type options.
*
* @param emptyValue - an empty value for a reward settlement type
* @return the reward settlement type options
* @throws Exception
*/
public LookupBuilder getRewardSettlementTypeOptions(String emptyValue) throws Exception {
LookupBuilder builder = new LookupBuilder();
if (emptyValue!=null)
{
builder.build("", emptyValue);
}
RewardSettlementType[] rewardSettlementTypes = RewardSettlementType.values();
for (int i=0; i<rewardSettlementTypes.length; i++)
{
RewardSettlementType rewardSettlementType = rewardSettlementTypes[i];
builder.build(rewardSettlementType.toString(), rewardSettlementType.getLabel());
}
return builder;
}
}
In this case, a UI class have to implement as well, extending the CRMUIProcessRunDefinitionBean. Also, module id and process id, must be defined in the UI as they declared in the module.xml file. To implement the basic functionality, we will need to create the following methods: createButton, loadForm, editButton, saveButton, submitButton, deleteButton and amendButton, as demonstrated below:
Later on, data entry page must be implemented by giving the ability to the user create, view, modify, delete or apply other operations on a process run record. Below, we can see the detail page of the process run definition and specifically the process runs tab, showing the successful whilst failed runs.
In addition, an XMLUtilBean need to be implemented, in order to save action inputs, criteria and schedule settings in the xml. Also this, messageRunDefinitionXMLUtilBean extends ProcessRunDefinitionXMLUtilBean.
On the last step, the CRMProcessRunBean mentioned in the module.xml as additional process need to be implemented whilst the method executeMessageProcess which executes the process runs via threats mechanism like in Implement a Multithreaded Process section. Firstly, process run method saves the action inputs. Then each process run request processed from a thread and if procedure works correctly, the next process run prepares to been processed and the current one saved as completed. On the other hand, if something goes wrong, the current process run is saved as failed and moves to process the next request. This procedure continues until all the process run requests pass from the multi-threading mechanism. As a result, all the successful and failed process runs are illustrated in the summary page image above. Also, below is illustrated the example of the multi-threaded method implemented:
public class CRMProcessSmsRunBean extends CRMProcessRunBean {
@EJB private smsMessageRunDefinitionXMLUtilBean messageRunDefinitionXMLUtilBean;
...
public void executeMessageProcess(CRMDOProcessRunLog processRun) throws Exception {
CRMDOProcessRunDefinition processRunDefinition = processRun.getProcessRunDefinition();
smsMessageRunDefintion messageRunDefinition= new smsMessageRunDefintion();
messageRunDefinition.setProcessRunDefinition(processRunDefinition);
messageRunDefinition = messageRunDefinitionXMLUtilBean.loadProcessingRunDefinition(messageRunDefinition);
CRMDOProvProvider provProvider = exsetProviderBean.loadEffective();
provProvider = exsetProviderBean.setObjectsFromXML(provProvider);
processRun.setStatus(ProcessRunLogStatus.IN_PROGRESS);
processRun.setStartDate(getCurrentDate());
processRunLogBean.save(processRun);
Boolean processComplete = new Boolean(false);
JDBCConnection connection= null;
try
{
//At this point is implemented the threats mechanism like in Implement a Multithreaded Process section
catch (Exception e)
{
saveEntityLogRecord(
processRun,
"",
"",
ProcessRunLogEntityStatus.FAILED,
e.getClass().getSimpleName(),
ExceptionUtil.getStackTrace(e));
processRun.setEndDate(getCurrentDate());
processRun.setStatus(ProcessRunLogStatus.FAILED);
processRunLogBean.save(processRun);
processRun = saveNextProcessRun(processRun);
if(connection!=null)
connection.close();
}
if (processComplete)
{
processRun.setStatus(ProcessRunLogStatus.COMPLETED);
processRun.setEndDate(getCurrentDate());
processRun = saveNextProcessRun(processRun);
processRunLogBean.save(processRun);
}
}
...
}
CRMProcessSmsRunBean must be also bind to the server by specifying the EJB in the ibm-ejb-jar-bnd.xml binding file.This xml found in CRMEJB > ejbModule > METADATA-INF
<ejb-jar-bnd>
...
<session name="CRMProcessProcessSmsRun" simple-binding-name="ejb/CRMProcessProcessSmsRun" />
...
</ejb-jar-bnd>
The process must also be added in the CrmEJB/ejbModule/META-INF/ibm-ejb-jar-ext.xml to define how much time the process could been executing on WebSphere server as follows:
...
<session name="CRMProcessProcessSmsRun">
<global-transaction transaction-time-out="86400" />
<time-out value="86400" />
</session>
...
Then the process, should be mentioned in CrmEJB/ejbModule/META-INF/jboss-ejb3.xml file where we declare in enterprise beans, the process and in assembly descriptor we mention the timeout of the execution on WildFly server as follows:
...
<session>
<ejb-name>CRMProcessProcessSmsRunBean</ejb-name>
<ejb-class>com.crm.process.provisioning.sms.CRMProcessProcessSmsRunBean</ejb-class>
<session-type>Stateless</session-type>
</session>
...
<container-transaction>
<method>
<ejb-name>CRMProcessProcessSmsRunBean</ejb-name>
<method-name>*</method-name>
<method-intf>Local</method-intf>
</method>
<tx:trans-timeout>
<tx:timeout>86400</tx:timeout>
<tx:unit>Seconds</tx:unit>
</tx:trans-timeout>
</container-transaction>
...