KEW: Building Custom Workflows

  Quick review of key topics   KEW Routing Components   The KEW Document Type Config file   Building a Proposal Development workflow   Other features to explore

  In KC, business data and processes are encapsulated within a document (eg Proposal Development Document)

  The document workflow – routing, approvals, etc. – is implemented using the Rice module Kuali Enterprise Workflow (KEW)

  Kuali Identity Management (KIM) also provides hooks for workflow routing

  XML configuration file   Describes features and behavior of the

document to KEW, including its routing and approval chain – AKA the Process Definition

  ProposalDevelopmentDocument.xml

  Parent – the parent document type. Document types are hierarchical – attributes are inherited from the parent and can be overridden.

  Also useful for assigning KIM roles at document type – e.g., assign admin role to all Preaward maintenance documents

<documentType> … <parent>KC</parent>

KC Document

Maintenance Document

Award Maintenance

Document

Compliance Maintenance

Document …

PropDev Document …

  A Java class that will be called after a KEW action is taken on a document.

  This allows documents to code some special behavior after certain steps in the routing.

  For example, we use the doRouteStatusChange postprocessor hook to set custom statuses on the proposal development document

<postProcessorName>org.kuali.rice.kns.workflow.postprocessor.KualiPostProcessor</postProcessorName>

  A group of users who can take super user administrative actions on the document

  The group of users who will get an action request for the document if there is a problem with the routing and it goes into exception routing

<superUserGroupName namespace="KC-WKFLW">OSP Superuser</superUserGroupName>

<defaultExceptionGroupName namespace="KC-WKFLW">ProposalAdmin</defaultExceptionGroupName>

  The Action to call when the document is opened from the doc search or action list

<docHandler>${kuali.docHandler.url.prefix}/proposalDevelopmentProposal.do?methodToCall=docHandler</docHandler>

  Policies – Allow you to configure behavior on a doc type basis   DOCUMENT_STATUS_POLICY – Display KEW

route status or custom application document status (status specific to that document)

  LOOK_FUTURE – Display the future action requests panel on the route log (screen shot)

<policy> <name>DOCUMENT_STATUS_POLICY</name> <stringValue>app</stringValue> </policy>

  Attributes   Render fields specific to this document on doc

search, action list, etc   See document search screen

<attribute> <name>AggregatorSearchAttribute</name> </attribute>

<ruleAttribute> <name>AggregatorSearchAttribute</name> <className>org.kuali.rice.kew.docsearch.xml.StandardGenericXMLSearchableAttribute</className> <label>AggregatorSearchAttribute</label> <description>AggregatorSearchAttribute</description> <type>SearchableXmlAttribute</type> <serviceNamespace>KC</serviceNamespace> <searchingConfig> <fieldDef name="aggregator" title="Aggregator"> <display> <type>text</type> </display>

(cont)

<lookup businessObjectClass="org.kuali.rice.kim.bo.Person"> <fieldConversions> <fieldConversion localFieldName="aggregator" lookupFieldName="principalName" /> </fieldConversions> </lookup> <fieldEvaluation> <xpathexpression>//aggregator/string</xpathexpression> </fieldEvaluation> </fieldDef> <xmlSearchContent> <users> <aggregator> <value>%aggregator%</value> </aggregator> </users> </xmlSearchContent> </searchingConfig> </ruleAttribute>

  Route Path – The order in which route nodes are visited during the document workflow

  Route Nodes – Details about each node   Route Path plus Route Nodes is referred to as

the Process Definition

  Route nodes – The stops on the route path. Many different types of nodes but we will look at 3: requests, role, dynamic.

  Rule Attributes – Tell KEW how to find data within the document used to make routing decisions. For example, here’s how to find the lead unit.

  Rule – Tell KEW what to do when certain conditions are met. For example, when the lead unit is BL-CHEM, route to this person for approval.

  Rule Template   Defines the rule attributes needed to evaluate the

node – e.g., a Unit Number   Links doc types, rules and rule attributes.

Indirection layer that allows reuse of the various components, ie a rule attribute can be used by multiple document types.

  In KIM, permissions and responsibilities are assigned to Roles, and Roles are assigned to Principals (users)

  Permissions are for authorizations   Responsibilities trigger KEW action requests –

role-based nodes will route based on KIM Responsibilities

  Requests nodes will route based on KEW rules

Initiator/Aggregator submits into routing

Principal Investigator

