Wednesday, 6 August 2014

CQ5 Workflow Tutorial Part - III

In my last post , I discussed about "how to use inbuilt processes using process steps". In this post I will show you how to create your custom  process and how to use them.

Agenda of this post
  1. Creating custom process Step.
  2. How to use this custom process Step.
  3. Explanation of all arguments in Workflow Process Interface execute() method.
  4. Use of all these arguments.
For doing all these stuff, I am creating a project using adobe maven archetype whose structure looks like - 
For creating a custom process step you have to implement WorkflowProcess interface in your java class. It provide a method named as execute() with three parameters, I will explain you all of these parameters.

Register your class as a component & add some properties as enabled, immediate, these property indicates-
That your service will be enabled immediately at the time of deployment of your project.

Now register your class as a service with some configurations -
i.e. add a property named as "process.label". This property defines a name of your process i.e. in workflow process step, you are able to see this process in select process drag drop menu with a name define using this property.



your final code will looks like -

import com.adobe.granite.workflow.WorkflowException;
import com.adobe.granite.workflow.WorkflowSession;
import com.adobe.granite.workflow.exec.WorkItem;
import com.adobe.granite.workflow.exec.WorkflowProcess;
import com.adobe.granite.workflow.metadata.MetaDataMap;
import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Properties;
import org.apache.felix.scr.annotations.Property;
import org.apache.felix.scr.annotations.Service;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

@Component(immediate = true, enabled = true, metatype = false)

@Service
@Properties({
        @Property(name = "service.description", value = "Service for Showing custom workflow demo."),
        @Property(name = "service.vendor", value = "versatileankur@blogspot.in"),
        @Property(name = "process.label", value = "Blog Process")
})
public class CustomProcess implements WorkflowProcess {

    private static final Logger LOGGER = LoggerFactory.getLogger(CustomProcess.class);


    @Override

    public void execute(WorkItem workItem, WorkflowSession workflowSession, MetaDataMap metaDataMap) throws WorkflowException {
        LOGGER.info("\n\n\n\n==== Custom workflow Creation completed successfully. \n thanks for creation");
    }
}

you have to add workflow dependencies i.e. com.adobe.granite.workflow.api in to your bundle pom.xml file. Now after writing this code just use mvn clean install -P autoInstallPackage command. you are able to see in /system/console/bundle, search for blog, you will get your bundle in active state i.e. everything works fine.

Now go to your blog workflow model which is shown below and follow the steps  as written below-




















Select blog Process Step we will get a dialog select second tab your screen looks like-




















In Process drop down we will see your custom workflow with a name Blog Process,
Check Handle Advance checkbox
click OK.
Save your workflow.
Go to any page in my case I select geometrixx/en.html page.
Select workflow tab.
Select your blog workflow model.
As shown below




















Click on Start workflow you will see your page refresh and workflow field becomes empty it means your code run fine. Now go to your crx-quickstart/logs/error.log file.
Press Ctrl+End or search for "Custom workflow Creation" you will see your comment printed there. It means everything is fine & working. By following above steps you are able to create custom workflow process step.

Explanation of method arguments.

workItem

  1. workItem represent the workItem corresponding to current step, it will be present till this step is running and not present in any other process or participant step. Using this workItem object you are able to access workflow instance or metaDataMap related to only this workItem.
  2. you can also access workflow metaDataMap using workItem object using workItem.getWorkflow().getMetaDataMap() method it will return metaDataMap related to whole workflow model.
  3. If you use workItem.getMetaDataMap() then it will return only that metaDataMap object which is related to this step only and not present in any other workflow step.
  4. You are also able to get payload of this workflow using getWorkflowData() method of workItem.
  5. You can explore this API from this link- WorkflowData.
workflowSession
  1. workflowSession represent the session related to whole workflow, using this Object you can deal with all node using history node of workflow instance. You can explore this interface using given link WorkflowSession.
metaDataMap

  1. this metaDataMap object is related to dialog properties which you select in process dialog. It provides you only those properties which are under process tab i.e. this will provide you information about - 
  2. what process you selected?
  3. Either you select Handle Advance checkbox or not?
  4. & also provide you list of arguments.
These there properties comes under three different property names as PROCESS, PROCESS_AUTO_ADVANCE, PROCESS_ARG.
PROCESS_ARG is of type 
String i.e. what ever you write in Argument text area it will be accessed as a single string & you can provide your custom logic to parse that string.
For testing all of these just write two line in execute() method of your CustomProcess class.

 @Override
    public void execute(WorkItem workItem, WorkflowSession workflowSession, MetaDataMap metaDataMap) throws WorkflowException {
        LOGGER.info("\n\n\n\n===== Custom workflow Creation completed successfully. \n thanks for creation");
        LOGGER.info("\n\n\n\n==============="+metaDataMap.get("PROCESS_ARGS", new String()));
        LOGGER.info("\n\n\n\n==============="+metaDataMap);
    }

Use mvn clean install -P autoInstallPackage command your bundle is successfully deployed into repository. Now go to blog workflow model  -> select blog process step -> select process tab -> type any text in Arguments text area as shown below.




















Now go to your geometrixx/en.html page and go to workflow tab-> select blog workflow - > click on start workflow buttonGo to crx-quickstart/logs/error.log

you will see Metadata map and PROCESS_ARG values which we provide form  workflow model dialog. This is all done in this post.

github repository link
https://github.com/vietankur009/blog


Happy Coding
Namah Shivay