C16: Workflow Rules

1
C16 Workflow Rules

• Nick Stefanidakis, ARCHIBUS, Inc.
• 2008 International ARCHIBUS Users Conference
• Wednesday, 16 April, 2008

2
Topics

• Web Central System Integrators Learning Path
• Roles
• Skills
• Techniques
• Creating Command Control Web Views
• Introducing Panels
• The Mini-Console
• Edit Forms
• Multiple Frame Form Patterns and Tabbed Views
• Using Restriction Consoles
• Enhancing Views with JavaScript
• Creating and Working with Workflow Rules

3
System Administration Roles

• Application Administrator
• Installation (Configuration, Projects, Logging)
• A/FM Security
• Database Administrator
• SQL-level Security
• Domain Administrator (FIM)
• A/FM personalization (forms, reports, processes)
• Review Activity Concepts in Learning Path doc
• Database Manager
• Customize SQL schema using A/FM data-dictionary

4
System Integrator Role

• System Integrator Capabilities
• Create custom Web Central forms/reports
• Add Actions or calculated fields
• Create Tabbed/Wizard forms
• Interact with Workflow Rules
• Use inline .css to customize formatting
• Use JavaScript to enhance functionality
• Skills required
• SQL, XML, JavaScript
• Simple .css (optional)

5
Business Logic Integrator Role

• Business Logic Integrator
• Write new Workflow Rule (event) handlers
• Create Unit Tests
• Invoke handlers using XML or JavaScript
• Required Skills
• SQL
• Simple Java (as a scripting language)
• Understanding of the build environment

6
Software Engineer Role

• Embed advanced controls using JavaScript and Java
• Create Ajax-enabled controls
• Timeline control (Room Reservations)
• Custom/3rd party controls/charts
• Others
• Beyond the scope of this session!

7
View Handling
JAVAWeb Server
axvw
XML Request
XML Response
Data- base
AJAX
XSL Style- sheet
XSL Transform
Web Client
HTML
JS
css
8
What is AJAX?

• AJAX isn't a technology, or a language, and
  there's no recipe to implement it it's just a
  combination of various components to achieve
  something you otherwise couldn't asynchronous
  http requests
• AJAX is short for Asynchronous JavaScript and
  XML. It uses the JavaScript XMLHttpRequest
  function to create a tunnel from the client's
  browser to the server and transmit information
  back and forth without having to refresh the
  page. The data travels in XML format because it
  transmits complex data types over clear text.
• Coldfusion Developers Journal

9
Working with Workflow Rules
10
System Integrator vs. Business Logic Integrator

• Workflow Roles For larger projects, project
  teams often divide the responsibilities
• the system integrator takes care of the forms and
  presentation layer and invoking the business
  rules
• the business logic integrator defines the
  workflow rules and any new event handlers that
  must be scripted
• You may be both!

11
What are Workflow Rules?

• Complex Business functions require database
  manipulation using JAVA event handlers
• Instead of calling event handlers directly, a
  workflow rule pointer is created inside the
  database.
• Since workflow rules include a security group
  field, users can be restricted from implementing
  event handlers they are not authorized to use
• System Integrators only need to know the rule
  name
• Schedule rules can also be configured to run at
  specified intervals, without users clicking a
  button

12
3 Ways to Call your WF Rule from an AXVW

• ltafmActiongt - Original Style (works with all
  views)
• ltcommandgt - CC style (must have a panel section)

ltafmAction type"messageRule"
eventName"AbSolutionsWorkflow-helpDeskPlanRequest
responseType"ab-ex-helpdesk-request-step2
.axvw"gt lttitle translatable"false"gtSubmitlt/
titlegt lt/afmActiongt
ltafmAction id"approve"gt lttitle
translatable"true"gtApprovelt/titlegt ltcommand
type"workflowRule"
ruleId"AbSolutionsViewExamples-approveProject"/gt
lt/afmActiongt
ltfield controlType"button"gt lttitle
translatable"true"gtApprovelt/titlegt ltcommand
type"workflowRule"
ruleId"AbSolutionsViewExamples-approveProject"/gt
lt/fieldgt
13
Define Workflow Rules

• Define Rule Name
• Specify Java Class and Method to call

14
A Word on WFR ltInputsgt

• Many of the new Command and Control Workflow Rule
  invocations do not require inputs to be supplied
  with the rule definition.
• By default, the new commands will pass the form
  values to the rule without specifying.
• Forms will pass all field values
• Reports will pass the primary key(s) for the
  selected record(s)

15
Business Logic Integrator Skills

• Using Java, youll
• Learn how to compile small Java extensions to Web
  Central
• Know how to call and define Java functions,
  extend an existing Java class, access predefined
  class methods and properties.
• Work with Java data types, conditional
  statements, and looping statements.
• You do not need to know how to
• Code a large Java program.
• Use object-oriented design techniques.
• Use the J2EE libraries, write servlets, interface
  with EJBs.

16
Workflow Rule Examples