Preaward Specialist Group

Departmental Approvers

OSP Office

Approval Request

Approval Request

Approval Request

Delegation Approval Request Acknowledge for

Submission to Sponsor

  First, build the route path.   Need to keep the split for proposal hierarchy.

Will talk more about split nodes later.   Start at initiated node – document is in

initialized/saved state. Initiator will have a complete request.

  Define the next nodes until we join back up from the split.

<routePath> <start name="Initiated" nextNode="isHierarchyChild" /> <split name="isHierarchyChild"> <branch name="False"> <role name="ProposalPersons" nextNode="PreawardSpecialistInitial" /> <role name="PreawardSpecialistInitial" nextNode="DepartmentApproval" /> <requests name="DepartmentApproval" nextNode="OSPOffice" / <role name="OSPOffice" nextNode="PreawardSpecialistFinal" /> <role name="PreawardSpecialistFinal" nextNode="Join" /> </branch> <branch name="True"> <requests name="WaitForHierarchyDisposition" nextNode="Join" /> </branch> <join name="Join" /> </split> </routePath>

  Next, configure the route nodes.   activationType – Parallel or Serial. If the node generates

multiple requests, should they all go out at once (parallel) or should they be staggered based on the priority defined in the rule (serial)

  mandatoryRoute – There should be at least one recipient at this node; if not, go into exception routing.

  finalApproval – This should be the last node that generates approval requests, if not, go into exception routing

  forceAction – If true, the user should approve again even if they approved earlier in the routing

  Initial Node – Not yet submitted; places a complete request in Initiator’s Action List

  See route log screen

<start name="Initiated"> <activationType>P</activationType> <mandatoryRoute>false</mandatoryRoute> <finalApproval>false</finalApproval> </start>

  Route to PI / CO-PI’s / Key Investigators   Based on KIM Role, not rules   Will send to Roles with ProposalPersons

responsibility for this Proposal   See responsibility screen

<routeNodes> … <role name="ProposalPersons"> <qualifierResolver>ProposalPersonsXPathQualifierResolver</qualifierResolver> <activationType>P</activationType> <finalApproval>false</finalApproval> </role> … </routeNodes>

  To resolve the role, KIM needs a proposal number qualifier.

  XPathQualifierResolver – Tell KEW how to find data in document XML.

<ruleAttribute> <name>ProposalPersons-XPathQualifierResolver</name> <className>org.kuali.rice.kew.role.XPathQualifierResolver</className> <resolverConfig> <qualifier name="proposal">

<xPathExpression>//document/developmentProposalList[1]/org.kuali.kra.proposaldevelopment.bo.DevelopmentProposal[1]/proposalNumber[1]</xPathExpression> </qualifier> </resolverConfig> </ruleAttribute>

  You can look at the XML for a specific document using the Document Operation screen

  See Document Operation screen

<documentContent><applicationContent><org.kuali.kra.workflow.KraDocumentXMLMaterializer> ... <developmentProposalList > <org.kuali.kra.proposaldevelopment.bo.DevelopmentProposal> <proposalNumber>10000</proposalNumber> ... </documentContent>

  Role-based routing   Specify NullQualifierResolver because this is

not based on rules or document roles – based on KIM responsibility

  See Preaward Specialist role screen

<role name="PreawardSpecialistInitial"> <qualifierResolverClass>org.kuali.rice.kew.role.NullQualifierResolver</

qualifierResolverClass> <activationType>P</activationType> <finalApproval>false</finalApproval> </role>

  Rule-based requests node   Again, we use Xpath to tell KEW how to find

the data it needs to make a routing decision, then specify a rule for that data

  All linked by rule template

<requests name="DepartmentApproval"> <ruleTemplate>DepartmentApproval</ruleTemplate> <activationType>S</activationType> <finalApproval>false</finalApproval> </requests>

  The rule template links to the rule attribute which provides the unit number

<ruleTemplate> <name>DepartmentApproval</name> <description>Department Approval Routing Rule</description> <attributes> <attribute> <name>DepartmentApprovalAttribute</name> <required>false</required> </attribute> </attributes> </ruleTemplate>

