1. Implementing Kuali Rice JA-SIG - April 30, 2008 Eric Westfall

2. Welcome! Welcome to the Implementing Kuali Rice seminar at JA-SIG! What to Expect -Overview of Kuali Rice -Information on Deployment and Integration -Hands-on exercises and examples looking at various components of Rice from a client developer perspective -Hands-on exercises involving setup and installation of a Kuali Rice Standalone Server -First half will be a high-level discussion, second half will be hands-on and fairly technical

3. Overview 1.Hands-on Setup 2.Kuali Rice Overview 3.Deployment and Integration 4.Example: IU’s Kuali Rice Implementation 5.Recipes Sample Application 6.Standalone Rice Server Installation 7.Java Thin Client Integration 8.Embedded KEW Client Integration 9.Institutional Customization 10.eDoc Lite

4. Hands-on Setup

5. We will be using VMware Player Setup Instructions: https://test.kuali.org/confluence/x/dYGQAg

6. Contents of the VMware Image Ubuntu Linux 7.10 JDK 1.5 Maven Subversion Eclipse –recipes sample application –Kuali Rice 0.9.2 –Sample Thin client –Sample Embedded client –Sample eDoc Lite project –Sample Institutional Plugin project

7. Contents of the VMware Image, cont. Oracle XE – contains 3 databases –RICERECIP – for recipe sample application –RICESTAND – for rice standalone –RICEEMBED – for embedded client SQuirrel SQL – an SQL client Tomcat – for rice standalone Various configuration files

8. Kuali Rice Overview

9. What is Kuali Rice? Kuali Rice is a suite of middleware and framework components Made up of several, possibly standalone and swappable, components Applications become a “Rice Client Application” by easily integrating with this middleware

10. Goals of Kuali Rice The vision for Kuali is a plug and play module by module approach to software Kuali started as financials, but has evolved into a suite of administrative software (KFS, KRA, KS) A lot of functionality in Kuali systems –Keeping the Kuali code base as small as possible without impacting quality is key Highly productive development environment –For Kuali projects –For non-Kuali projects

11. Goals continued A common and consistent architecture –Allow developers to understand other rice-enabled projects –Infrastructure would not need to be reinvented on each project - focus on functionality! –Rice team can focus on IT standards, like SOA, that will benefit the entire Kuali software suite – Adoption of other Kuali modules feasible Generic enough for non-Kuali applications

12. Kuali Rice Components KNSKuali Nervous System KEWKuali Enterprise Workflow KSBKuali Service Bus KENKuali Enterprise Notification KIM Kuali Identity Management KOMKuali Organization Management

13. Kuali Nervous System Web-based Application Framework Data Model Driven (Data Dictionary) Provides reusable code, shared services, integration layer, and a development strategy Provides a common look and feel through a screen drawing framework A document-centric (business process) model with workflow as a core concept

14. Kuali Nervous System, Cont. More Core Concepts / Features –Transactional documents –Maintenance documents –Inquiries –Lookups –Business Rules –Data Dictionary

15. Kuali Enterprise Workflow Facilitates routing and approval of business processes throughout an organization Provides re-usable routing rule creation which defines how business processes should be routed Provides hooks for client applications to handle workflow lifecycle events of business processes Routing processes are configurable when the system is live resulting in high availability End users interact with central workflow GUIs for all client applications –Document Search –Action List

16. Kuali Service Bus Service Registry to enable applications and services on the bus to interact with other applications and services Provides synchronous service invocation Provides asynchronous messaging Provides flexible security Provides Quality of Service (QoS) Light Weight – keep it simple

17. Kuali Enterprise Notification Works with the Action List to provide a single place for all institution-related communications –Workflow items come from KEW –Non-workflow items from KEN Non-workflow example items –Overdue library book –A concert on campus –Graduation checklists for seniors Provides a secure and controlled environment for notifying the masses

18. Kuali Enterprise Notification, cont. Eliminate sifting through email Communication broker which provides any combination of action list, text messages, email, etc... Audit trail just as in KEW (Route Log) User preferences for notification types End user interfaces –Viewing notification details –Maintaining the system (admin) –Sending messages (admin)