• Invoking a Rule from a Panel Button (source)
• Edit axvw to call correct workflow rule!
• Invoking Rules from Per-Row Buttons (source)
• Invoking Rules on Multiply Selected Rows (source)

lt!-- call to WFR to invoke Hello World rule
--gt ltcommand type"workflowRule"
ruleId"AbSolutionsMyAdn-helloWorld"/gt
17
Enabling SQL Workflow Rule Logging

• Logging SQL Statements
• Aside from seeing when the query is invoked, the
  SQL logging shows the query in the final form
  with all SQL dialect considerations evaluated and
  all macros expanded.
• Logging Workflow Rule Invocations
• Logging View-Analysis Query Operations

18
Web Central Help and Java API Reference

• Event Handler Interface
• Web Central expects that each event handler that
  is called from a workflow rule will implement the
  EventHandler interface.
• Essentially, this amounts to implementing at
  least a single handle() method that Web Central
  knows to call.

19
When to Use Custom Workflow

• Customized business workflow requiring complex
  decision logic
• Complex reporting requiring multiple custom
  queries and invoked via AJAX
• Use results of a SQL query to execute another SQL
  query(ies)

20
Components of a Workflow Rule

• Workflow Rule
• A database record describing
• Function Approve Project
• Parameters Project ID
• Security Who may execute, e.g. Project
  Approvers
• Event Handler
• A compiled Java class file defining Business
  logic
• Note Each Workflow Rule must call an Event
  Handler that implements the rule

21
Custom Workflow Rule Development Process

• Create event handler Java class
• Compile event handler Java class into JAR file
• Create workflow rule definition in an XML file
• Import the workflow rule XML definition into the
  database
• Write event handler unit test and verify that it
  works
• Test the workflow rule from Web Central UI

22
ADN Product/Activity Structure

• Workflow rules and event handlers are a part of
  ADN product/activity structure

23
Working with Web Centrals API

• Web Central API provides over 100 methods
• More than double in size from 16.2
• Functionality including
• Create/retrieve/update/delete database records
• Format and localize data values
• Invoke other workflow rules
• Render views and generate reports
• Send email notifications

24
Moving Event Handlers to Production

• Event handlers are compressed to JAR format
• Product and Activity name are used as a part of
  the JAR file name

25
Rules for Handling Exceptions

• Stop Dont do it!
• All exceptions thrown from event handlers are
  handled by Web Central
• The database transaction is rolled back
• An error message is displayed and logged to
  archibus.log file

26
Rules for Handling Exceptions

• You may handle exceptions if
• You use custom transaction management, or
• To provide custom error message to the user

27
WebCentral as Development platform

• Built in Development Platform
• Activitys root directories contain build scripts
• For example ..\adn-products\my-product\my-activit
  y
• compileJar.bat Compiles Java classes, creates
  JAR file and copies it to WEB-INF/lib
• importWorkflowRules.bat Imports workflow rules
  from an XML file into database
• exportWorkflowRules.bat Exports workflow rules
  from the database into an XML file
• testEventHandler.bat Executes an event handlers
  unit test and generates a report

28
Multiple methods in Event Handler

• Event handler class can have many methods
• public class HelpDeskHandler
• extends EventHandlerBase
• public void approve(EventHandlerContext
  context)
• // your code here
• public void reject(EventHandlerContext
  context)
• // your code here
• This event handler Java class implements two
  different workflow rules

29
Working with Input Parameters

• All input parameters are passed to the event
  handler via EventHandlerContext object
• public void handle(EventHandlerContext context)
• Double cost_estimated (Double)
• context.getParameter("cost_estimated")
• Web Central converts HTTP request string
  parameters into Java objects of a correct type
  numeric, date, time
• String parameters are literalized to protect from
  SQL injection attack
• If parameter is not supplied, the exception is
  thrown

30
Working with Input Parameter Groups

• Use input parameter groups to handle all values
  submitted from the form regardless of their
  number or names
• Map fieldValues new HashMap(
• context.getParameters("fields"))
• fieldValues.put("project.status", "Approved")
• executeDbSave(
• context, "project", stripPrefix(fieldValues))
  

31
Returning Results from Event Handlers

• Use EventHandlerContext to add any number of
  response parameters
• String message localizeString(context,
  "Hello!")
• context.addResponseParameter("message", message)
• All response parameters are added to the
  response-for-XSL document
• String parameters as attributes of actionIn XML
  element
• XML parameters as children of actionIn XML
  element
• Access the workflow rule response parameters in
  custom view XSL
• ltxslvariable name"message" select"//actionIn/re
  sult/_at_message"/gt

32
Tools for Writing Your Own Handlers

• Folder structure
• Command Utilities
• The Eclipse IDE (WebCentralEclipseGuide.doc)
• Unit Tests
• JS Eclipse
• XML Buddy
• Firefox
• FireBug

33
Putting it all Together

• Helpdesk Request Example
• afm_activity_params table

34
Questions?