<ruleAttribute> <name>DepartmentApprovalAttribute</name> <className>org.kuali.rice.kew.rule.xmlrouting.StandardGenericXMLRuleAttribute</className> … <type>RuleXmlAttribute</type> <serviceNamespace>KC</serviceNamespace> <routingConfig> <fieldDef name="leadUnitNumber" title="Lead Unit" workflowType="RULE"> <display><type>text</type></display> <validation required="false" /> <fieldEvaluation> <xpathexpression>wf:xstreamsafe('//document/developmentProposalList[1]/org.kuali.kra.proposaldevelopment.bo.DevelopmentProposal/ownedByUnitNumber')= wf:ruledata('leadUnitNumber')</xpathexpression> … </ruleAttribute>

<rule> <name>DepartmentApprovalRule</name> <documentType>ProposalDevelopmentDocument</documentType> <ruleTemplate>DepartmentApproval</ruleTemplate> <description>Department Approval Routing Rule for IN-CARD</description> <forceAction>false</forceAction> <ruleExtensions> <ruleExtension> <attribute>DepartmentApprovalAttribute</attribute> <ruleTemplate>DepartmentApproval</ruleTemplate> <ruleExtensionValues> <ruleExtensionValue> <key>leadUnitNumber</key> <value>IN-CARD</value> … </ruleExtensions>

(cont)

<responsibilities> <responsibility> <principalName>chew</principalName> <actionRequested>A</actionRequested> <priority>1</priority> </responsibility> … </rule>

  The rule says that if the unit number is IN-CARD, send an action request to Inez Chew

  Could also be a group or role   What if I need to route a hierarchy – school,

campus? Will see in a minute.   See rules editor screen

  Same as preaward specialist group, except here we have a delegation

  See Role screen

<role name="OSPOffice"> <qualifierResolverClass>org.kuali.rice.kew.role.NullQualifierResolver</qualifierResolverClass> <activationType>P</activationType> <finalApproval>false</finalApproval> </role>

  Going back to the preaward specialists for submission to Sponsor.

  However, this time we are just using an Acknowledge request so the document can proceed to Processed status. See role screen.

<role name="PreawardSpecialistFinal"> <qualifierResolverClass>org.kuali.rice.kew.role.NullQualifierResolver</qualifierResolverClass> <activationType>P</activationType> <forceAction>true</forceAction> <finalApproval>false</finalApproval> </role>

  Ingest XML config files; KEW parses the files and inserts data into KEW tables

  See ingester screen

  For unit hierarchy routing – build an approval chain dynamically based on your KC unit hierarchy

  Implement the KEW HierarchyProvider interface – tell KEW how to build a DOM tree

  Replace the Department node with a dynamic node

<routeNodes> … <dynamic name="hierarchy"> <activationType>P</activationType>   <type>edu.iu.uits.kra.workflow.engine.node.hierarchyrouting.SimpleHi

erarchyRoutingNode</type>         <ruleSelector>HierarchicalNamed</ruleSelector>  </dynamic> … </routeNodes>

Indiana University

BL-BL-Approver UA-UA-Approver

BL-ARSC-Approver

BL-CHEM-Approver

BL-BI-Approver

UA-VPIT-Approver

edu.iu.uits.kra.workflow.engin.node.hierarchyrouting.SimpleHierarchyProvider

University Unit Hierarchy Tree

Proposal Approval Units

  NamedRuleSelector: Pick the rule for the given Unit based on a string matching pattern

<rule> <name>hierarchy-UA-VPIT-Approver</name> <documentType>ProposalDevelopmentDocument</documentType> <description>Unit Approver for UA-VPIT</description> <forceAction>true</forceAction> <responsibilities> <responsibility> <principalName>lsalander</principalName> <actionRequested>A</actionRequested> <priority>1</priority> </responsibility> </responsibilities> </rule>

  Graphical view of document hierarchy, Process Definition, KEW roles/permissions/responsibilities

  See doc config screen

  Different types of nodes – split/join nodes for branched routing; email nodes; custom nodes….

  Different types of rule attributes/qualifier resolvers – Java rule attributes, groovy, DataDictionary…

  Compound rules – e.g., route to the Co-PI’s lead unit approvers if the total cost is over 100,000

  And much more!

  Rice 2.0 – Rule authoring user interface (fall 2011)

  Will be able to hook into KEW for routing   Needed for functional equivalence with Coeus

  http://wiki.kuali.org   KC Public Documentation   Rice Public Documentation

  Collaboration lists   kc.technical.collab@kuali.org   rice.collab@kuali.org

  Conferences   Kuali Days 2011 – kuali.org

  rSmart Training   Rice Training – August 15 – 19   KC Training – August 22 – 26