19. Kuali Identity Management Still under development Once development is complete, will retrofit existing Kuali Rice modules to take advantage of it –Replace current user and workgroup services that are currently implemented as part of KEW –Replace authentication/authorization which is currently part of KEW Keeping it simple to start Will maintain information about persons, groups, roles, etc.

20. Kuali Identity Management, cont. Goals: –Clean and consistent service interfaces used by all Kuali apps; generic enough for non-Kuali apps –Leverage KNS to provide a reference implementation for services; workflow-enabled management application –Flexibility for dynamic attributes associated with IdM entities (persons, groups, roles, etc) –Pluggable integration with other IdM products

21. Kuali Organization Management Still under development Provide a common set of service APIS for Organization and Unit Hierarchy Management Provide an out-of-the-box reference implementation for managing these data structures Goal of becoming the shared infrastructure application for managing organizations and their hierarchies for all Kuali applications

22. Deployment and Integration

23. There are multiple ways to deploy and integrate applications with Kuali Rice –Bundled – Kuali Rice software is “bundled” into your application –Standalone – a standalone server is deployed In addition, when deploying a standalone server, the following client integration options are available, most relate to the KEW module –Embedded KEW – workflow engine is embedded into your application –KEW Java Thin Client –Web Services – for KEW and, eventually, KIM –eDoc Lite We are going to take a detailed look at these

24. Bundled Mode All Kuali Rice modules are embedded into the client application, including the Web Application The Recipe sample application (which we will look at later) runs in this mode. Does not require the deployment of a standalone Rice server Ideal for development or “quickstart” applications This is not desirable for Enterprise deployments of Kuali Rice

25. Bundled Mode Diagram

26. Standalone Rice Server The Standalone Rice Server allows you to run a central Kuali Rice application that can be integrated with multiple clients Facilitates a single KEW Action List, Document Search, etc. Allows for a shared KSB Service Registry Supports multiple integration options for clients: –KEW Java Thin Client –Embedded KEW –Web Services

27. KEW Java Thin Client Allows for a Java client application to integrate with the KEW module of Rice Uses Java Serialization over HTTP All workflow processing happens on the standalone server If the workflow processing requires custom code (i.e. Post Processors), then plug-ins need to be developed and deployed to the server

28. KEW Java Thin Client Diagram

29. Embedded KEW Embedded KEW allows you to configure a workflow engine embedded in your application but still use a standalone rice server This allows for the following: –Integration of database transactions between client application and embedded KEW (via JTA) –Fast - Embedded client talks directly to database –No need for application plug-ins on the server –Still a single KEW web app but scalability is increased because of multiple Workflow Engines

30. Embedded KEW Diagram

31. KEW Web Services There are a few web service endpoints that are exposed from Kuali Rice KEW has a subset of it’s API available using this integration method The KSB allows for exporting of services onto the bus using SOAP Web Services In the future, we hope to add more web service endpoints to Kuali Rice For example, KIM is being designed with web service remoting in mind

32. eDoc Lite Simple, form-based system which uses XML and XSLT In the absence of a separate client application, eDoc Lite can be used to create fairly sophisticated form-based applications Deployed and hosted entirely inside of the Standalone Rice server

33. Bringing it all Together Leveraging the KSB and the previous examples, it’s possible to utilize multiple strategies for KEW integration and deployment Examples: –Some clients running as Thin Clients –Some clients leveraging code deployed in plug-ins on the standalone server –Multiple servers deployed in a cluster for scalability –Some clients integrating directly with web service endpoints –Some clients running in Embedded Mode –Numerous eDoc Lite applications

34. The Whole Picture

35. Example: IU’s Kuali Rice Implementation

36. Example: Indiana University’s Kuali Rice Implementation Thin Clients –HR –ERA –EPIC –TK –SIS Embedded Clients –IUF –Travel (coming soon) –KFS (coming soon)

37. Example: Indiana University’s Kuali Rice Implementation eDoc Lite clients –Office of Affirmative Action –University Graduate School –Safeword Card Requests –OVPR Internal Funding –OVRPA Conflict of Interests –Purchasing Conflict of Interests –SIS Special Credit –IU Health Center –UITS Unit Change Request –…and more on the way!

38. Example: Indiana University’s Kuali Rice Implementation Institutional Customizations –Integration with our LDAP-based User Repository (EDS) –Integration with Active Directory for reading group and role information –Integration with our CAS installation for authentication –Custom component for authenticating with our Email servers (requires SSL) –Various shared routing components deployed in a plug-in

40. Hands-on Setup Checkpoint

41. For those wishing to follow along, let’s take some time to verify your setup is ready and working.

42. Recipes Sample Application

43. We will be using the Recipes Sample Application to look at different pieces of KNS and KEW A simple system for maintaining recipes and categories that they fit into Two Entities (Business Objects) –Recipe –Recipe Category Two Tables (DB Tables) –RECIPES_T –RECIPES_CATEGORIES_T

44. Recipes Sample Application Setup Project is already checked out at /java/projects/recipes and available in Eclipse This application runs with Kuali Rice bundled inside of it (no standalone server) We need to do the following: –Prepare the database (both Recipes and Rice) –Start the web application –Connect to the web application –Import workflow configuration https://test.kuali.org/confluence/x/RgCgAg

45. Review the Business Objects The recipes app is not completely hooked together yet so let’s do it! First we’ll review the Business Objects used by the recipes app. Open the Java files in package edu.sampleu.recipe.bo.* Should include: Recipe Recipe Category

46. How These Link Together We use an ORM (Object Relational Mapper) called Apache OJB XML files combined with a set of Apache Java libraries that automatically persist data in our business objects to our DB Working on replacing with JPA in 0.9.3 - a Java standard –No more XML, use annotations in Java code instead

47. Recipe OJB Mapping Open repository.xml in the recipes project in Eclipse Notice that the mapping for Recipe is missing, let’s add it Open repository.xml in the recipes_reference project in Eclipse Find and copy the mapping for Recipe Now both of our Business Objects are mapped to the database

48. Leveraging the KNS We’ll use the KNS to provide search and detail information on categories and recipes Search = Lookup Detail Info = Inquiry We’ll use the KNS to provide maintenance CRUD operations with workflow backing them CRUD = Maintenance Documents

49. Review RecipeCategory DD We use something called the Data Dictionary (DD) to construct our lookups, inquiries, and maintenance documents Open RecipeCategory.xml - this is the business object DD file –Lookups –Inquiries Open RecipeCategoryMaintenanceDocument.xml - this is the maintenance document XML –CRUD, Workflow, Authz Run the web app to correlate DD to functionality

50. Create Recipe DD Files The Recipe BO does not currently have any Data Dictionary files. Copy Recipe.xml from recipes_reference into recipes Copy RecipeMaintenanceDocument.xml from recipes_reference into recipes Let’s take a look at both of these Data Dictionary files.

51. Create Recipe Workflow Configuration We need workflow configuration as well. Copy in RecipesWorkflowBootstrap.xml and rename to RecipeMaintenanceDocument When done, restart web application. Ingest the modified RecipesWorkflowBootstrap.xml Now let’s create a category and a recipe.

52. Tweaking a Lookup Take a look at the existing lookup for Recipe Category. Let’s remove “id” from it. Open RecipeCategory.xml Remove “id” from the lookup fields Restart the application

53. Tweaking a Maintenance Document Open RecipeMaintenanceDocument.xml Let’s only have one section, so move the content from the details section and put it into the info section Remove the details section Restart the application

54. Initiation Authorization Open RecipeCategoryMaintenance.xml Notice that Recipe Category initiation is restricted to members of the WorkflowAdmin workgroup Login as “fran” (not a member of WorkflowAdmin) Attempt to create a new Recipe Category, you should not be allowed to

55. Add Custom Rule Checks Open the RecipeRules class Open RecipeMaintenanceDocument.xml We want to check to see if any of the ingredients is beef, then we need to make sure that the beef category is chosen Copy code from RecipeRules class in recipes_reference project Start the web application and test it out

56. Leveraging KEW Recipe app uses KEW for workflow functionality and configuration Apply workflow rules to documents Alter workflow processing chains Call external services to make workflow decisions for us Current setup just uses “Ad Hoc” routing Let’s look at a more complex example

57. Adding a Group Approval Make use of the NamedRuleSelector - template-less rules Open RecipesWorkflowBootstrap.xml from recipes_reference Open RecipesUsersWorkgroupsBootstrap.xml from recipes_reference We want any Recipe Category changes to be approved by the “RecipeMasters” workgroup Restart application when changes have been made

58. Learning More We’ve barely scratched the surface There is much more to learn about the KNS and KEW We will explore KEW in more detail later For good examples of how to use the KNS, download the Kuali Financial System (KFS) source code for hundreds of examples There are also some examples in Kuali Rice

59. Standalone Rice Server Installation

60. Standalone Server The Standalone Rice Server download is available in.war form on the Rice website Provides services from the following Rice components: –KEW –KEN –KSB –KIM and KOM coming in 0.9.3

61. Installing the Standalone Server https://test.kuali.org/confluence/x/doKVAg 1.Obtain Standalone.war file 2.Install Tomcat (or other Servlet container) 3.Create database 4.Create Configuration Files 5.Deploy.war into Tomcat 6.Start Tomcat 7.Ingest Bootstrap XML Configuration

62. Java Thin Client Integration

63. Creating a Thin KEW Client The Thin Client communicates with KEW using the WorkflowDocument and WorkflowInfo Java APIs Behind the scenes, communicates using Java Serialization over HTTP with services exposed on the KSB from a Standalone Rice Server Uses Plug-ins when needed for executing code on the standalone server Uses Digital Signatures for security

64. Examining the Sample Thin Client We’ll look at a simple thin client This client will communicate with the KEW services that are deployed in the Standalone Rice server we installed earlier Code located in sample-thin-client project

65. Examining the Sample Thin Client, cont. Open sample-thin-client-config.xml Keystores and Digital Signatures Open SpringBeans.xml Examine ThinClientServlet.java Start application by running: –Launch sample-thin-client.launch Connect to web application at: –http://localhost:8083/thinclienthttp://localhost:8083/thinclient No workflow configuration for this document yet, let’s create it!

66. Configuring workflow for the Sample Thin Client Workflow configuration is in conf directory Open sample-thin-client-1.xml This is a simple routing configuration which allows for “ad-hoc” routing. Ingest sample-thin-client-1.xml Let’s route a Document

67. Document Handler The docHandler is a URL defined on the Document Type to which requests to load the document from KEW are forwarded Primarily used on the Action List and Document Search Ingest sample-thin-client-2.xml Create a new document, search for and select it in Document Search or in Action List

68. The KEW Rule System Ad-hoc Routing is fairly simple Let’s familiarize ourselves with the Rule System so we can implement some more complex routing The Rule System in KEW consists of the following pieces: –Rule Attributes –Rule Templates –Routing Rules

69. Rule Attributes A Rule Attribute is a multi-purpose component with the following responsibilities: –Executes logic for Rule evaluation –Defines how Rule data related to the attribute should be collected –Performs validation of Rule data –Generates XML to attach to the payload Can be written in Java or XML+XPath

70. Rule Templates A Rule Template is a collection of Rule Attributes Defines what data should be collected and evaluated on the Rule Example – A template used to create Rules which route to Deans might include Rule Attributes for “Campus” and “School”

71. Routing Rules Routing Rules evaluate data on the document and determine who should receive action requests (approve, ack, fyi) Configured via a GUI (or imported from XML) The RuleTemplate and it’s attributes define what fields will be collected in the Rule GUI During routing, Rule Evaluation Sets are “selected” at each node. Default is to select by Document Type and Rule Template defined on the Route Node

72. XML-based Routing and Rules All documents in KEW can have an XML payload attached to them. The data in this XML can be used to make routing decisions. The Rule system built into KEW can leverage this XML for Rule evaluation using Xpath. We’ll use “Campus Code” for our example: – BL

73. Campus Code Routing Example For the sake of example, we’ll use 2 IU campus codes: –BL –IN Open sample-thin-client-3.xml Ingest sample-thin-client-3.xml Route a document -> it goes into Exception Routing because there are no rules!

74. Creating Rules for Campus Code 2 Workgroups need to be created, one for IN and one for BL –Ingest sample-thin-client-4.xml Navigate to the following URL: http://localhost:8082/rice-0.9.2-standalone/en/RuleQuickLinks.do We’ll create 2 rules, one for each campus, using the STC.BL and STC.IN groups

75. Searchable Attributes Searchable Attributes can be used to customize Document Search We’ll set up Searchable Attributes for Campus Code so we can search by it Open sample-thin-client-5.xml Ingest sample-thin-client-5.xml Route a document and then search by it’s Campus Code

76. “Role-based” Routing Sometimes it’s not convenient to use Rules because routing data is already available elsewhere or needs to be resolved dynamically In these cases, use “Role” Attributes Open InitiatorRoleAttribute.java from the “rice” project Let’s set up our document to send an Acknowledge request to initiator after it’s been fully approved

77. “Role-based” Routing – Acknowledge to Initiator Open sample-thin-client-6.xml Ingest sample-thin-client-6.xml Route document, approve at campus Now we have an acknowledgment to the Initiator! Role attributes can execute arbitrary code: –Read data from another database –Make a service call

78. Post Processors A Post Processor will receive events about node transitions and status changes Associated with a Document Type Often used to “Finalize” the business transaction represented by the workflow process Open STCPostProcessor.java But wait! How can the server execute this code? We need to create a plug-in.

79. Plug-ins A plug-in is a packaged set of code that can be deployed into the standalone server Plug-in layout: –META-INF/workflow.xml –lib –Classes Let’s build the plug-in! https://test.kuali.org/confluence/x/B4CwAg

80. Testing the Post Processor Once the plug-in is deployed our Post Processor can be used by the server We need to update our Document Type Open sample-thin-client-7.xml Ingest sample-thin-client-7.xml Now when we route and approve our document, it should go into exception routing if Campus Code is “IN”

81. More on Plug-ins For more information on plug-ins, see the “Workflow Plugin Guide” https://test.kuali.org/confluence/x/rW8 We will look at plug-ins a bit more when we discuss institutional customization

82. Parallel Routing So far we’ve only seen sequential route paths It’s also possible to use splitting and parallel branches Let’s split on campus code Open CampusSplitNode.java A SplitNode tells the KEW engine which branches of a route path should be executed

83. Parallel Routing, cont. Open sample-thin-client-8.xml Ingest sample-thin-client-8.xml Now the document will choose one branch or the other (or both!) depending on the campus code(s) specified.

84. Embedded KEW Client Integration

85. Creating an Embedded Client An Embedded KEW client executes the workflow engine locally but uses the standalone server’s database for storing and accessing documents Still uses WorkflowDocument and WorkflowInfo apis similar to thin client (unless KNS is used) JTA is used to provide cross-datasource transactions –Atomikos vs. JOTM/XAPool All KEW-related GUI screens (i.e. Document Search, Action List, Rules, etc.) are accessed from the standalone server A plug-in is no longer required for routing components (Post Processors, Split nodes, etc.) since the engine executes locally

86. Embedded Client Database Open embedded_db_bootstrap.sql The client application’s database needs to have tables related to KSB messaging –Each client needs it’s own message queue –…but there is only one Service Registry If the client is also using the KNS, it needs to have those tables as well The “riceembed” database has been pre- created for us using embedded_db_bootstrap.sql

87. Embedded Client Configuration Open sample-embedded-client-config.xml Open SpringBeans.xml in sample- embedded-client project Open sample-embedded-client-1.xml Launch the Sample Embedded Client Ingest sample-embedded-client-1.xml Notice how we don’t require a plug-in to be deployed to the server in order for the Campus Split Node to be executed

88. Institutional Customization

89. Customizing Kuali Rice at your Institution There are many ways to customize your Standalone Rice installation, including but not limited to: –Integration with institution’s identity services –Integration with institution’s authentication mechanisms (i.e. CAS) –Development and deployment of shared routing components

90. Customizing Kuali Rice at your Institution, cont. One way to customize Rice standalone is to use an Institutional Plug-in This plug-in can be used to override services using a custom Resource Loader implementation Let’s look at an example which would allow for using something like CAS for authentication

91. Custom Web Authentication Service We will be looking at the sample- institutional-plugin project Let’s implement basic HTTP auth Open HTTPAccessAuthenticationFilter Open sample-ip-config.xml and copy configuration into rice-config.xml In rice-config.xml find the “Dummy Login Filter” and comment it out.

92. Custom Web Authentication Service, cont. Open HTTPAccessWebAuthenticationService Open CustomOverrideResourceLoader Open SpringBeans.xml Open workflow.xml Build and deploy the plugin Start web application When we attempt to access standalone Rice we now see a basic HTTP authenticaton prompt

93. More Customizations There are other services which can be overridden using an Institutional Plugin See Workflow Plugin Guide in the Rice documentation for more details Other ways to customize include: –Custom Spring file (configure a value for kew.bootstrap.spring.file) –Crack open WAR and make changes there –Build WAR from custom source

94. eDoc Lite

95. eDoc Lite Overview Sometimes you need integration to a big client app, with complicated and dynamic routing. Sometimes you need simple 1-2 page documents, with simple routing. The latter is where eDoc Lite comes in. eDoc Lite is a simple, form-based system that runs entirely within workflow, and can be created with no java, just XML.

96. eDoc Lite – Details Simple form creation and presentation –Using XML against a Schema for form fields layout –Using your own custom XSLT for presentation Simple validation rules –Regular Expression –Validate Against List –Custom Validators –Required/Not-Required –JavaScript Validation

97. Building Blocks of an eDoc Lite Every eDoc Lite consists of 4 pieces: –Field Definitions – defines what fields the EDL has, what type, validations, etc. Similar to a Data Dictionary definition in KNS –Stylesheet – an XSLT stylesheet that renders the EDL for the user –Document Type – defines the workflow process for the EDL –EDL Association – associates each of the 3 pieces above to form an eDoc Lite

98. eDoc Lite Architecture

99. Example – University Graduate School - Course Remonstrance For this exercise we will look at a very feature-rich real world eDoc Lite form University Graduate School Course Remonstrance Process As courses are created or changed in the Graduate School, the class bulletin needs to be updated All Graduate Courses additions/changes at IU are approved through this process

100. UGS Routing Process Department Department-Review School School-Review SESPreScreen UGS1 PreRemonstrance Remonstrance UGS2 DeanOfFaculty SES DepartmentFYI SchoolFYI

101. UGS Setup First we need to setup EDL, ingest the following from the rice project: –edlstyle.xml –widgets.xml edlstyle.xml is the default style for eDoc Lite documents (the UGS documents have their own style so we won’t be using this) widgets.xml is an XSLT library that is used for rending input tags for the various fields on a document

102. Ingest UGS Setup The following files in the sample-edoclite folder need to be ingested in this order: –UGS-workgroups.xml –UGS-attributes.xml –UGS-templates.xml –UGS-doctypes.xml –UGS-rules.xml –UGS-course-change-request.xml –UGS-new-course-request.xml

103. New Course Request Let’s create a New Course Request and Route it Notice the validation that is being performed Notice as the request moves through routing that certain fields are editable and other are not

104. Examining the EDL Definition and Stylesheet Open UGS-new-course-request.xml Examine section

105. Handling EDL Data Since EDL uses KEW for it’s routing. You can implement Post Processors to write your EDL data to a database. There is one already available which can be used out of the box to write to: –EN_EDL_DMP_T –EN_EDL_FIELD_DMP_T This data can then be reported on in DSS environment or extracted via some other process

106. Questions? There is a lot more to learn about Kuali Rice You can use the content of this seminar as a starting point http://rice.kuali.org kuali-rice@googlegroups.com Thank you for coming!