Open Application Architecture Platform Administration Guide

Transcription

1 Peregrine Open Application Architecture Platform Administration Guide Version For Windows, Solaris, and Linux PART NO: OAA ENG

2 Copyright 2002 Peregrine Systems, Inc. or its subsidiaries. All rights reserved. Information contained in this document is proprietary to Peregrine Systems, Incorporated, and may be used or disclosed only with written permission from Peregrine Systems, Inc. This book, or any part thereof, may not be reproduced without the prior written permission of Peregrine Systems, Inc. This document refers to numerous products by their trade names. In most, if not all, cases these designations are claimed as Trademarks or Registered Trademarks by their respective companies. Peregrine Systems, AssetCenter, and ServiceCenter are registered trademarks of Peregrine Systems, Inc. or its subsidiaries. This product includes software developed by the Apache Software Foundation ( This product also contains software developed by the following companies or individuals: Sun Microsystems, Inc., Jean-Marc Lugrin, Netscape Communications Corporation, and Original Reusable Objects, Inc. This document and the related software described in this manual are supplied under license or nondisclosure agreement and may be used or copied only in accordance with the terms of the agreement. The information in this document is subject to change without notice and does not represent a commitment on the part of Peregrine Systems, Inc. Contact Peregrine Systems, Inc., Customer Support to verify the date of the latest version of this document. The names of companies and individuals used in the sample database and in examples in the manuals are fictitious and are intended to illustrate the use of the software. Any resemblance to actual companies or individuals, whether past or present, is purely coincidental. If you have comments or suggestions about this documentation, please send to support-sd@peregrine.com This edition applies to version of the licensed program. Peregrine Systems, Inc. Worldwide Corporate Campus and Executive Briefing Center 3611 Valley Centre Drive San Diego, CA Tel or Fax

3 Contents Introducing the OAA Platform About this Guide Conventions Used in this Guide Chapter 1 Architecture Overview OAA Platform Architecture Archway Internal Architecture Archway Requests The Document Manager Chapter 2 Configuring the Application Servers JRun Configuring JRun Additional Steps for Configuring JRun on Solaris or Linux WebSphere or WebLogic 6.1 SP1 or SP Updating the scriptpollers.ini Files Configuring for Applications Using OAA Persistence Defining Run-time Parameters Verifying proper application server configuration Chapter 3 Load Balancing Your System Server Processing Considerations Multiple Application Server Instances.. 41 Creating Multiple Instances of Tomcat Editing the workers.properties File Contents 3

4 OAA Platform Editing the uriworkermap.properties File (IIS only) Editing the mod_jk.conf-auto File (Apache only) Editing the httpd.conf File (Apache only) Editing the wrapper.properties Files Editing the server.xml Files Installing Additional Tomcat Instances Testing the Load Balancing Chapter 4 Adapters SCAdapter Parameters Troubleshooting the ServiceCenter Database Connection ACAdapter Parameters ACAdapter Error Codes Troubleshooting the AssetCenter Database Connection JDBCAdapter ARAdapter BizDocAdapter Parameters MailAdapter Troubleshooting the MailAdapter Connection Verifying Adapter Connections Chapter 5 Security User Registration Authenticating Users Default Security Configuration Custom JAAS Configuration JAAS LoginModule Control Flags JAAS Configuration Options Example: Defining an LDAP custom configuration Standard Sun Microsystems JAAS Configuration Command line options Overriding the Login Script Defining User Rights Contents

5 Administration Guide HTTP Authentication Windows NT Challenge/Response Setting up Windows NT Challenge/Response Testing the Settings Chapter 6 Tailoring Peregrine Portal Themes Deploying the Classic Theme Variations Locating the Files Preparing for Customization Changing the Header Graphic Modifying the Style Sheets Editing the CSS Files Changing the Layers Changing the Framesets Chapter 7 Using OAA Workflow Defining Workflow Templates Creating a Workflow Template Creating a New Workflow Template from Another Template Modifying a Workflow Template Deleting a Workflow Template Creating a Component Template Using the Worklist Accessing the Worklist Completing Work Items Reassigning a Work Item Viewing History Viewing Status Delegating Your Worklist to Another User Using Workflow Administration Accessing the Administration Function Monitoring Process Instances Updating a Process Instance Deleting a Process Instance Starting a New Process Instance Viewing Error Events Contents 5

6 OAA Platform Setting Up the Request List Uploading JavaScript Files Using the Request List Accessing My Requests Viewing Request Details Initiating a New Request Viewing Overdue Requests Glossary OAA Platform Workflow Index Contents

7 Introducing the OAA Platform Peregrine Open Application Architecture (OAA) platform is a software platform that enables the hosting of a variety of Web applications over a corporate intranet. The platform is Java based, encompassing the latest in Java technology including Java servlets, JAAS login authentication, and JSP pages that enable Web pages to display data dynamically. OAA Platform is the underlying architecture for many Peregrine products. It provides a Web portal, Peregrine Portal, from which users can access their Web applications. The Peregrine Portal also provides access to the Admin module, from which all aspects of the OAA Platform are monitored and maintained. The base of OAA Platform includes: Archway a Java servlet that processes HTTP requests from a browser, sends the requests through an adapter to a back-end system, and returns XML data to be displayed in the browser. Core files the OAA Platform contains jsp and XML. The core consist mainly of low level Java utility classes used by the Portal Web applications built on the base OAA framework. Peregrine Portal includes a login page and provides access to your Peregrine Web applications and to the Admin module for configuration of your application. Introducing the OAA Platform 7

8 OAA Platform Skins and style sheets provide a choice for the appearance of the Web pages. The OAA Platform includes a number of optional components that are configured for use with Web applications as they are needed. These include: Adapters enables connection to the back-end system database. The adapter required by your Web application is deployed during the installation. OAA Persistence provides a general purpose database that is used by certain Peregrine Web applications. OAA Persistence provides data persistence to a database. OAA Workflow enables workflow capabilities used by some OAA Platform Web applications. Notification Services a centralized service for sending and receiving notifications through multiple communication devices and for tracking the status of these notifications. Separate documentation for Notification Services is provided with the Web applications that use this feature. 8 Introducing the OAA Platform

9 Administration Guide About this Guide This guide is a supplement to the guides provided with Peregrine Web applications. For specific information about the Web applications you have installed, refer to the guides provided with those applications. This guide is intended for use by an administrator or developer who will be installing or maintaining a system using the OAA Platform. This guide should be used in conjunction with several other manuals, which are: Operating guides, reference manuals, and other documentation for your PC hardware and operating software. The guides for the Peregrine Web applications you have installed. Documentation for the Peregrine back-end systems you are using. Documentation for the application server you are using. Conventions Used in this Guide Screen shots in this guide are included as examples only. Screens are shown using the Classic stylesheet. The following documentation conventions are used in this guide: Object Button, page name, menu option File name Example Click Next The login.jsp file About this Guide 9

10 OAA Platform Object Example Sample script or XML code var msgticket = new Message( "Problem" ); Menu path... msgticket.set( "_event", "epmc" ); The ellipsis (...) is used to indicate that portions of a script have been omitted because they are not needed for the current topic. Samples of code are not entire files, but they are representative of the information being discussed in a particular section. Select Start>Program Files. 10 Introducing the OAA Platform

11 1 CHAPTER Architecture Overview This chapter introduces the architecture behind OAA Platform. The platform offers a simple and extensible way of using Web applications to interface with Peregrine s existing systems or with other databases. OAA Platform Architecture OAA Platform applications and interfaces are implemented using basic building blocks that include: HTTP XML Commercial web servers A simple and widely supported protocol for sending client requests to a server. Variations such as HTTPS provide security as well. Extensible Markup Language. A documentation meta-language that allows you to format data, which can then be displayed through a Web browser. Unlike HTML, you create your own XML tags and define them any way you want. The services provided by the Archway architecture can be served from any commercial Web server, including IIS, Apache, Netscape Enterprise Server, or the Java Web Server. Architecture Overview 11

12 OAA Platform Application servers Common clients OAA Platform supplies Apache Tomcat for an application server with the installation. JRun, WebSphere, and WebLogic are also supported. Applications can be deployed via Web browsers (IE, Netscape), handheld devices (Palm Pilot), or mobile phones (through HDML). The application server processes data (JSP pages, XML, and so forth) that it receives from the database or client that is specifically related to the Peregrine Web applications. The Web server converts the data into a form (HTML) that can be displayed in a Web browser. 12 Chapter 1 Architecture Overview

13 Administration Guide The following diagram illustrates the architecture: HAND-HELD DEVICE (PalmPilot) WEB BROWSER CELL PHONE WEB SERVER (IIS, Apache, Netscape, etc.) APPLICATION SERVER (Tomcat, JRun, WebSphere, WebLogic, etc.) OAA Platform PEREGRINE PORTAL Provides access to Peregrine Web applications JSP ARCHWAY Java Servlet (XML, Queries, Events) Adapter EXTERNAL CONNECTION LIBRARIES Database, Mail Server, etc. The Archway component listens to HTTP requests from clients, routes the requests to an appropriate server, and returns data or documents. The requests supported by Archway can vary, but they fundamentally consist of queries, data updates, or system events. OAA Platform Architecture 13

14 OAA Platform For example, a client can contact Archway and ask to query a database for a list of problem tickets. Another client could contact Archway and supply it with a new purchase request to be entered into the database. All requests and responses are formatted using XML. For example, a problem ticket expressed in XML could appear as follows: <problem> <number> PM5670 </number> <contact> Joe Smith </contact> <description> My printer is out of paper </description> </problem> Clients that interact with Archway can do anything they need with the XML that is returned as a response. Very frequently, the client initiating the request is a user interface such as a Web browser. Such a client could easily display the XML documents returned by Archway. However, to be of better use, the XML documents are often displayed within a formatted HTML page. This is accomplished by using Java Server Pages (JSP). JSP provides a syntax for creating HTML pages that is pre-processed by the Web server before being sent to the browser. During this processing, XML data obtained from Archway is merged into the HTML page. Archway's architecture includes special support for automatically generating the HTML and JSP pages that make up a Web application. 14 Chapter 1 Architecture Overview

15 Administration Guide Archway Internal Architecture Archway is implemented as a Java servlet. The Java servlet is an application executed by a Web server that processes HTTP requests from a client through a Web browser and sends the request, by way of an adapter, to a database. It then retrieves the requested information from the database and returns it to the client. Archway requires both a Java environment and a Web server. Each request is interpreted to determine its destination. Archway is able to communicate with a variety of back-end systems, including the AssetCenter or ServiceCenter products from Peregrine. Requests can be handled in one of three ways: A request can be sent directly to an adapter that talks to a back-end server. For instance, a query request for opened tickets could be forwarded to an adapter capable of communicating with ServiceCenter. A request can be sent to a script interpreter hosted by Archway. This enables you to define your own application-specific services. Within a script, calls can be made back to Archway to access the back-end system with database operations and events. Finally, a request can be sent to a component known as a Document Manager. This component provides automated services for combining logical documents. Archway communicates with back-end systems with the help of specialized adapters that support a predefined set of interfaces for performing connections, database operations, events, and authentication. All adapters use DLLs to communicate with each application. Messages can be routed to a script interpreter hosted by Archway. The interpreter supports ECMAScript, a European standard based on the Core JavaScript language used by Netscape (JavaScript) and Microsoft Internet Explorer (JScript). Messages can be routed to the Document Manager component. This component reads special schema definitions that describe application documents for logical entities such as a purchase request, problem ticket, or product catalog. The script interpreter uses these schemas to automatically generate database operations that query, insert, or update such documents. Archway Internal Architecture 15

16 OAA Platform Archway Requests Each form displayed by a Web application using OAA Platform has a related JSP. A virtual directory tells the URL the location of the JSP pages the Web browser will use to display the Web application forms. Archway supports a variety of requests, all of which are based on two basic technologies: HTTP and XML. The HTTP protocol defines a simple way for clients to request data from a server. The requests are stateless and a client/server connection is maintained only during the duration of the request. All this brings several advantages to Archway, including the ability to support a large number of requests with the help of any of today's commercial Web servers. Another important advantage is that any system capable of making HTTP requests can contact Archway. This includes Web browsers, of course. But in addition, all modern programming environments support HTTP. This makes it very simple to write new adapters that communicate with Peregrine servers without the need of specialized APIs. An HTTP connection consists of: A client request A server response The messages exchanged normally have a number of header lines and some content lines. For example, consider the following two principal parts of a request: Query String Content The parameters sent with the URL for the HTTP connection. For example: This URL is made up of a server locator ( and a query string (hello&world). The data appended to the request. This data can be in any format, but for Archway, the data is always formatted as XML. Archway uses the query string of a request to determine what it has been asked to do. The following query string syntax is expected: archway?target.command&param=value&param=value& 16 Chapter 1 Architecture Overview

17 Administration Guide Let's consider each part of the request: Target Command Param=Value The name of the target object that should handle the request. Archway forwards requests to a system and returns the response. Thus, the target could be ServiceCenter, AssetCenter, or another database. The target may also be the name of a Script Object that contains customizable logic for handling the request. The action that the target object should take. By default, five basic actions are supported: query, update, insert, delete, and event. However, when the target is a Script Object, the action can be any function defined by the script. Parameter values included in the request. An arbitrary number of parameters can be passed along with the request. The encoding of these parameters is the same as that used by CGI (Common Gateway Interface). As with CGI, data sent by a browser is provided by fields embedded in an HTML form. This data is automatically formatted as a CGI request in a way that Archway understands. The following are sample URLs that query Archway with HTTP requests. These queries return data in XML documents. host name/servlet/archway?sc.query&_table= probsummary&priority.code=1 This sends a query request to ServiceCenter for all records in the probsummary table with a priority code of 1. host name/servlet/archway?ac.query&_table=amasset&_return= Brand;mPrice;Model&_count=2 This sends a query request to AssetCenter for the first two records in the amproduct table. Only the Brand, mprice, and Model fields are returned for each record. host name/servlet/archway?test.helloworld&greeting=hello This sends a helloworld request to a script object named test. Archway Internal Architecture 17

18 OAA Platform The screen below shows the XML results of a query for products from AssetCenter. The Document Manager Archway uses XML to exchange data and documents between clients and the supported back-end systems. Fundamentally, the XML data returned by Archway is obtained by executing queries against one or more systems. The queries can be executed by a direct URL request or indirectly within an ECMAScript. Simple queries are only capable of returning record sets of data. However, clients are more often interested in exchanging documents. A Document is a logical entity built up of several pieces of data that can come from various physical database sources. The Document Manager uses schemas to determine which XML elements to use and what data should be contained in the elements. The data used by the Document Manager depends on the back-end system being used. 18 Chapter 1 Architecture Overview

19 2 CHAPTER Configuring the Application Servers This chapter includes instructions for configuring the alternate application servers supported with OAA Platform. The procedures in this chapter will only configure OAA Platform on the application servers. Refer to your application server documentation for installation instructions. The following alternate application servers are supported: JRun 3.1 WebSphere or WebLogic 6.1 SP1 or SP2 Configuring the Application Servers 19

20 OAA Platform JRun 3.1 Configuring JRun The JRun application server requires a Java run-time environment. The OAA Platform installer includes the Java 2 SDK Standard Edition v1.3.1_01. However, you can also use JRE if you already have it installed. Before you configure JRun, do the following: If you do not have the appropriate Java run-time environment as described above, install the RTE provided with the Peregrine Web application installer. Refer to the documentation for your Peregrine Web application for instructions. Install JRun from the Allaire Web site. Return to the Peregrine installer and install OAA Platform and your Web application. The Zip files will be copied to your system, but will not be deployed. The following procedure will deploy the oaa package, portal.<version>.war, into the JRun Default Server. To deploy the ProductCoreAbbreviated package into JRun: 1 Open the JRun Management Console and log in. 20 Chapter 2 Configuring the Application Servers

21 Administration Guide 2 Select JRun Default Server>Web Applications. A screen opens from which you can edit, create, deploy, or remove application, as shown here. 3 Click the Deploy an Application link. 4 In the page that opens, fill out the fields as follows: JRun

22 OAA Platform Servlet War File or Directory: Browse to c:\oaa\packages\portal.<version>.war. Select this file, and then click Accept. JRun Server Name: Select JRun Default Server. Application Name: Type oaa. Application URL: Type /oaa. Application Deploy Directory: JRun generates this directory. Make a note of this path. You will need this information later in the procedure. 5 Click deploy. A message that oaa has been successfully deployed appears. The next step is to edit the class path. 6 Copy the following files into your Java RTE ext directory, for example: c:\jdk1.3.1\jre\lib\ext: All of the.jar files in the c:\oaa\external folder. The oaasecurityproxy.jar file, located in the...oaa\web-inf\lib directory of your JRun installation. Note: In this step, assume that you have installed the Java RTE supplied with the OAA Platform installer. If you are using an existing RTE, copy the.jar files into the equivalent directory location. 22 Chapter 2 Configuring the Application Servers

23 Administration Guide 7 From the Management Console activity menu, select JRun Default Server>Java Settings, and then click Classpath, as shown here. Click ClassPath. 8 In the edit window that opens, type the path to the directory to which you copied the JAR files in step 6 (for example: c:/jdk1.3.1/jre/lib/ext/jaas.jar). Type the path to the JAR files here. JRun

24 OAA Platform 9 Click update. 10 On the Java Settings page, click Java Arguments. Click Java Arguments. 11 In the edit window that opens, use the format example to enter an -Xmx value. This defines the maximum amount of heap memory allocated for your system. It is recommended that you set this value to at least 225 MB, but not more than 512 MB. Note: Make sure that the setting for maximum heap size is less than the free RAM available to the application server(s). Exceeding the amount of available RAM causes the JVM processes to swap to disk, reducing overall performance. A setting of 256 MB should be sufficient for most systems. Applications using Persistence may require a higher setting. 12 Log out of the JRun Management Console. 13 Stop the JRun Default Server from the Windows Services dialog box. 14 In the OAAdeploy.properties file, located at c:\oaa\packages, replace the path to the deployment directory with the path you noted in step Make sure that all slashes in the path are forward slashes and save the file. 16 Open a command prompt window and change directories to c:\oaa\packages. 24 Chapter 2 Configuring the Application Servers

25 Administration Guide This directory contains all of the Zip files that were installed onto your system. 17 To deploy all packages, type java -jar OAADeploy.jar, and then press ENTER. If you want to deploy only some of the packages, add the appropriate parameters to the command. Tip: On Windows, use the command java -jar OAAdeploy.jar -help for a list of the optional parameters available and instructions for using them. 18 Start the JRun Default Server. 19 Make sure that your Web server has an oaa virtual directory pointing to the Application Deploy Directory noted in step 4. The JRun configuration for Windows is now complete and you can log in to the Peregrine Portal. Important: If you have installed an application that uses OAA Persistence (in other words, uses the BizDocAdapter to connect to an Oracle database), go to Configuring for Applications Using OAA Persistence on page 38 for further configuration instructions. Continue to the next section for Solaris or Linux systems. JRun

26 OAA Platform Additional Steps for Configuring JRun on Solaris or Linux 1 Open the JRun Management Console and log in. 2 On the menu at the left, select JRun Default Server>Java Settings. 3 Click Library Path. 4 If you are using AssetCenter, add the AssetCenter bin directory and the Oracle lib directory to the path. On Solaris, also add /usr/bin and /usr/ucblib to the path. 5 Click update. The following page shows the updated path. The updated path appears here. 6 Click logout to exit the Management Console. 7 To stop and restart the JRun Default Server, type the following commands from the jrun/bin directory:./jrun -stop default &./jrun -start default & 26 Chapter 2 Configuring the Application Servers

27 Administration Guide WebSphere or Use the following procedures to set up WebSphere on Windows. To configure WebSphere: 1 Install your Peregrine Web application using the installation procedure in your Web application documentation. Note: If you already have a Java run-time environment installed on your system, skip this option on the installer CD browser. Skip the Tomcat installation option and go directly to the option to install your Web application. 2 Verify that the WebSphere Admin Server has been started. 3 Open the WebSphere Advanced Administrator s Console (Start > Programs > IBM WebSphere > Application Server > Administrator s Console). 4 On the menu at the left side of the console, right-click on Enterprise Applications and select Install Enterprise Application. 5 On the screen displayed, do the following: a Select Install stand-alone module. b In the Path field, browse to the path to the portal<version #>.war file. The default is C:\oaa\packages\portal<version #>.war. c In the Application Name field, type oaa. d In the Context Root field, type /oaa. WebSphere or

28 OAA Platform The following screen shows the completed form. 6 Click Next. 7 Click Next on the following dialog boxes. These screens will not be used. Mapping Users to Roles Mapping EJB RunAs Roles to Users Binding Enterprise Beans to JNDI Names Mapping EJB References to Enterprise Beans Mapping Resource References to Resources Specifying the Default Datasource Specifying Data Sources for Individual CMP Beans 28 Chapter 2 Configuring the Application Servers

29 Administration Guide 8 In the Selecting Virtual Hosts for Web Modules, verify that the default is selected, and then click Next. 9 In the Selecting Application Servers dialog box, verify that the default is selected, and then click Next. WebSphere or

30 OAA Platform 10 On the dialog box displayed, click Finish. 11 On the left menu, select Nodes > system name > Application Servers > name of application server (for example, Default Server). 12 In the screen displayed, click the JVM Settings tab. 13 Set the initial and maximum Java heap size. Recommended settings are as follows: a In the Initial Java heap size field, type 60. b In the Maximum Java heap size field, type the value you want for heap memory. This setting should be at least 225 MB, but not more than 512 MB. 30 Chapter 2 Configuring the Application Servers

31 Administration Guide Note: Make sure that the setting for maximum heap size is less than the free RAM available to the application server(s). Exceeding the amount of available RAM causes the JVM processes to swap to disk, reducing overall performance. A setting of 256 MB should be sufficient for most systems. Applications using Persistence may require a higher setting. 14 On the left menu, right-click on the system name node, which will have the same name as your computer. Select Regen Webserver Plugin. This updates the configuration file for WebSphere s connector to your Web server so that the Web server knows that files under /oaa are handled by WebSphere. 15 Minimize the Console window. 16 Restart your Web server. To complete the configuration of WebSphere: 1 Verify that the WebSphere Default Server is stopped. 2 Open the oaadeploy.properties file (located at c:\oaa\packages) in any text editor. Set the deployment directory to the path to the location of the oaa files inside your application server. The default path is: C:/WebSphere/AppServer/installedApps/oaa.ear/portal xx.war/ WebSphere or

32 OAA Platform 3 In the...\oaa\packages directory, delete portal xx.war.ear. 4 Open a command prompt window and do the following: a Change directories to the location of the packages directory. The default location is C:\oaa\packages. This directory contains all of the Zip files that were installed onto your system. b To deploy all packages, type java -jar OAADeploy.jar, and then press ENTER. If you want to deploy only some of the packages, add the appropriate parameters to the command. Tip: For a list of the optional parameters available and instructions for using them, use the command java -jar oaadeploy.jar -help. 5 Go to the...oaa\web-inf\lib folder and copy the following files to the C:\WebSphere\AppServer\java\jre\lib\ext directory: oaasecurityproxy.jar jaas.jar 6 Go to c:\oaa\external and copy the following files to the C:\WebSphere\AppServer\lib\ext directory: jai_codec.jar jai_core.jar mlibwrapper_jai.jar 7 Open the archway.xml file (located at C:\WebSphere\AppServer\installedApps\oaa.ear\portal xx.war\WEB- INF\default\) in any text editor, and do the following: a Remove the comment markers <!-- and --> from the three lines following after the <!-- Uncomment the following three lines for use in WebSphere--> comment: <SSLProvider>com.ibm.jsse.JSSEProvider</SSLProvider> <HTTPSHandlerPkg>com.ibm.net.ssl.internal. <CryptoProvider>com.ibm.crypto.provider.IBMJCE</CryptoProvider> This will change the SSL implementation to use IBM instead of Sun. b Save the file. 32 Chapter 2 Configuring the Application Servers

33 Administration Guide 8 If you are using WebSphere with IIS as your Web server, create an /oaa virtual directory in IIS to point to websphere/appserver/installedapps/oaa.ear/portal xx.war. 9 Open the WebSphere Advanced Administrative Console that you minimized earlier. In the menu on the left, right-click on the server name and select Start. Important: If you have installed an application that uses OAA Persistence (in other words, uses the BizDocAdapter to connect to an Oracle database), go to Configuring for Applications Using OAA Persistence on page 38 for further configuration instructions. To test the configuration: 1 After the server is started, open a Web browser and type the following in the Address field: name>:9080/oaa/admin.jsp where 9080 is the port number for WebSphere s built-in Web server. If you are using a different version of WebSphere, enter the correct port number for that version. If you are using IIS as your Web server, omit the port number. 2 Press ENTER. If everything is configured properly, the Administrator login page will be displayed. WebSphere or

34 OAA Platform WebLogic 6.1 SP1 or SP2 The following procedure configures WebLogic for OAA Platform on Windows, Solaris, or Linux. 1 Install OAA Platform and your Web application using the installation procedures in your Web application installation guide. Note: If you have already have a Java run-time environment installed on your system, skip this option on the installer CD browser. Skip the Tomcat installation option and go directly to the option to install Peregrine OAA. 2 In the WebLogic applications directory, create a directory called oaa. 3 Open the oaadeploy.properties file, located in the packages directory, and add the path to the WebLogic applications/oaa directory, for example: deploymentdir=c:/bea/wlserver6.1/config/mydomain/applications/oaa 4 Open a command prompt window and change directories to the location of the packages directory. The default location is C:\oaa\packages. This directory contains all of the Zip files that were installed onto your system. 5 To deploy all packages, type java -jar OAADeploy.jar, and then press ENTER. If you want to deploy only some of the packages, add the appropriate parameters to the command. Tip: For a list of the optional parameters available and instructions for using them, use the command java -jar oaadeploy.jar -help. 6 Verify that the following directory exists. If it does not exist, create it: C:\bea\jdk131\jre\lib\ext 7 Go to the OAA Platform lib folder (typically bea\wlserver6.1\config\<my domain>\applications\oaa\web-inf\lib), where <my domain> is the WebLogic domain of the system on which WebLogic is installed. Move the following file to the \bea\jdk131\jre\lib\ext folder: log4j jar oaasecurityproxy.jar 8 Go to the OAA Platform external folder (typically c:\oaa\external) and copy the following files to the \bea\jdk131\jre\lib\ext folder: 34 Chapter 2 Configuring the Application Servers

35 Administration Guide jaas.jar jai_codec.jar jai_core.jar jcel_2_1.jar jcert.jar jnet.jar jsse.jar local_policy.jar mlibwrapper_jai.jar sunjce_provider.jar US_export_policy.jar 9 Open the startweblogic.cmd file (located at c:\bea\wlserver6.1\config\mydomain\), in any text editor and do the following: a Scroll to the following section of the script: echo *************************************************** echo * To start WebLogic Server, use the password * echo * assigned to the system user. The system * echo * username and password must also be used to * echo * access the WebLogic Server console from a web * echo * browser. * echo Set WLS_PW equal to your system password for no password prompt server startup. set WLS_PW=password b In the last line, change the word password to your WebLogic system password. c Search for the -mx parameter setting in the file. Change this setting to at least 225 MB, but not more than 512 MB. Note: Make sure that the setting for maximum heap size is less than the free RAM available to the application server(s). Exceeding the amount of available RAM causes the JVM processes to swap to disk, reducing overall performance. A setting of 256 MB should be sufficient for most systems. Applications using Persistence may require a higher setting. d Save the file. 10 Create a virtual directory named oaa on your Web server and point it to the WebLogic applications oaa directory. WebLogic 6.1 SP1 or SP2 35

36 OAA Platform This will create a connection between the application and Web servers. 11 Restart the Web server. 12 Restart WebLogic as follows: The first time you start WebLogic after the installation, you will need to start it in development mode for it to find the Web applications that have been deployed. a Open the startweblogic (.cmd or.sh) file. b Locate the line that sets the STARTMODE variable. Set this variable to STARTMODE=false. c Start WebLogic. After you have done this at least once, you can change the setting to STARTMODE=true, which is the usual setting for a production system. Important: If you have installed an application that uses OAA Persistence (in other words, uses the BizDocAdapter to connect to an Oracle database), go to Configuring for Applications Using OAA Persistence on page 38 for further configuration instructions. To test the configuration: 1 After the server is started, open a Web browser and type the following in the Address field: name>:7001/oaa/admin.jsp If you are using IIS as your Web server, omit the port number. 2 Press ENTER. If everything is configured properly, the Administrator login page will be displayed. In the Admin module Control Panel, verify that the adapters are connected. Note: To connect to your database, you may need to modify the connection parameters using the Admin module Settings page. For instructions for using the Admin module, refer to your Web application guide. If you need to reinstall OAA Platform on WebLogic, first uninstall your current installation by deleting the oaa directory from WebLogic. Recopy the OAA Platform files, and then restart WebLogic and your Web server. 36 Chapter 2 Configuring the Application Servers

37 Administration Guide Updating the scriptpollers.ini Files If you will be using script pollers, you will need to update the script poller INI files with the name of the Java virtual machine (JVM) for the application server you are using. The scriptpollers.ini files are configured to use the default Java virtual machine (JVM). If you are using an alternate application server, you will need to tell Archway where to run the script pollers. Script poller files are located at <application server>\webapps\oaa\web-inf\apps in the common, notifications, and oaaworkflow folders. In the scriptpollers.ini file, add the ArchwayJVMName parameter, as shown in bold type in the example below, substituting jvm_name with the appropriate name for the application server you are using: WebSphere: oaa_bin WebLogic: oaa_wlserver60 (This will be different if WebLogic is not installed in the default installation directory.) Tomcat: oaa_bin <poller> <name>keepalivesc</name> <interval>600</interval> <parms> <ArchwayJVMName>jvm_name</ArchwayJVMName> </parms> </poller> Updating the scriptpollers.ini Files 37

38 OAA Platform Configuring for Applications Using OAA Persistence If your application uses OAA Persistence (BizDocAdapter) to connect to a database, use the following procedures to complete your installation. These procedures can be used for WebSphere, WebLogic, or JRun application servers. Defining Run-time Parameters There are several parameters that are specific to applications using OAA Persistence. Use the following procedure to define these parameters in the Admin module of your Web application. To define run-time parameters: 1 Verify that your application server has been started. 2 Browse to the administrator login page of your Web application: The Peregrine Portal administrator login page displays. 3 In the Name field, type Admin. No password is required. 4 Click Login as Administrator. 5 Click Settings in the Activity menu in the sidebar. 6 Enter the following parameters. Tab Field Name Value Common Enable script pollers Yes Event queue rome Web Application Alias for rome Portal DB Alias for rome Notification Adapter Alias for rome Note: The settings on each tab must be saved separately. 7 Click the Rome tab. 38 Chapter 2 Configuring the Application Servers

39 Administration Guide 8 Enter the following parameters for your database. Database Field Name Value IBM DB2 Database Type IBM DB2 Database User Name username Database User password Password Database URL jdbc:db2:<database name> Replace <database name> with name of your DB2 instance. Database Driver COM.ibm.db2.jdbc.app.DB2Driver Microsoft SQL Database Type Microsoft SQL Server Server Database User Name username Database User password Password Database URL jdbc:inetdae7:<host name>:<port> Replace <host name> with name of the host where the server resides. Replace <port> with the communications port number used by the database. Database Driver com.inet.tds.tdsdriver Oracle Database Type Oracle Database User Name username Database User password Password Database URL jdbc:oracle:oci8:@orcl_<database name> Replace <database name> with name of your Oracle instance. Database Driver oracle.jdbc.driver.oracledriver Oracle Thin Database Type Oracle Driver Database User Name username Database User Password password Configuring for Applications Using OAA Persistence 39

40 OAA Platform Database Field Name Value Database URL Database Driver name>:<port>:<database name> Replace <host name> with name of the host where the server resides. Replace <port> with the communications port number used by the database. Replace <database name> with name of your Oracle instance. oracle.jdbc.driver.oracledriver 9 After you enter settings for each tab, scroll to the bottom of the page, and then click Save. The Control Panel page displays. 10 Click Settings in the Activity menu in the sidebar to return to the tabs. 11 When the last tab has been completed and saved, click Reset Server from the Control Panel. A message is displayed at the top of the Control Panel when the server has been reset. Note: Reseting the server automatically runs the table creation process. Verifying proper application server configuration To complete the configuration of your application server, test to see if you can see the Peregrine OAA login page. To verify the installation: 1 Start your application server. 2 In a Web browser, enter the following URL: 3 Press ENTER. 4 When the user login page is displayed, type Admin in the User Name field. No password is required. 5 Click Login. Your application Home page is displayed. 40 Chapter 2 Configuring the Application Servers

41 3 CHAPTER Load Balancing Your System After completing your installation of OAA Platform and your Web application, decide whether or not you will need multiple application server instances. Server Processing Considerations Multiple Application Server Instances A server running a Web application such as Peregrine's Get-Services or Get-Resources consumes approximately 60 to 100 MB of memory per application server instance. Care should be taken not to set the maximum heap size of the JVM in excess of the free RAM available to the application server(s). Exceeding the amount of available RAM causes the JVM processes to swap to disk, reducing overall performance. Unlike other Adapters, the AssetCenter and ServiceCenter Adapters each create a single connection to the respective back end. Therefore, the memory consumed on the AssetCenter database server is the same as that consumed by a single client connection. The memory consumed on the ServiceCenter server is also the same as that of a single ServiceCenter client process. Load Balancing Your System 41

42 OAA Platform Note that memory usage does not increase significantly per session, because the architecture is based on the sharing of a set of resources and database connections among all sessions handled by the same application server instance. The small amount of memory consumed for session-specific information is released as the users log off or as their sessions expire. Note that server sessions do not expire unless the browser is closed or the user navigates to a different domain. Because ServiceCenter and AssetCenter adapters maintain a single connection to the back end, adding extra application server instances brings the added benefit of concurrent access to the back-end data store. The need for extra application server instances and therefore JVMs is directly related to three variables: The number of concurrent users. The processing power of the machine hosting the OAA Platform Web server. The number of processors on the machine. Each deployment may make different demands of the software and hardware, but, in any case, optimal back-end throughput for ServiceCenter and AssetCenter is achieved with the maximum number of application server instances that the server can handle without degraded performance due to lack of CPU headroom, file system swapping, and context switching. Cache synchronization with Symmetric MultiProcessing (SMP) servers can, in most cases, be ignored as a performance tuning factor except in the case of the extremely large-scale systems. To serve as a control guideline, low-end processors, such as a Pentium 450, should be capable of producing acceptable load handling for around 100 concurrent sessions on a single application server process. A dual Pentium 1000 with 2 gigabytes of RAM (a common data center configuration) should be capable of handling 400+ concurrent sessions using multiple application server instances. When using adapters capable of pooling, for example, the JDBCAdapter or BizDocAdapter, performance beyond the 400-concurrent-user benchmark can be achieved. 42 Chapter 3 Load Balancing Your System

43 Administration Guide Creating Multiple Instances of Tomcat Multiple instances of Tomcat are installed as services. Although this is not required, it makes the instances easier to manage and provides extra functionality, including restarting the service if it fails or if the machine on which the instances are installed needs to be restarted. Important: The following procedures use Tomcat with IIS as the Web server. This configuration is required if you are using Windows NT Challenge/Response. However, if you are not using Windows NT Challenge/Response, it is recommended that you use Tomcat with Apache as your Web server. The process for both configurations is similar and differences in configuring multiple instances of Tomcat with Apache are noted in the instructions. Any procedures that are not designated specifically for IIS or Apache should be completed for both. Creating Multiple Instances of Tomcat 43

44 OAA Platform The following diagram illustrates the architecture: Peregrine OAA Server IIS 5.0 IIS_redirect adapter 8009Tomcat NT service Ajp13 connector port:8009 Archway Servlet Web Client Web Client Load Balancer Worker w8009 port:8009 w8011 port:8011 w8013 port:8013 w8015 port: Tomcat NT service Ajp13 connector port:8011 Archway Servlet 8013Tomcat NT service Ajp13 connector port:8013 Archway Servlet Web Client Load Balancer Peregrine OAA App Files Peregrine OAA Server IIS 5.0 IIS_redirect adapter Config Files 8015Tomcat NT service Ajp13 connector port:8015 Archway Servlet 8009Tomcat NT service Ajp13 connector port:8009 Archway Servlet Back-End System (ServiceCenter, AssetCenter, etc.) Web Client Web Client Load Balancer Worker w8009 port:8009 w8011 port:8011 w8013 port:8013 w8015 port: Tomcat NT service Ajp13 connector port:8011 Archway Servlet 8013Tomcat NT service Ajp13 connector port:8013 Archway Servlet Peregrine OAA App Files Config Files 8015Tomcat NT service Ajp13 connector port:8015 Archway Servlet Creating multiple JVMs using Tomcat requires the following: Editing the workers.properties file to set the values (port number, host, and so on) for each Tomcat instance. Editing the uriworkermap.properties file to define a default worker name. (For Tomcat with Apache, you will be editing a copy of the mod_jk.conf-auto file and the Apache httpd.conf file.) Copying and modifying the wrapper.properties file to specify the parameters used by Windows to start the Tomcat JVM as a Windows service. There is a separate file for each Tomcat instance. Copying and modifying a server.xml file for each Tomcat instance. Installing multiple instances of Tomcat as a service using jk_nt_service.exe. This file can be found on the installation CD. Testing the configuration. 44 Chapter 3 Load Balancing Your System

45 Administration Guide The following procedures describe an example of an installation of four Tomcat instances on a system using IIS. Editing the workers.properties File For each server on which Tomcat instances are installed, there is only one workers.properties file, located in the config directory of your Tomcat installation. This file is shared by all Tomcat instances on the server. The workers.properties file specifies the worker threads that the Web server connector will create to communicate with the Tomcat instances. Each Tomcat instance must communicate on a different port. The host should be set to the name of the server running the instances or localhost if they are running on the same server as IIS. Cache size is the maximum number of user sessions that IIS should direct to the Tomcat instance at one time. Lbfactor is a number greater than or equal to 1 that IIS uses to load balance the workers. If all the workers are running on servers that have equal performance strengths, the lbfactor numbers should be equal. Workers with a lower lbfactor will be assigned fewer user sessions by the loadbalancer worker in IIS. The following example configures four load-balanced Tomcat instances, identified by port numbers 8009, 8011, 8013, and To edit the workers.properties file: 1 Open the workers.properties file (located in the config directory of your Tomcat installation) in any text editor. 2 Edit the following lines as shown. The paths for workers.tomcat_home and workers.java.home are the locations of your Tomcat installation and Java SDK installations. workers.tomcat_home=c:\jakarta-tomcat workers.java.home=c:\jdk1.3.1_01 ps=\ worker.list=loadbalancer, w8009, w8011, w8013, w8015 worker.loadbalancer.type=lb worker.loadbalancer.balanced_workers=w8009, w8011, w8013, w8015 Creating Multiple Instances of Tomcat 45

46 OAA Platform Note: You can define the worker names any way you want as long as you continue the same naming convention throughout the procedure. 3 Add the following lines for each Tomcat instance you have installed, incrementing the port number for the values shown in step 2: worker.w8009.port=8009 worker.w8009.host=localhost worker.w8009.type=ajp13 worker.w8009.cachesize=40 worker.w8009.lbfactor=10 4 Comment out the following lines. These default workers will not be used. worker.ajp12.port=8007 worker.ajp12.host=localhost worker.ajp12.type=ajp12 worker.ajp12.lbfactor=1 worker.ajp13.port=8009 worker.ajp13.host=localhost worker.ajp13.type=ajp13 worker.ajp13.lbfactor=1 worker.ajp13.cachesize=10 5 Save the file. Editing the uriworkermap.properties File (IIS only) Note: For systems using the Apache Web server, go to the next section to edit the mod_jk.conf-auto file. For each server on which Tomcat instances are installed, there is only one uriworkermap.properties file, located in the config directory of your Tomcat installation. This file is shared by all Tomcat instances on the server. To edit the uriworkermap.properties file: 1 Open the uriworkermap.properties file in any text editor. 2 Change the default worker to loadbalancer. 46 Chapter 3 Load Balancing Your System

47 Administration Guide Example: default.worker=loadbalancer 3 Change all oaa contexts to use loadbalancer instead of default worker ajp12. Make sure the oaa contexts do not include patterns for files that IIS is more suited to serve such as pictures. Usage: <file(s) or directory context pattern> = <worker name> Examples: /oaa/servlet/*=$(default.worker) /oaa/presentation/*.jsp=$(default.worker) 4 Save the file. Editing the mod_jk.conf-auto File (Apache only) If you are using Apache as your Web server, use the following procedure. This file is shared by all Tomcat instances on the server. It is important that you do this step after you have already installed your Web application, otherwise mounts, locations, and directories will not be included in the mod_jk.conf-auto file and you will have to manually add them. To edit the mod_jk.conf-auto file: 1 Make a copy of the mod_jk.conf-auto file and rename it to mod_jk.conf-local. Both of these files are located in the Tomcat conf directory. 2 Open the mod_jk.conf-local file in any text editor. 3 Change JkWorkersFile to point to the correct worker.properties file. Example: JkWorkersFile C:\Jakarta-tomcat-3.2.3\worker.properties 4 Change all JkMounts to use loadbalancer instead of default worker ajp12. Usage: JkMount<file(s) or directory> <worker name> Examples: JkMount/oaa/servlet/* loadbalancer JkMount/oaa/*.jsp loadbalancer 5 Save the file. Creating Multiple Instances of Tomcat 47

48 OAA Platform Editing the httpd.conf File (Apache only) The httpd.conf file must include mod_jk.conf-local. To edit the httpd.conf file: 1 Open the httpd.conf file in any text editor. 2 Add the following line: include "C:/<tomcat directory>/conf/mod_jk.conf-local" 3 Save the file. Editing the wrapper.properties Files You will need a separate wrapper.properties file for each instance of Tomcat that will be running concurrently. These files will specify the parameters used by Windows to start the Tomcat JVMs as a Windows service. To edit the wrapper.properties files: 1 Make a copy of the wrapper.properties file for each Tomcat instance and give each file a unique name. 2 Open one of the wrapper.properties files in any text editor. 3 Set wrapper.tomcat_home to point to the Tomcat home directory. Example: wrapper.tomcat_home=c:\jakarta-tomcat Set wrapper.java_home to point to the JDK home directory. Example: wrapper.java_home=c:\jdk1.3.1_01 5 Set wrapper.server_xml to point to the server.xml file for this instance of Tomcat. Example: wrapper.server_xml=$(wrapper.tomcat_home)\conf\8009server.xml 6 Add the -Xrs switch (required) and the -Xms and -Xmx switches (optional) to the wrapper.cmd_line execution statement. -Xrs required when using Tomcat as a Windows NT service. This switch tells the JVM not to exit when the current user logs off the system. 48 Chapter 3 Load Balancing Your System

49 Administration Guide -Xmx a memory switch. This switch tells the JVM the maximum amount of memory it is allowed to use. -Xms a memory switch. This switch gives the JVM a minimum amount of memory to allocate when starting. The -Xmx switch can be added to optimize the usage of RAM on the server by Tomcat. A good way to determine usage is to start the server and IIS, but not Tomcat. Observe how much memory is used at idle with no user load (or the normal load level experienced by the server when under normal pre-peregrine Web application usage). The following example outlines how to analyze and configure the -Xms and -Xmx switches: Example: The server has 2 Gb RAM hardware. At idle it uses about 180 MB. That leaves 1916 MB left for Tomcat usage. Subtracting 116 MB for just-in-case extra overhead leaves 1800 MB. Divided by 4 for the four Tomcat instances gives each Tomcat instance a maximum of 450 MB of RAM to use without worrying about the OS paging the memory. wrapper.cmd_line=$(wrapper.javabin) -Xrs -Xmx450m -Xms150m -server -classpath $(wrapper.class_path) $(wrapper.startup_class) -config $(wrapper.server_xml) -home $(wrapper.tomcat_home) 7 Save the file. 8 Repeat steps 2 through 7 for each copy of the wrapper.properties file you made. Editing the server.xml Files You will need a separate server.xml file for each Tomcat instance that will be run concurrently. The name of each file must match the name specified in the wrapper.properties file for this Tomcat instance. This file contains the information Tomcat needs to connect to the Web server as well as to find the OAA Platform Web application files. To edit the server.xml files: 1 Make a copy of the server.xml file for each Tomcat instance and give each file a unique name. 2 Open one of the copied files in any text editor. Creating Multiple Instances of Tomcat 49

50 OAA Platform 3 Set the log file locations and verbosity levels. The log file names in the path should be distinct for each Tomcat instance. Examples: <Logger name= tc_log path= logs/8009tc.log verbositylevel= INFORMATION /> <Logger name= servlet_log path= logs/8009servlet.log verbositylevel= INFORMATION /> <Logger name= JASPER_log path= logs/8009jasper.log verbositylevel= INFORMATION /> 4 Comment out the Tomcat HttpConnectionHandler connector. This is the port that Tomcat uses to communicate with a browser for direct HTTP requests. Since IIS will be serving the static data, Tomcat does not need to listen on this connector. It will also prevent a user from directly accessing Tomcat instances. Example: <Connector classname="org.apache.tomcat.service.pooltcpconnector"> <Parameter name="handler" value="org.apache.tomcat.service.http.httpconnectionhandler"/> <Parameter name="port" value="8080"/> </Connector> 5 Change the port number for the Tomcat Ajp13 listener. This is the port that Apache and Tomcat use to communicate when processing HTTP requests. This port number needs to be unique for each Tomcat instance on a server. Example: <Connector classname="org.apache.tomcat.service.pooltcpconnector"> <Parameter name="handler" value="org.apache.tomcat.service.connector.ajp13connectionhandler"/> <Parameter name="port" value="8009"/> <Parameter name= max_threads value= 100 /> <Parameter name= max_spare_threads value= 30 /> <Parameter name= min_spare_threads value= 10 /> </Connector> 6 Change the OAA context so that it is not reloadable. 50 Chapter 3 Load Balancing Your System

51 Administration Guide This prevents Tomcat from reloading the servlet without restarting the service. This improves performance and helps keep the JSP code that the Tomcat instances are serving in sync during an update. All other contexts should be set to reload=false. Example: <Context path= /oaa docbase= webapps/oaa crosscontext= false debug= 0 reloadable= false > </Context> 7 Save the file. 8 Repeat steps 2 through 7 for each copy of the server.xml file you made. Installing Additional Tomcat Instances After you have edited the Tomcat files, you are ready to install additional instances of Tomcat as Windows services using jk_nt_service.exe. To install additional Tomcat instances: 1 Open a DOS command prompt and change directories to your Tomcat bin directory. 2 Use the following syntax to create each Tomcat instance: jk_nt_service.exe -I <ServiceName><Path to wrapper file> Example: jk_nt_service.exe -I 8009Tomcat..\conf\8009wrapper.properties where 8009wrapper.properties is the name you gave each copy you made of the wrapper.properties file. 3 Repeat step 3 for each wrapper.properties file, changing the port number values for each Tomcat instance. Creating Multiple Instances of Tomcat 51

52 OAA Platform Testing the Load Balancing After you have created the additional Tomcat instances, test the system by starting the services and logging in to your Web application. To start the JVM services: 1 Open your Windows Control Panel>Services dialog box. 2 Scroll to the Tomcat entry, and then click Start. 3 Log in to your OAA Platform Web application. 52 Chapter 3 Load Balancing Your System

53 4 Adapters CHAPTER OAA Platform includes a number of adapters that are used to connect to databases or to a mail server. During the installation of your Web application, the adapters that are needed for the application were deployed. The following adapters are included with OAA Platform: ServiceCenter adapter (SCAdapter) provides a connection to the ServiceCenter database. AssetCenter adapter (ACAdapter) provides a connection to the AssetCenter database. Java Database Connectivity adapter (JDBCAdapter) enables a full database connection from OAA Platform and its Web applications to any database. Remedy ARS adapter (ARAdapter) enables a connection to the ARS Server. OAA Persistence adapter (BizDocAdapter) provides a connection to an Oracle database for the Web applications that use OAA Persistence. FacilityCenter adapter (FCAdapter) enables a connection between OAA Platform and FacilityCenter. Adapters 53

54 OAA Platform FleetAnywhere adapter (FAAdapter) enables a connection between OAA Platform and FleetAnywhere. Mail adapter (MailAdapter) enables a connection to an external mail server. During the installation process, tabs were created on the Admin module Settings page for the parameters you will need for your Web application. Additional tabs may be added after you have defined the target database for your system. Some of these adapters are reserved for future use. Information about the adapters currently being used is included in the following sections. Important: This chapter provides general information about the adapters. Refer to your Web application documentation to determine which adapters are used by the application you installed and how these adapters should be configured. SCAdapter The SCAdapter connects a Web application to the ServiceCenter database. This section includes information about the parameters that are specific to ServiceCenter, ServiceCenter event handling, and tips for troubleshooting the connection to ServiceCenter. Parameters Use the Settings page in the OAA Platform Admin module to change these parameters if needed. The parameters are located on the ServiceCenter tab. Admin Module Field Default Setting Description Host (none) The host name for your ServiceCenter installation. Port The port number for your ServiceCenter installation. The default port number for a full client is Chapter 4 Adapters

55 Administration Guide Admin Module Field Default Setting Description Log (none) The location of the sclog file. Admin user falcon An administrator login must be defined in order to connect to ServiceCenter. The default is falcon, the sample administrator login supplied with ServiceCenter. Admin password (none) By default, no admin password is required. Anonymous user falcon With this login, requests sent to Archway are processed without going through the OAA Platform user interface. Used by the script poller function. Anonymous password (none) By default, no anonymous password is required. Problem default category example Default problem category when inserting a new problem. Call default category example Default category when using Call Management. Default ticket schema Problem Sets up Call Management. Defines the type of ticket to insert in Get-Services (can be Incidents or Problem). Alias for sc(getit.service); Specifies the target configuration for which this is an alias. Adapter com.peregrine.oaa.adapter.sc. SCAdapter Full class path for the adapter associated with this target. SCAdapter 55

56 OAA Platform Troubleshooting the ServiceCenter Database Connection ACAdapter If you are having trouble making a connection between OAA Platform and the ServiceCenter database, verify the following: 1 Check the Control Panel page in the Admin module to confirm the database connectivity status. See Verifying Adapter Connections on page If sc is disconnected, verify that the ServiceCenter service is running (the ServiceCenter console has been started). 3 Verify that you have ServiceCenter full client connectivity by starting a client that is pointed to the port listed on the Settings page in the Admin module. The ACAdapter connects a Web application to the AssetCenter database. This section includes information about the parameters that are specific to the ACAdapter, ACAdapter error codes, and tips for troubleshooting the connection to AssetCenter. Parameters Use the Settings page in the OAA Platform Admin module to change these parameters if needed. The parameters are located on the AssetCenter tab. Most of the configuration parameters will already be set with appropriate default values for your installation. However, if you are using a version of AssetCenter other than the default version being used with your Web application, you will need to define the database name. Admin Module Field Default Setting Description Date format yyyy-mm-dd The default date format for data sent to AssetCenter. Database ACDemo351ENG The name of the AssetCenter database to which you are connecting. 56 Chapter 4 Adapters

57 Administration Guide Admin Module Field Default Setting Description Anonymous name Admin Anonymous user name used when an unknown user attempts to communicate with AssetCenter. Anonymous password (none) Anonymous user password. By default, no anonymous password is required. Admin name Admin Administration user used by OAA Platform when performing tasks such as user authentication and registration. Admin password (none) By default, no admin password is required. Default capability words (none) Semicolon-separated list of access rights that all users should have regardless of their profiles. Example: ac(getit.requester). Adapter com.peregrine.oaa.adapter.ac. ACAdapter Full class path for the adapter associated with this target. ACAdapter 57

58 OAA Platform ACAdapter Error Codes The following table lists error codes that may be returned by the ACAdapter. A description of the meaning of the code is included. Code Description Generic error Function called with wrong parameter Provided handle doesn t match an existing object No more data available in the result set The database server signaled an internal error Invalid value (incorrect type, out of range,...) Invalid record (mandatory field not given,...) No right to insert or update document Function is obsolete or not yet implemented Maximum number of connections reached (access denied). Troubleshooting the AssetCenter Database Connection If you are having trouble making a connection between your Web application and the AssetCenter database, verify the following: 1 Check the Control Panel page in the Admin module to confirm the database connectivity status. 2 If ac is disconnected, verify that the Database parameter defined on the AssetCenter tab of the Admin Settings page is the same as the database name displayed when you log in to AssetCenter. 58 Chapter 4 Adapters

59 Administration Guide JDBCAdapter ARAdapter The Java Database Connectivity (JDBC) adapter allows you to create a connection between your Peregrine Web application and any database. If the Web application you are using requires the JDBCAdapter, a tab for the adapter settings will be included on the Settings page of the Admin module. JDBCAdapter settings are also defined on the Rome tab. Refer to the documentation for your Web application for specific instructions for using the JDBCAdapter with your system. The ARAdapter enables a connection to the AR System server. In order for the Java RTE to locate the dynamically loaded shared libraries, the following variables must be set: Windows: Set the PATH environment variable to <webapp>/oaa/web-inf/lib Linux or Solaris: Set the LD_LIBRARY_PATH to <webapp>/oaa/web-inf/lib The following table describes the parameters that define the ARAdapter connection. These parameters are set on the AR Adapter tab of the Admin module Settings page. Admin Module Field Default Setting Description Admin user Demo Administration user name required when performing tasks such as user authentication and registration. Admin password (none) By default, no admin password is required. JDBCAdapter 59

60 OAA Platform Admin Module Field Default Setting Description Anonymous user Demo Anonymous user name used when an unknown user attempts to communicate with an ARAdapter application. Anonymous password (none) By default, no anonymous password is required. Problem default category example Default problem category used by Get-Services when inserting a new problem. Call default category example Default category when using Call Management. Default ticket schema Problem Sets up Call Management. Defines the type of ticket to insert in Get-Services (can be Incidents or Problem). Default capabilities getit.service Minimum capability word needed to access Get-Services. Adapter BizDocAdapter com.peregrine.oaa.adapter.ar. ARAdapter The BizDocAdapter provides a connection to an Oracle database and is used by Web applications that require OAA Persistence. Settings for this adapter are located on the Rome tab of the Admin module Settings page. OAA Persistence is an optional component of the OAA Platform. OAA Persistence provides: An Oracle database. Full class path for the adapter associated with this target. An Archway adapter, BizDocAdapter, to connect your application to the Oracle database and process data between them. Tblcreate a tool that reads a database schema and creates database tables. OAA Persistence also enables interaction with OAA Business Intelligence to provide reporting capabilities. 60 Chapter 4 Adapters

61 Administration Guide Parameters Use the Settings page in the OAA Platform Admin module to change these parameters if needed. The parameters are located on the Rome tab. Refer to the documentation for your Web application for specific instructions for using the BizDocAdapter with your system. Admin Module Field Default Setting Description (Web Application tab) Alias for (PortalDB tab) Alias for MailAdapter rome rome Specifies the target configuration for which this is an alias. Specifies the target configuration for which this is an alias. The MailAdapter is an implementation of JavaMail API 1.2 and supports the following mail protocols: POP3 for inbound mail IMAP for inbound mail SMTP for outbound mail The MailAdapter also supports MIME type attachments in outbound . The following table describes the parameters that define the MailAdapter connection. These parameters are set on the tab of the Admin module Settings page. Admin Module Field Default Setting Description Inbound mail host (none) The full name or IP address of the inbound mail server. Inbound mail protocol (none) The protocol used by the inbound mail server, which is either IMAP or POP3. Inbound mail user ID (none) The user ID used to access the inbound mail server. MailAdapter 61

62 OAA Platform Admin Module Field Default Setting Description Inbound mail password (none) The user password used to access the inbound mail server. Mail sender address (none) This address is used as the default sender address in outbound messages. Legal domains (none) A semicolon-separated list of mail domains with which the Peregrine Portal can correspond. Only users with an address in these domains are allowed to complete online self-registration in the Peregrine Portal. Anonymous user (none) Anonymous user name used in ServiceCenter when an unknown user attempts to communicate with the mail adapter. Anonymous password (none) Anonymous user password in ServiceCenter for the mail adapter. Outbound mail host (none) The full name or IP address of the outbound mail server. Outbound mail user ID (none) The user ID used to access the outbound mail server. Outbound mail password (none) The user password used to access the outbound mail server. Attached files path (none) The path to the directory containing all uploaded attachment files. Adapter com.peregrine.oaa.adapter.mail. MailAdapter Full class path for the adapter associated with this target. Troubleshooting the MailAdapter Connection You can check the status of the MailAdapter connection on the Control Panel. If the adapter shows as disconnected, check that the settings on the tab of the Settings page are correct. If you are still unable to connect, contact your system administrator for verification of the parameter values. 62 Chapter 4 Adapters

63 Administration Guide Verifying Adapter Connections The status of the connection to a database can be verified from the Control Panel in the Admin module. For more information on connectivity troubleshooting with each adapter, refer to the guides for the Web applications you have installed. Verifying Adapter Connections 63

64 OAA Platform 64 Chapter 4 Adapters

65 5 Security CHAPTER This chapter includes information about how security is handled by OAA Platform, including the following: User registration User authentication Installing and using Windows NT Challenge/Response OAA Platform operates transparently over Secure Sockets Layer (SSL) when the virtual directory of the Web server is configured to use SSL. No certificate-based authentication is used. Passwords are sent over the wire as plain text unless SSL is employed. Passwords are stored as plain text in a browser cookie if the user selects Enable automatic login. SSL uses the public-and-private key encryption system, which includes the use of a digital certificate. If your Web server has a certificate, then your URL would be something like Most browsers (Internet Explorer 4.0 or higher and Netscape 4.x) recognize this and know to send data encrypted when the site to which it is connecting is a secured site (https). Security 65

66 OAA Platform User Registration OAA Platform also supports Windows NT Challenge/Response authentication. When this form of authentication is used, passwords are not actually exchanged between the browser and Web server, and the authentication process is kept secure. However, Windows NT Challenge/Response is only supported by Internet Explorer browsers on Windows systems. Instructions for configuring Windows NT Challenge/Response begin on page 80. If a user has a login name already established in the back-end system you are using, the user does not need to register in the Web application. For example, in ServiceCenter the appropriate capability words would be defined in the user s Operator record. In AssetCenter, the appropriate user rights would be defined in the user s Profile. Similar access rights can be defined in whichever back-end system you are using. The user login will automatically be authenticated in the back-end system. However, if a user is attempting to log in for the first time without back end authentication, the user is prompted for certain default information as shown in the following screen. Note that the first four fields are required, as indicated by the arrows to the right of each field. 66 Chapter 5 Security

67 Administration Guide When the user clicks Register, the information is stored in the appropriate database. If you are using AssetCenter, OAA Platform will transform this data into a Profile record that will then be passed to your AssetCenter system. An amempldept record is created with the user-supplied data and a default Profile will be assigned, getit.default. If you are using ServiceCenter, an Operator record is created. A contact record is also created for the new user. Note: The adapter must be defined before the capability words will be recognized. For example, if no adapter is defined for Service Center, the ServiceCenter capability words will not be used. The documentation for the back-end system you are using includes instructions for establishing user rights and using capability words. The access right, getit.admin, can be defined for any user who will need administrative access. Other access rights, which are specific to the Web applications, are explained in the guides for the applications you have installed. Basic registration information and login scripts are stored in the.../oaa/apps/common/jscript/ directory. Login scripts are in the file named login.js. If you want to make changes to the registration process, such as changing the way a user s password is defined, you can change the scripts in this directory. User Registration 67

68 OAA Platform Authenticating Users You can configure the Peregrine OAA Platform to use one of four security authenitcation options: Use the default configuration to authenticate users against Peregrine adapters. See Default Security Configuration on page 68. Use a custom configuration to authenticate users against user-defined adapters such as LDAP or JDBC compliant databases. See Custom JAAS Configuration on page 69. Use a standard JAAS configuration to authenticate users against the Sun Microsystem s standard Java Authentication and Authorization Service (JAAS). See Standard Sun Microsystems JAAS Configuration on page 76. Override the standard OAA Platform login script and authenticate users without using JAAS. See Overriding the Login Script on page 77. Default Security Configuration The default configuration authenticates users against a set of pre-configured JAAS login modules. By default, one JAAS login module is configured for each registered Peregrine adapter. For example, if you are using both AssetCenter and ServiceCenter, then the OAA Platform will create login modules for both the ACAdapter and the SCAdapter. These login modules are only used to authenticate users. User access rights are derived from user profile records in the back-end systems (for example, ServiceCenter or AssetCenter). User access rights determine which modules the user can access and what tasks they can perform within those modules. For example, one user may be able to open tickets only, while another may have rights to approve tickets as well. For instructions on user access rights, refer to Defining User Rights on page 79 and consult your Web application documentation. You do not have to do any additional configuration to use the default security configuration. The OAA Platform will automatically generate login modules for each Peregrine adapter installed on the system. The default login module settings are: loginmodule=com.peregrine.oaa.security.oaaloginmodule 68 Chapter 5 Security

69 Administration Guide control flag=optional options=<none> Custom JAAS Configuration A custom JAAS configuration authenticates users against a set of JAAS LoginModules you define in a local.xml file. This file describes the settings to be used for each JAAS LoginModule. A local.xml file has the following format. <jaas_config> <jaasconfiguration>customconfig</jaasconfiguration> <CustomConfig>adapter1;adapter2</CustomConfig> <adapter1> <loginmodule>java class of login module</loginmodule> <controlflag>authentication behavior</controlflag> <options>semicolon separated list of options</options> </adapter1> <adapter2> <loginmodule>java class of login module</loginmodule> <controlflag>authentication behavior</controlflag> <options>semicolon separated list of options</options> </adapter2> </jaas_config> The following table describes how to use the XML tags and assign appropriate values. Use these XML tags <jaas_config> </jaas_config> <jaasconfiguration> </jaasconfiguration> To do this Define a custom JAAS configuration. All JAAS configuration settings must be between these two tags. Define the name of your custom JAAS LoginModule. The value of this tag determines the tag name to use for the next tag. For example, if you create a custom configuration with the value CustomConfig, then you must use the tags <CustomConfig> and </CustomConfig> to define the list of adapters used. Custom JAAS Configuration 69

70 OAA Platform Use these XML tags <CustomConfig> </CustomConfig> This is a user definable tag <adapter1> </adapter1> <adapter2> </adapter2> These are user definable tags <loginmodule> </loginmodule> <controlflag> </controlflag> <options> </options> To do this Define the list of all adapters that you want to use for authentication. Use semicolons between entries to sepecifiy muliple adapters. If the adapter name you list does not match a registered AdapterPool, then the OAA Platform assumes the name is a logical name to be defined in a separate adapter tag. The OAA Platform will attempt to authenticate users against each adapter you list. The values listed in this tag determine the tags names to use for each adapter. For example, if you create two adapters adapter1 and adapter2, then you must use the tags <Adapter1>, </Adapter1>, <Adapter2>, and </Adapter2> to define your adapters. Define the JAAS LoginModule settings for each adapter. Each adapter must have both <loginmodule> and <controlflag> tags defined for it. Define the fully qualified class name of the JAAS LoginModule. This is a required setting for each JAAS LoginModule you use. Define what information is necessary to authenicate a user. This is a required setting for each JAAS LoginModule you use. See JAAS LoginModule Control Flags on page 71 for a description of available options. Define the list of authentication options. Use semicolons between entries to sepecifiy muliple options. This is an optional setting for each JAAS LoginModule you use. See JAAS Configuration Options on page 72 for a description of available options. 70 Chapter 5 Security

71 JAAS LoginModule Control Flags Administration Guide The following table lists the possible settings for the <controlflag> tag. A JAAS LoginModule can have one of four behaviors: Control Flag REQUIRED REQUISITE SUFFICIENT OPTIONAL Authentication Behavior If the user cannot be authenticated against the adapter, the login will fail. Whether it succeeds or fails, authentication continues to the next LoginModule in the list. If the user cannot be authenticated against the adapter, the login will fail. If it succeeds, authentication continues to the next LoginModule in the list. Authentication can proceed even if this LoginModule fails. It it succeeds, authentication does not continue to the next LoginModule in the list. If it fails, authentication continues to the next LoginModule in the list. Authentication can proceed even if this LoginModule fails. Whether it succeeds or fails, authentication continues to the next LoginModule in the list. Note: ControlFlag settings are case insensitive. The overall authentication succeeds only if all Required and Requisite LoginModules succeed. If a Sufficient LoginModule is configured and succeeds, then only the Required and Requisite LoginModules prior to that Sufficient LoginModule need to have succeeded for the overall authentication to succeed. If no Required or Requisite LoginModules are configured for an application, then at least one Sufficient or Optional LoginModule must succeed. By default, the controlflag setting of all OAA Platform Web applications LoginModules is Optional. For most enterprises, this will be the desired configuration. Custom JAAS Configuration 71

72 OAA Platform The following table shows some sample scenarios and how the login process works. Module Name Status Scenario 1 Scenario 2 Scenario 3 LoginModule1 required pass pass fail LoginModule2 sufficient fail fail fail LoginModule3 requisite pass pass pass LoginModule4 optional pass fail fail Final Authentication pass pass fail In Scenario 1, authentication succeeds even though LoginModule2 fails. This is because the Required loginmodule takes precedence over the sufficient loginmodule. In Scenario 2, authentication succeeds because the loginmodules that failed are only Sufficient and Optional. Scenario 3 authentication fails because a loginmodule with a status of Required failed. JAAS Configuration Options The following tables list the possible settings for the <options> tag. Standard JAAS Options The following table lists the standard JAAS options available for all adapters. Option Use Description debug=true optional Instructs a LoginModule to output debugging information. The OAALoginModule logs debugging information to stdout and not to archway.log. tryfirstpass=true optional The first LoginModule in the list saves the password entered and this password is used by subsequent LoginModules. If authentication fails, the LoginModules prompt for a new password and repeats the authentication process. 72 Chapter 5 Security

73 Administration Guide Option Use Description usefirstpass=true optional The first LoginModule in the list saves the password entered and this password is used by subsequent LoginModules. If authentication fails, LoginModules do not prompt for a new password. storepass=true optional Stores the password for the user being authenticated. clearpass=true optional Clears the password for the user being authenticated. Peregrine JndiLoginModule Options The following table lists the options available to custom JAAS LoginModules using the Peregrine JndiLoginModule. Option Use Description user.provider.url required Use this option to provide the URL to the starting point in your directory service where you want to search for users. For example, ldap://server/dc=peregrine,dc=com Note: This option corresponds to the Java constant Context.PROVIDER_URL. security.principal optional Use this option to specify which directory service user you want to use to authenticate non-anonymous queries of your directory service. Use the DN of the directory service user. For example, uid=user,dc=peregrine,dc=com Tip: To prevent user passwords from being visible to users, you should only set this option if you are using a directory server such as IPlanet where user passwords are SHA hashed by default. Note: This option corresponds to the Java constant Context.SECURITY_PRINCIPAL. Custom JAAS Configuration 73

74 OAA Platform Option Use Description security.credentials optional Use this option to define the password for the security.principal user. This option should only be used in conjuction with the security.principal option. Important: If you are using a simple security authentication protocol then this password may be passed as plaintext. Tip: To safeguard this password, either enable SSL (set the security.protocol=ssl option) or use an security.authentication that protects passwords. Note: This option corresponds to the Java constant Context.SECURITY_CREDENTIALS. security.protocol optional Use this option to enable or disable an SSL connection between the JndiLoginModule and your directory server. This option has two possible values: simple (Default setting) ssl Note: This option corresponds to the Java constant Context.SECURITY_PROTOCOL security. authentication optional Use this option to enable or disable anonymous binding to your directory service. Typically, this option has one of two values: none (Default setting) simple Note: If you do not specify a value for security.principal then security.authentication defaults to a value of none. Likewise, if you set security.authentication to simple but security.credentials is omitted or has zero length, then security.authentication will reset to none. Note: This option corresponds to the Java constant Context.SECURITY_AUTHENTICATION. 74 Chapter 5 Security

75 Administration Guide Option Use Description user.search.scope optional Use this option to specify the number of levels to descend when searching for the user being authenticated by user.provider.url. This value must be an integer. The default value is 1. Note: This option corresponds to the Java constant SearchControls.ONELEVEL_SCOPE. group.provider.url optional Use this option to provide the URL to the starting point in your directory service where you want to search for groups. For example, ldap://server/dc=peregrine,dc=com Note: This option corresponds to the Java constant Context.PROVIDER_URL. group.search.scope optional Use this option to specify the number of levels to descend when searching for a group. This option should only be used with group.provider.url. This value must be an integer. The default value is 1. Note: This option corresponds to the Java constant SearchControls.ONELEVEL_SCOPE. group.search.object Class optional Use this option to specify the name of the LDAP group objectclass. Valid values are: groupofnames (Default value) groupofuniquenames. groupofurls Note: Either groupofnames or groupofuniquenames can be used to define static groups in LDAP, but they may not be used together. If you choose the groupofurls option, then you are configuring dynamic groups. No additional configuration settings are required to recognize dynamic groups. storeidentity=true optional Use this option to store a reference to the User being authenticated. clearidentity=true optional Use this option to clear a reference to the User being authenticated. Custom JAAS Configuration 75

76 OAA Platform Example: Defining an LDAP custom configuration The following XML code illustrates you could define a loginmodule to authenticate users against an LDAP directory service. <jaas_config> <jaasconfiguration>myconfig</jaasconfiguration> <myconfig>ldap</myconfig> <ldap> <loginmodule> com.sun.security.auth.module.jndiloginmodule </loginmodule> <controlflag>required</controlflag> <options> user.provider.url="ldap://server/dc=peregrine,dc=com"; group.provider.url="ldap://server/dc=peregrine,dc=com" </options> </ldap> </jaas_config> Standard Sun Microsystems JAAS Configuration The standard JAAS configuration authenticates users against the Sun Microsytems JAAS configuration loginmodule. To enable the standard JAAS configuration, you must edit the local.xml file and add the following lines: <jaas_config> <usestandardjaasconfiguration>true</usestandardjaasconfiguration> </jaas_config> If you choose to use the standard JAAS configuration, then you must also do one of the following two things: Specify the appropriate JAAS command line options when the container is started or Configure the java.security file in $JAVA_HOME/jre/lib/security for JAAS. 76 Chapter 5 Security

77 Command line options Administration Guide The command line properties required for use of the standard file-based configuration are as follows: java -classpath <list of jars> \ -Djava.security.manager \ -Djava.security.policy==java2.policy \ -Djava.security.auth.policy==jaas.policy \ -Djava.security.auth.login.config==jaas.config \ MyMainClass For <list of jars>, enter the list of jars used by your JAAS-enabled Java application. For MyMainClass, enter the fully qualified class name of the Java main program class. Overriding the Login Script As an alternative to writing a custom JAAS login module, you can override the login script function, login.init(), to obtain login credentials from another source. To override the login script: 1 Create a function that obtains the user s login name. For example: msg.set( loginuser, struser ); 2 Create a different login screen for the initial Web application page. This screen must use the user information you gathered from the script above. 3 Configure the external authentication service to return users to the file login.jsp if they are successfully authenticated. The login.jsp file then sets up the initial frame set, and calls the server script functions, login.init() and login.login(). Overriding the Login Script 77

78 OAA Platform The following diagram shows the process for authenticating a login within a Peregrine Web application using ServiceCenter as the back-end system. Access Web application Alternate login page (logindefault.asp) Alternate login page (loginmgr.asp) Alternate login (other login information) Regular login page (login.jsp) Is User previously Authenticated? (NT Challenge/Response, other authentication) No Bring up regular login page with any messages Yes Set the Operator in the User Space for ServiceCenter Authentication Yes Is the OPERATOR set? User Information No Perform adapter authentication No, Send back error message User authenticated? Yes Enter Web application 78 Chapter 5 Security

79 Administration Guide Defining User Rights HTTP Authentication Once a user has been authenticated, the modules to which the user has access are defined by the back-end system. For example, if you are using AssetCenter and a user does not have access rights to a particular table in AssetCenter, the user will not be able to access the corresponding module in the Web application. The same is true if you are using ServiceCenter for the back-end system. The user must have the appropriate capability words set in the Operator record in ServiceCenter in order to see the corresponding module in the web application. For specific information about defining user rights, refer to the documentation for the Web application you have installed. OAA Platform uses HTTP basic authentication. When you query the Archway servlet using a URL, you will be prompted for your user name and password. The default setting for this parameter is true. The setting can be changed in the archway.xml file, located at <tomcat installation>\webapps\oaa\web-inf\default. Warning: If you change the HTTP authentication setting to false, you will open up the URL query being used to any user on the system. If this protection is turned off, you will need to protect this URL by restricting access through your Web server. Defining User Rights 79

80 OAA Platform Windows NT Challenge/Response Windows NT Challenge/Response is one of the ways Windows NT facilitates the authentication of users on a Web server. The process consists of a secure handshake between the browser (IE) and the Web server (IIS). The handshake lets the Web server know exactly who the user is, based on how they logged in to their workstation. This allows the Web server to restrict access to files or applications based on who the user is. Applications running on the Web server can use this information to identify users without requiring them to log in. OAA Platform uses Windows NT Challenge/Response as follows: The user logs in to an NT workstation. The user starts an IE browser and navigates to the login.asp page. IE automatically sends user authentication information to IIS. The user s password is not transferred, but the Windows NT Challenge/Response handshake between IE and IIS is enough for the server to recognize the user. The Web application login automatically detects the user by using the Windows NT Challenge/Response/IIS server data. The user is logged in without requiring that a name and password be entered. During this process, Archway authenticates and impersonates the NT user with each of its adapters. The following circumstances must be handled during this process: The NT user is not yet registered with an Archway adapter. When this occurs, the web application asks the user to register and enter profile information. The application then lets the user log in and stores this information for future login attempts. The NT user name is already registered as an Administrator in the back-end system. When this occurs, the web application does not proceed with automatic login. The user is presented with another login screen and is asked to verify their password. This step is an added security measure to prevent a user from accidentally logging in with administrative rights. 80 Chapter 5 Security

81 Administration Guide Setting up Windows NT Challenge/Response The following procedure uses Windows NT as an example. If you are using Windows 2000, the overall procedure is the same. However, in Windows 2000, Challenge/Response is called Integrated Windows Authentication, and the IIS Management Console is called Internet Information Services. To configure Windows NT Challenge/Response: 1 Open the IIS Management Console (Start>Programs>Administrative Tools>Internet Services Manager). 2 Click on the oaa virtual directory. 3 Right-click on login.asp and select Properties. 4 Select the File Security tab. 5 Click Edit in the Anonymous Access and Authentication Control section. 6 Check Windows NT Challenge/Response. Make sure this is the only option checked. Click OK. 7 Click OK on the other windows displayed until you return to the Microsoft Management Console. Windows NT Challenge/Response 81

82 OAA Platform Updating the loginverify.asp File 1 Repeat the steps above for loginverify.asp. Follow steps 3 through 5 as they are written above except select loginverify.asp instead of login.asp. 2 In the Authentication Methods window, check the Allow Anonymous Access and Windows NT Challenge/Response options. Click OK. 3 Click OK on the other windows until you return to the Microsoft Management Console. 4 Close the Management Console. Setting Permissions for the Presentation Folder 1 Use Windows NT Explorer to navigate to the...oaa\presentation folder. 2 Right-click on presentation and select Properties. 3 On the Security tab, click Permissions. Note: If you do not see a Security tab, verify that your Web application is installed on an NTFS partition. 82 Chapter 5 Security

83 Administration Guide 4 Click Add to change the user groups that have permission to access the folder. Change the permission to a named authenticated group. For example, you could change permissions to all Authenticated Users. Testing the Settings 5 If the user group called Everyone has permissions, highlight the entry, and then click Remove so that only the group you selected in the previous step can access the ProductCoreAbbreviated. 6 Click OK. Close all remaining windows. Log in to your Peregrine Web application to make sure the access permissions are set correctly. The Windows NT Challenge/Response settings are activated when you log in through a special login page named login.asp. Accessing your applications through the standard login.jsp page results in the users needing to log on as usual. To test the settings: 1 Open a Web browser. 2 Enter the following URL: in the browser address field (where webserver is the name of your Web server and oaa is the name of the virtual directory created during installation). 3 Verify that access to OAA Platform is what you expected based on the settings you chose for the login.asp and loginverify.asp files. Windows NT Challenge/Response 83

84 OAA Platform 84 Chapter 5 Security

85 6 CHAPTER Tailoring Peregrine Portal Themes OAA Platform provides a number of ways to customize the interface of an application built on the platform. You can make a quick change, such as replacing the logo with your company logo, or a more complex change such as rewriting the code that defines layer placement or frameset size. This chapter includes advanced procedures for changing the ProductCoreAbbreviated interface. To use this information effectively, you should have knowledge of XML and the CSS2 specifications established by the W3C as outlined at Tailoring Peregrine Portal Themes 85

86 OAA Platform Deploying the Classic Theme Variations The Classic theme is the default theme used by applications built on the OAA Platform. This is the theme you will use to create a customized theme for your enterprise. There are three variations of the Classic theme: Classic, the neutral gray design, which is the version shown in this document. Blues, which adds blue hues to the Classic design. Greens, which adds green hues to the Classic design. These themes, as well as a number of other optional themes, are deployed with the application installation. However, once you have created your customized theme, it is recommended that you delete all other themes to prevent users from selecting one of them and overriding your custom theme. If you decide later that you want to manually deploy a theme that has been deleted, or if you did not deploy all themes during the installation, use the following procedure to deploy the theme(s) from the oaa\packages directory. To deploy an alternate Classic design: 1 In a command prompt window, change directories to C:\oaa\packages. 2 Type: java -jar OAADeploy.jar <name of the theme> Note: If you want to deploy both of the variations on the classic theme, type both of the theme names, separated by a space. 3 Press ENTER. 4 Open your Web browser and log in to the Admin module (localhost/oaa/admin.jsp). 5 Click Settings. On the Common tab, locate the section called Themes - Skins and Stylesheet Settings and change the following parameters: a In the Default skin/theme field, change the parameter to the name of the theme you want to use (blues or greens). b In the Default stylesheet field, change the parameter to the appropriate name for the CSS file (blues.css or greens.css). 6 Scroll to the bottom of the page, and then click Save. 86 Chapter 6 Tailoring Peregrine Portal Themes

87 Administration Guide Locating the Files 7 When the Control Panel is displayed, click Reset Server. 8 Refresh your browser to see the new theme. Note: The file locations in this document are for systems using Tomcat as the application server. These files are located in an equivalent directory for installations using an alternate application server. The following file types are used to create themes: Java Server Pages (JSP) enable the display of dynamic data in a Web browser. JSPs process data received for display as an HTML page in a browser. Cascading Style Sheets (CSS) define a set of parameters for how HTML pages appear in a Web browser. The set of styles is applied to all pages within the application. Image (GIF) files the header and other image files that make up the interface. JSP Files The JSP files for the Classic theme are located at...\jakarta-tomcat-3.2.4\webapps\oaa\images\skins\classic. These files will be the template for your new custom theme. The JSP files are organized into three categories according to the browser type: Netscape 4 series (_ns): frames_ns.jsp admin_frames_ns.jsp layers_ns.jsp Internet Explorer 5 series (_ie) frames_ie.jsp admin_frames_ie.jsp layers_ie.jsp Netscape 6 series (_gecko) frames_gecko.jsp Locating the Files 87

88 OAA Platform admin_frames_gecko.jsp layers_gecko.jsp CSS Files The CSS files are located at...\jakarta-tomcat-3.2.4\webapps\oaa. These files are separated into two folders: css folder for the Internet Explorer, Netscape 6.x, and Mozilla files. ns_css folder for Netscape 4.x files. Each of these folders contains a file called classic.css. Important: Whenever you modify a file, make sure that you modify the corresponding file for each of the browser types used by your enterprise. Preparing for Customization Any changes you make to the Classic theme should be done in a copy of the theme. You will also need to make copies of the CSS files. To make the folder and file copies: 1 Locate the classic (or blues or greens) folder (...\jakarta-tomcat-3.2.4\webapps\oaa\images\skins\classic) and make a copy of the folder. Rename the folder to anything you want that will identify the theme as your corporate theme. 2 Locate the css folder (for Internet Explorer, Netscape 6.x, or Mozilla browsers) and/or the ns_css folder (for Netscape 4.x), and make a copy of the classic.css file in this folder. Give the copied CSS file the same name you gave the new folder in step 1. For example, if you named the theme folder corporate, the CSS file would be named corporate.css. 3 If you want users to have access only to the customized corporate theme, delete all other skin folders and CSS files.this is necessary to prevent a user from selecting another theme as a user preference, which will override your corporate theme. If you decide that you want to use these files again, you can redeploy them using the preceding procedure. 88 Chapter 6 Tailoring Peregrine Portal Themes

89 Administration Guide Make all of your theme customizations in these new folders and the new CSS files. Back up these changes so that if you redeploy your application, the changes will not be lost. Changing the Header Graphic One of the easiest changes you can make is to add your corporate logo to the ProductCoreAbbreviated. To change the header graphic: 1 Open the file getit_header_logo.gif in an image editor. The file is located at C:\jakarta-tomcat \webapps\oaa\images\skins\<corporate theme>. 2 Edit the header as needed to customize it for your enterprise. 3 To save your changes, do one of the following: Replace the existing header file with your new file, keeping the same name. To do this: a Rename the existing header file as a backup. b Copy your new file into the classic folder and name it getit_header_logo.gif. c Or: To display the new image in the interface, refresh your browser. Use your new file name to be the header file. If you choose this option, you will need to define this new file name as the logo for your system. To do this: a Log in as an administrator (admin.jsp login page). b Click Settings. Changing the Header Graphic 89

90 OAA Platform c On the Common tab, scroll to the section called Themes - Skins and Stylesheet Settings. d e f g In the Default Peregrine Portal logo field, type the new image name. Scroll to the bottom of the page, and then click Save. When the Control Panel is displayed, click Reset Server. Refresh the browser to view your changes. 90 Chapter 6 Tailoring Peregrine Portal Themes

91 Administration Guide Modifying the Style Sheets For each theme folder name, there is a corresponding css file of the same name. For example, the classic theme has two corresponding classic.css files, one for Internet Explorer, Netscape 6.x, and Mozilla, and one for Netscape 4.x. These css folders are located at <tomcat>\webapps\oaa\. You can view the changes you have made on the Change theme page, available from the Peregrine Portal Home page. Modifying the Style Sheets 91

92 OAA Platform You may also refer to the more detailed style sheet key in the themes Administration section of the Portal. To access the style sheet key, locate the Default stylesheet field on the Common tab of the Admin Settings page and click the Peregrine Portal Stylesheet Key link. Click this link to view the Stylesheet Key. 92 Chapter 6 Tailoring Peregrine Portal Themes

93 Administration Guide Editing the CSS Files The following shows a portion of the classic.css file. The font family, size, weight and color, as well as other parameters such as the background color for the style are defined in this file. Some of the more commonly-modified styles are listed in the following table. Style Name.PageTitle.FormTitle.TableHeading.TableEvenRow Style Description Used on the page title located directly below the logo and tabs. Used for the title of forms. Normally used to title DocExplorer window content. Used for application headings for both search and results functions. Used within the table heading with alternating background colors for ease of reading. Has a background color of white. Modifying the Style Sheets 93

94 OAA Platform Style Name.TableOddRow a.tableevenrow a.tableoddrow.listboxheading.listboxevenrow.listboxoddrow a.listboxevenrow a.listboxoddrow.actionbutton.modulemenu.modulemenutitle.currentmodulemenu.activemodulemenu.menulink.activemenulink Style Description Used within the table heading with alternating background colors for ease of reading. Has a background color of light gray. Designates the style with a link attribute. Designates the style with a link attribute. A bolded version of Table Heading. A bolded version of TableEvenRow. A bolded version of TableOddRow. Designates the style with a link attribute. Designates the style with a link attribute. The style used on buttons throughout the Portal. Used for the left-hand navigational menu. Designates the navigational subsets title. Designates the currently-selected navigational subset. Designates the currently-selected page within the navigational subset. Used within all module menus. Used when the mouse hovers over a menu link. In general, you should modify the style sheets after you have completed the overall design using the image editor s color picker to ensure that the hexadecimal choices are as true to the logo and design as possible. 94 Chapter 6 Tailoring Peregrine Portal Themes

95 Administration Guide Changing the Layers Layers are implemented using the div tag. Each div tag has an id attribute describing its function in the header. Decide which functionality you wish to retain or omit in your new header, and then modify the appropriate tags. The following div tags are required: logo div time div toolbar div user div tabs div form titles div Save your modifications to your deployment directory and then refresh your browser to view the changes. The following code samples show how the div tags work. These samples are from the layers_ie.jsp file located at C:\<tomcat>\webapps\oaa\images\ skins\classic and are for Internet Explorer. Corresponding files for Netscape have a _gecko or _ns designation. Make sure that you modify all files if your application will be used in both Internet Explorer and Netscape browsers, and that you make the modifications in the corresponding JSP file in your corporate theme folder. Positions the logo layer in the header: <div id="logo" style="position:absolute; left: 0px; top: 0px; width: 100%; height: 40px; z-index: 3;"> <img name="logo" border="0" src="<%= logo %>" alt="logo"> </div> Positions the time and alert line layer used for debugging and alerts: <div id="time" style="position:absolute; right: 4px; top: 84px; width: 100%; z-index: 13;" onmouseover="_pausealert()" onmouseout="_startalert()" class="userbartext"> </div> Changing the Layers 95

96 OAA Platform Positions the toolbar buttons layer located currently in the upper right section of the header: <div id="toolbar" style="position:absolute; width: 50px; top: 59px; right: 0px; z-index: 12;"></div> Positions the name of the currently logged-in user in the header: <div id="user" style="position:absolute; top: -4px; right: 0px; z-index: 14;"> <table width="100%" border="0" cellpadding="0" cellspacing="0" align="right"> <tr> <td width="50%"> </td> <td nowrap width="3" align="right" valign="top"> <img src="<%= Archway.getSkinImagePath("backgrounds/rt_l.gif", user ) %>"> </td> <td nowrap align="right" valign="top" width="100%" background="<%= Archway.getSkinImagePath("backgrounds/rt_tile.gif", user ) %>"> <img src="<%= Archway.getSkinImagePath("backgrounds/rt_tile.gif", user ) %>"> </td> <td nowrap><font class="userbartext" size="1" face="arial, Helvetica, sans-serif"><%=usertitle%></font> </td> </tr> </table> </div> Positions the navigational tabs in the header: <div id="tabs" style="position:absolute; left: 0px; top: 60px; width: 100%; z-index: 11;" > </div> Positions the page title layer in the header: <div id="formtitles" style="position:absolute; left: 10px; top: 81px; width: 200px; z-index: 16;"> </div> 96 Chapter 6 Tailoring Peregrine Portal Themes

97 Administration Guide Changing the Framesets Important: You should have advanced knowledge of frames to modify these files. Keep all of the frames and do not change the names of any of the frames. To do so will result in JavaScript errors in your application. There are two framesets to be modified for each browser, for a total of six files. These files are located at...\jakarta-tomcat-3.2.4\webapps\oaa\images \skins\<your corporate theme>. The frames_xx.jsp files are for the pages that you access when logging in as an end-user (login.jsp). The admin_frames_xx.jsp files contain the configuration for the Admin module (accessed when you log in using admin.jsp). The following sections show the complete -ie.jsp files as examples of the frameset files. frames_ie.jsp <%@ include file="../../../jspheader_2.jsp" %> <%@ include file="../../../message_special.jsp" %> <frameset onload="settopframes()" onunload="closechildwindows()" border="0" framespacing="0" frameborder="no" cols="*" rows="102,*"> <frame scrolling="no" marginwidth="0" marginheight="0" src="oaa_header.jsp" name="getit_main_head"> <frameset cols="185,10,*" rows="*" frameborder="no" border="0" framespacing="0"> <frame scrolling="auto" marginwidth="0" marginheight="0" src="apphead.jsp" name="getit_header"> <frame name="framesep" scrolling="no" marginheight="0" marginwidth="0" src="framesep.jsp"> <frameset rows="*,0"> <frame scrolling="auto" marginwidth="6" marginheight="6" src="e_login_main_start.jsp?<%= user.getadw(msg,"params" ) %>" name="getit_main"> <frame noresize scrolling="no" marginwidth="0" marginheight="0" src="backchannel.htm" name="backchannel"> Changing the Framesets 97

98 OAA Platform </frameset> </frameset> </frameset> admin_frames_ie.jsp include file="../../../jspheader_2.jsp" %> include file="../../../message_special.jsp" %> <frameset onload="settopframes()" onunload="closechildwindows()" border="0" framespacing="0" frameborder="no" cols="*" rows="102,*"> <frame scrolling="no" marginwidth="0" marginheight="0" src="oaa_header.jsp" name="getit_main_head"> <frameset cols="185,10,*" rows="*" frameborder="no" border="0" framespacing="0"> <frame scrolling="auto" marginwidth="0" marginheight="0" src="apphead.jsp" name="getit_header"> <frame name="framesep" scrolling="no" marginheight="0" marginwidth="0" src="framesep.jsp"> <frameset rows="*,0"> <frame scrolling="auto" marginwidth="6" marginheight="6" src="e_adminlogin_login_start.jsp?<%= user.getadw(msg, "Params") %>" name="getit_main"> <frame noresize scrolling="no" marginwidth="0" marginheight="0" src="backchannel.htm" name="backchannel"> </frameset> </frameset> </frameset> 98 Chapter 6 Tailoring Peregrine Portal Themes

99 7 CHAPTER Using OAA Workflow OAA Workflow is an optional component of the OAA Platform. OAA Workflow provides a workflow system where a business process is defined in a process definition. The process definition is composed of activities that can be manual activities or automated activities and is used to create and manage process instances. In the execution of a process instance, activity instances are started. The activity instances include work items allocated to a workflow participant or to an invoked application used to support an activity. Definitions of Workflow terminology are included in the Glossary beginning on page 172. Note: The screen shots shown in this chapter represent a generic installation of the Peregrine Portal, Notification Services, and Workflow. Your Portal may have additional navigation buttons and tabs for your Web application. The workflows shown are examples only and do not represent actual workflows. Using OAA Workflow 99

100 OAA Platform Defining Workflow Templates The workflow templates are process definitions for business processes associated with a business object, such as contracts or projects. Business objects can be attached to a specified workflow template designed for processing work for the business object. Creating a Workflow Template OAA Workflow provides a graphical workflow designer for designing and creating workflow templates. After a workflow template is created and attached to a business process, process instances of the workflow template can be started. Each process instance will be routed according to the activities specified in the workflow template, but the workflow definition for a process instance is no longer linked to the workflow template. If changes to the routing are required during processing, the user can modify the workflow through the workflow designer for that specific process instance. The workflow template will not be changed and future process instances will be routed according to the workflow template. Note: Capability (permission) must be assigned to a user before the user can modify a workflow route. Refer to the administrator s guide for your application for information on granting capabilities to a user. 100 Chapter 7 Using OAA Workflow

101 Administration Guide To create a workflow template: 1 Log on to your Web application to display the Navigation Menu on your Home page. 2 Click the Workflows tab, or click Workflows from the Navigation Menu. The Workflow menu will display in the left pane. Defining Workflow Templates 101

102 OAA Platform 3 From the Workflows menu, click Template Design to display the List of Workflow templates page. Note: After workflow templates are defined, the template name and type (Process or Component), for each template will display in the list. 4 Click New Process. 102 Chapter 7 Using OAA Workflow

103 Administration Guide The Create a New Workflow page is displayed. The Type entry of Process is created by the system based on your selection of the New Process button. 5 In the Name text box, type the name of the new workflow template. 6 In the Process Type section, select one of the option buttons to define the process type associated with this workflow template. Standalone When the Standalone option button is selected, there is no link to a business object or to data. Business Object When the Business Object option button is selected, the workflow will be related to a business object associated with your Web application. Embedded Data When the Embedded Data option button is selected, the workflow will be related to data. This data is not stored in the database, but is carried with the process. 7 If you selected the Business Object option button, select the business object from the associated drop-down list. 8 If you selected the Embedded Data option button: a Select the entity or schema from the associated drop-down list. Defining Workflow Templates 103

104 OAA Platform b Click Data Layout to display the EditLayout window. You can change the data layout using the Personalize this page option at the top of the page. Refer to your Web application documentation for information on the Personalization feature. c Click Save to exit the EditLayout window and return to the Create a New Workflow page. The workflow template will define a specific process definition. The name assigned to the template must be unique and should reflect the process definition. Each workflow template must have a Start and End activity. When initially displayed, the workflow designer contains the Start and End activity, and includes a sample activity that can be modified for use in your workflow template or can be deleted. See Modifying an Activity on page 121 and Deleting an Activity on page In the workflow designer, create and add activities to the workflow template using the toolbar icons described in the following table. Icon Description Select a component from the template list. See To add a component template: on page 120 for information on adding an activity from the template list. Create a new Select activity. See To create and add a Select activity: on page 115 for information on adding a Select activity. 104 Chapter 7 Using OAA Workflow

105 Administration Guide Icon Description Create a new Jump activity. See To create and add a Jump activity: on page 118 for information on adding a Jump activity. Create a new activity. See To create and add a new activity: on page 105 for information on adding a new activity. Trash. See To delete an activity: on page 122 for information on deleting an activity from a workflow template. In addition to the activity icons on the toolbar, zoom functionality is provided by the following toolbar icons. Icon Description To zoom in on the workflow template graphic, click the Zoom in icon until the required magnification is achieved. To zoom out on the workflow template graphic, click the Zoom out icon. Creating a New Activity These activities represent the basic activities used when defining a workflow template for a specific process definition. An activity can be one of four types: Task, Approval, Message, or Script. To create and add a new activity: 1 Position the cursor over the Activity icon, then click and hold down the left mouse button. 2 Drag the Activity icon over an activity so that the new activity will precede, follow, or be parallel to that activity. Notice that a rectangle outlined in red will display along with the icon. 3 To select the placement of the new activity, position the red rectangle in one of the positions described in the following table and release the left mouse button. Defining Workflow Templates 105

106 OAA Platform Note: The position of the new activity is determined by where the red rectangle is located when you release the mouse button. When positioned... over the first half of the current activity over the last half of the current activity over the top half of the current activity over the bottom half of the current activity The activity will be placed... before the current activity after the current activity above the current activity below the current activity Parallel routing is defined by creating activities above or below a current activity (AND-Split). The activities are then joined later in the process by adding an activity after the parallel activities (AND-Join). 106 Chapter 7 Using OAA Workflow

107 Administration Guide After you click the mouse button, the Workflow window is displayed. You will define the details for the new activity through this window. 4 In the Title text box, type the title you want to display on the activity in the workflow designer. 5 Select the task type from the Type drop-down list. Values for Type are: Task a manual task Approval a task requesting approval Message an informational message that does not require user work Script a task performed by the system 6 In the Subject text box, type a short description of the task. This description will display in the ScreenTip when the cursor is placed over the activity. 7 In the Description box, type a full description of the task, or type the detailed message when the selected Type option button is Message. Defining Workflow Templates 107

108 OAA Platform 8 If you want to prompt a customized form for a business object, select the name of the form from the Form Name drop-down list. Instead of the standard Task Details page, the selected form will display when viewing task details. 9 Click Next. The Workflow window displays additional activity details. The activity details will be different depending on the Type option button selected. If the selected type is Task or Approval, see To complete the activity details for Task or Approval tasks: on page 108. If the selected type is Message, see To complete the activity details for a Message task: on page 111. If the selected type is Script, see To complete the activity details for a Script task: on page 113. To complete the activity details for Task or Approval tasks: When the activity type is Task or Approval, the Workflow window shown below is displayed. 108 Chapter 7 Using OAA Workflow

109 Administration Guide 1 In the Choose whom to notify to accomplish the task section, select one of the option buttons to determine who is notified of the task. User that initiated the process The user who initiated the process will be notified. By Person The specific person selected will be notified. By Role All users assigned to the selected role will be notified. 2 If you selected the By Person option button: a Click the magnifying glass to display the Employee Lookup window. b Using this window, select the person you want to notify. The name of the person selected will display next to the option button. 3 If you selected the By Role option button, select the role from the associated drop-down list. 4 If you want to notify the user by , select the Notify recipient check box. Note: The user will be notified by the method set in the Notification Services tab. For information on Notification Services, refer to the Notification Services 2.2 Quick Start Guide. When a user receives an notification, it contains standard message text and a link to the application where the associated activity will be displayed. Defining Workflow Templates 109

110 OAA Platform 5 In the How many hours will this task require? section, you have the following options: a When the task is time-sensitive, type the number of hours allocated for the task to be completed in the Estimated time text box. b Select the Calculate deadline by assignee work hours check box if you want the deadline to be calculated according to the actual work schedule of the assignee. For example, this would prevent the deadline from occurring on a day that the assignee normally has off. c Select the Auto complete upon deadline check box to cause the activity to go to completed state when the deadline is reached. If you select this option, also choose a default status from the drop-down list in the Auto complete default status field. You can set an alarm for a time-sensitive task using . 6 Select the alarm type from the Type drop-down list. Values are: None an alarm is not defined for the task. Time elapsed since start of task alarm will be sent when the elapsed time (specified in Time limit) from the start of the task is reached. Time before end of task alarm will be sent when the number of hours (specified in Time limit) prior to the end of the task is reached. Note: When the alarm type is Time before end of task, the Estimated time text box must contain an entry for the number of hours allocated for the task. 7 Select the Send reminder to assignee check box to send the notification to the person assigned to the task. 8 Select the Send reminder to other user check box when you also want to send the notification to another person. This person may be a supervisor or project manager who needs to know that a time-sensitive task is pending. 9 Click the magnifying glass to display the Employee Lookup window. 10 Using the window, select the other user to notify. 11 Click Update to complete the task definition and display the activity in the workflow designer. 110 Chapter 7 Using OAA Workflow

111 Administration Guide To complete the activity details for a Message task: When the activity type is Message, the Workflow window shown below is displayed. 1 In the Choose whom to notify to accomplish the task section, select one of the option buttons to determine who is notified of the task. User that initiated the process The user who initiated the process will be notified. By Person The specific person selected will be notified. By Role All users assigned to the selected role will be notified. 2 If you selected the By Person option button: Defining Workflow Templates 111

112 OAA Platform a Click the magnifying glass to display the Employee Lookup window. b Using this window, select the person you want to notify. The name of the person selected will display next to the option button. 3 If you selected the By Role option button, select the role from the associated drop-down list. 4 If you want to notify the user by , select the Notify assignee of this task check box. Note: The user will be notified by the method set in the Notification Services tab. For information on Notification Services, refer to the Notifications Service 2.2 Quick Start Guide. When a user receives an notification, it contains standard message text and a link to the application where the associated activity will be displayed. a If you have defined a custom template in Notification Services, click the magnifying glass icon next to Custom Message Template. A window is displayed, from which you can select the template you want to use. b If you select a custom template that uses fields other than the default workflow fields, enter the name of the Java class that will be used to render the custom template in the Custom Render Class field. 5 Click Update to complete the task definition and display the Message activity in the workflow designer. 112 Chapter 7 Using OAA Workflow

113 Administration Guide To complete the activity details for a Script task: When the activity type is Script, the Workflow window shown below is displayed. Defining Workflow Templates 113

114 OAA Platform 1 Click the magnifying glass next to Script Function Name to display the Script File Lookup window. 2 Using this window and following the lookup instructions, locate and select the script function. The selected script function name will display next to Script Function Name in the Workflow window. 3 Select one of the following option buttons to determine how the workflow process will be continued after the script is executed: Go to next step after execution Select this option button if you want the system to continue the workflow process after the script is executed. Wait for external notification Select this option button if you want the system to wait for an event from an external system before continuing the workflow process. 4 Click Update to complete the task definition and display the activity in the workflow designer. Creating a Select Activity A Select activity is used to branch workflow routing (OR-Split). The workflow route is determined by a decision made in the previous activity or, in the case of a Custom Select, by the value returned after a script is executed. 114 Chapter 7 Using OAA Workflow

115 Administration Guide Note: If a Select activity, where the selection type is Approval, is present in the workflow, an Approval type activity must directly precede the Select activity. To create and add a Select activity: 1 Position the cursor over the Split icon, then click and hold down the left mouse button. 2 Drag the Split icon over an activity so that the new activity will precede, follow, or be parallel to that activity. Notice that a rectangle outlined in red will display along with the icon. 3 To select the placement of the Select activity, position the red rectangle in one of the positions described in the following table and release the left mouse button. Note: The position of the activity is determined by where the red rectangle is located when you release the mouse button. When positioned... over the first half of the current activity over the last half of the current activity over the top half of the current activity over the bottom half of the current activity The activity will be placed... before the current activity after the current activity above the current activity below the current activity Defining Workflow Templates 115

116 OAA Platform After you release the mouse button, the Workflow window will display. 4 Type a name for the task in the Title text box. The title will display (followed by the task number) on each of the activities associated with this Select activity. 5 Select the type of selection from the Type drop-down list. Values are: Approval checks the previous activity to determine the routing requirements. If you select this option and you have defined Time Out as the Auto Complete Default Status for the task, select Add a timeout branch in the Approval Select section. Custom determines the routing requirements from the value returned by a script. If you selected Approval, go to step 8 to complete the procedure. 116 Chapter 7 Using OAA Workflow

117 Administration Guide 6 If you selected Custom, click the magnifying glass next to Script to display the Script File Lookup window. 7 Using this window and following the lookup instructions, locate and select the script function. The selected script function name will display next to Script in the Workflow window. 8 Type or select the number of branches in the Number of branches text box. 9 Click Update to complete the Select activity definition and display the activity in the workflow designer. A Select activity creates activities for each of the branches created. The top activity (task 1) will execute when the prior task is approved. The bottom activity (task 2) will execute when the prior task is declined. Defining Workflow Templates 117

118 OAA Platform 10 Click each of the branch activities and modify the activity details. See Modifying an Activity on page 121 for information on modifying activity details. Creating a Jump Activity A Jump activity is used to re-route the process forward or backward to a specific activity. For example, when an approval is declined, the process may be sent back to another activity for changes or sent forward to the End activity. To create and add a Jump activity: 1 Position the cursor over the Jump icon, then click and hold down the left mouse button. 2 Drag the Jump icon over an activity so that the new activity will precede, follow, or be parallel to that activity. Notice that a rectangle outlined in red will display along with the icon. To select the placement of the Jump activity, position the red rectangle in one of the positions described in the following table and click the left mouse button Note: The position of the activity is determined by where the red rectangle is located when you release the mouse button. When positioned... over the first half of the current activity over the last half of the current activity over the top half of the current activity over the bottom half of the current activity The activity will be placed... before the current activity after the current activity above the current activity below the current activity 118 Chapter 7 Using OAA Workflow

119 Administration Guide After you release the mouse button, the Workflow window will display. 3 From the activity list, select the destination activity for the jump. The title of the destination activity will display in the ScreenTip when the cursor is placed over the jump activity. The Workflow window will close and the Jump activity will be added in the workflow designer. Adding a Component Template Component templates are a set of activities that represent a portion of a process that can be used in more than one workflow template. See Creating a Component Template on page 127. When component templates have been pre-defined in the system, you can add them to your workflow template if they meet your requirements for the process being defined. Defining Workflow Templates 119

120 OAA Platform A component template that is added to a workflow process template is a copy and is no longer linked to the original component template. If changes are made to the original component template, a component template previously added to a workflow process template will not inherit those changes. To add a component template: 1 Position the cursor over the Components icon, then click and hold down the left mouse button. 2 Drag the Components icon over an activity so that the component template will precede, follow, or be parallel to that activity. Notice that a rectangle outlined in red will display along with the icon. To select the placement of the activity, position the red rectangle in one of the positions described in the following table and release the left mouse button. Note: The position of the activity is determined by where the red rectangle is located when you release the mouse button. When positioned... over the first half of the current activity over the last half of the current activity over the top half of the current activity over the bottom half of the current activity The activity will be placed... before the current activity after the current activity above the current activity below the current activity 120 Chapter 7 Using OAA Workflow

121 Administration Guide After you release the mouse button, the Workflow window will display a list of component templates. 3 Click the component template you want to add to the workflow template. The Workflow window will close and the component template will be added in the workflow designer. Modifying an Activity In the process of designing a workflow template, after activities are created, they may need to be moved to another location in workflow, re-defined using different options, or renamed. The Sample activity provided in the initial workflow designer must be modified if you want to use it within your workflow template. Activities can be modified before or after the workflow template is saved. Defining Workflow Templates 121

122 OAA Platform Note: Modifying an activity within a workflow template that has already been created does not effect process instances that are currently running. After a process instance is started, it is no longer linked to the workflow template. To modify an activity 1 Click the activity you want to modify. The Workflow window for the selected activity will display the activity details. 2 Make the required modification to the activity details. Depending on the activity you are modifying, see Creating a New Activity on page 105, Creating a Select Activity on page 114, Creating a Jump Activity on page 118, or Adding a Component Template on page 119 for specific instructions on defining activity details. 3 Click Update. Deleting an Activity Activities can be deleted from a workflow template before or after the workflow template is saved. Note: Deleting an activity within a workflow template that has already been created does not effect process instances that are currently running. After a process instance is started, it is no longer linked to the workflow template. To delete an activity: 1 Using the left mouse button, click the activity you want to delete and hold down the mouse button. 2 Drag and drop the activity onto the Trash icon. Saving the Workflow Template After a new workflow template is completed, you must save the template. To save the workflow template: Click Create. The workflow template will be added to the List of Workflow templates. Note: If you exit the Create a New Workflow page prior to clicking Create, all changes to the workflow template will be discarded. 122 Chapter 7 Using OAA Workflow

123 Creating a New Workflow Template from Another Template Administration Guide A workflow template can be created from a defined workflow template that has many of the same activity sequences. To create a workflow template from another template: 1 Log on to your Web application to display the Navigation Menu on your Home page. 2 Click the Workflows tab, or click Workflows from the Navigation Menu. The Workflow menu will display in the left pane. 3 Click Template Design from the Workflows left pane menu to display the List of Workflow templates page. 4 Locate and click the name of the workflow template you want to use as the base for the new workflow template. The Details for template page is displayed. 5 Make modifications to the template to accommodate the required activities for the new template. See Creating a Workflow Template on page 100 for information on adding, modifying, or deleting activities. 6 Change the name of the template. 7 Click Save As to save the workflow template with the new name. Modifying a Workflow Template A workflow template can be modified as necessary to ensure its continued alignment with the business process it represents. Note: Modifying a workflow template does not affect process instances that are currently running. After a process instance is started, it is no longer linked to the workflow template. To modify a workflow template: 1 Log on to your Web application to display the Navigation Menu on your Home page. 2 Click the Workflows tab, or click Workflows from the Navigation Menu. The Workflow menu will display in the left pane. Defining Workflow Templates 123

124 OAA Platform 3 Click Templates Design from the Workflows left pane menu to display the List of Workflow templates page. 4 Locate the workflow template you want to modify. 5 Click the name of the workflow template you want to modify. 124 Chapter 7 Using OAA Workflow

125 Administration Guide The Details for template page is displayed. 6 Make the necessary modifications to the template. See Creating a Workflow Template on page 100 for information on adding, modifying, or deleting activities. 7 Click Update to update the workflow template and return to the List of Workflow templates page. Deleting a Workflow Template When a workflow template is no longer useful or the process has been redefined as another template, you can delete the workflow template. Note: Deleting a workflow template does not effect process instances that are currently running. After a process instance is started, it is no longer linked to the workflow template. To delete a workflow template: 1 Log on to your Web application to display the Navigation Menu on your Home page. 2 Click the Workflows tab, or click Workflows from the Navigation Menu. The Workflows menu will display in the left pane. Defining Workflow Templates 125

126 OAA Platform 3 Click Template Design from the Workflows menu to display the List of Workflow templates page. 4 Locate the workflow template you want to delete. 5 Click the name of the workflow template you want to delete. The Details for template page is displayed. 126 Chapter 7 Using OAA Workflow

127 Administration Guide 6 Scroll to the bottom of the page, and then click Delete to delete the workflow template and return to the List of Workflow templates page. The workflow template list no longer displays the name of the deleted workflow template. Creating a Component Template Component templates are a set of activities that represent a portion of a process. These templates can be used when designing workflow process templates. To create a component template: 1 Log on to your Web application to display the Navigation Menu on your Home page. 2 Click the Workflows tab, or click Workflows from the Navigation Menu. The Workflow menu will display in the left pane. 3 Click Template Design from the Workflows left pane menu to display the List of Workflow templates page. Note: After component templates are defined, the template name and type (Component), will display in the list. 4 Click New Component. Defining Workflow Templates 127

128 OAA Platform The Create a New Workflow template page is displayed. 5 In the Name text box, type the name of the new component template. The component template will define a specific set of activities. The name assigned to the template must be unique. Notice that the workflow designer contains only a sample activity. Since a component template is designed to be added to a workflow template, component templates do not contain the Start and End activities. The sample activity can be modified for use in the component template or deleted. See Modifying an Activity on page 121 and Deleting an Activity on page In the workflow designer, create and add activities to the component template using the toolbar icons described in the following table. Icon Description Select a new activity from the template list. See To add a component template: on page 120 for information on adding an activity from the template list. Create a new Select activity. See To create and add a Select activity: on page 115 for information on adding a Select activity. 128 Chapter 7 Using OAA Workflow

129 Administration Guide Icon Description Create a new Jump activity. See To create and add a Jump activity: on page 118 for information on adding a Jump activity. Create a new activity. See To create and add a new activity: on page 105 for information on adding a new activity. Trash. See To delete an activity: on page 122 for information on deleting an activity from a workflow template. In addition to the activity icons on the toolbar, zoom functionality is provided by the following toolbar icons. Icon Description To zoom in on the workflow template graphic, click the Zoom in icon until the required magnification is achieved. To zoom out on the workflow template graphic, click the Zoom out icon. To create and add a new activity, see Creating a New Activity on page 105. To create and add a Jump activity, see Creating a Jump Activity on page 118. To create and add a Select activity, see, Creating a Select Activity on page 114. To add a component template for inclusion into this component template, see Adding a Component Template on page 119. See Modifying an Activity on page 121 and Deleting an Activity on page 122 for information on modifying and deleting activities. 7 Click Create. The component template will be added to the List of Workflow templates. Note: If you exit the Create a New Workflow page prior to clicking Create, all changes to the workflow template will be discarded. Defining Workflow Templates 129

130 OAA Platform Using the Worklist Accessing the Worklist Workflow users receive work items through a worklist. This chapter provides information on how to use your worklist and complete your work items. Note: Users can be notified through when work items are received. The notification contains standard message text and a link to the Web application, where the associated activity will be displayed. As a workflow user, you will receive work items through your worklist. To access your worklist: 1 Log on to your Web application to display the Navigation Menu on your Home page. If you have customized your Home page to include the My Messages workflow component, the My Messages frame will display below the Navigation Menu. 130 Chapter 7 Using OAA Workflow

131 Administration Guide You can access your work items directly from this page, or from the Navigation Menu, click Workflows to display the My Messages page. 2 Click the magnifying glass icon next to the work item to display the work item details page. The page displayed depends on the activity type. Completing Work Items Each work item on your worklist must be completed according to the information displayed in the Details tab for that work item. There are three types of work items, based on the activity type: Task See To complete a Task activity: on page 132. Approval See To complete an Approval activity: on page 133. Message See To complete a Message activity: on page 134. Note: If a customized form was selected when the activity was created in the workflow template, the Task Details page may contain different information than shown in the following procedures. Using the Worklist 131

132 OAA Platform To complete a Task activity: 1 When the activity is a Task activity, the Task Details page is displayed. 2 Review the General Information frame of the page to determine the task to be performed and if there is a date it must be completed. The date due is optional and depends on the setting defined for the work item activity. 3 Review and complete the instructions in the Detailed Description frame of the page. If you want to reassign the task to another user, see Reassigning a Work Item on page When the task is for a business object, click View details in the Associated Business Object section to view the business object details. 5 If the task instructions require additions or changes to the business object, complete the task instructions in the Details page, then click Submit Changes. To return to the Task Details page, click Return to List. 6 Click Mark as Complete on the Task Details page. 132 Chapter 7 Using OAA Workflow

133 Administration Guide The Enter your comments page will display. 7 Type your comments in the Enter your comments text box. 8 Click Submit to complete the work item. The work item is removed from your worklist and workflow continues to the next activity in the process instance. To complete an Approval activity: 1 When the activity is an Approval activity, the Approval Details page is displayed. 2 Review the General Information frame of the page to determine the task to be performed and the date it must be completed. 3 Review the instructions in the Detailed Description frame of the page. If you want to reassign the task to another user, see Reassigning a Work Item on page When the task is for a business object workflow, click View details in the Associated Business Object section to view the business object details. 5 Click Return to List to return to the Approval Details page. 6 Click Approve to approve the work item, or click Decline to decline approval. Using the Worklist 133

134 OAA Platform The Enter your comments page will display. 7 Type any comments in the Enter your comments text box. 8 Click Submit to complete the work item. The work item is removed from your worklist and workflow continues to the next activity in the process instance. The next activity depends on whether you approve or decline the work item. To complete a Message activity: 1 When the activity is an Approval activity, the Approval Details page is displayed. 2 Read the message in the Detailed Description frame of the page. If you want to forward the message to another user, see Reassigning a Work Item on page If you want to view the details of an associated business object, click View details. The details page for the business object is displayed. 4 To return to the Message Details page, click Return to List. 5 Click Mark as Read to complete the work item and delete the work item from your worklist, or click Forward to send the message to another user. The work item is removed from your worklist and workflow continues to the next activity in the process instance. Reassigning a Work Item Reassigning a work item to another user will add that work item to the worklist of the other user and will remove the work item from your worklist. Note: To temporarily reallocate all your work items to any user, see Delegating Your Worklist to Another User on page 139. To reassign a task to another user: 1 From the Task Details page or the Approval Details page click Reassign, or from the Message Details page, click Forward. 134 Chapter 7 Using OAA Workflow

135 Administration Guide The Reassign Task page is displayed. 2 Click the magnifying glass in the Select the person section to display the Employee Lookup window. Using the Worklist 135

136 OAA Platform Viewing History 3 Using this window, select the person you want to reassign the work item. The name of the person selected will display next to the magnifying glass in the details page. 4 Click Submit. 5 The work item will be removed from your work list and will display in the work list of the user where it was reassigned. You can view the history of the work items for a process instance. To view the process instance history: 1 From the My Messages page, click the magnifying glass icon next to the work item entry. The details page for the selected work item is displayed. 2 Click the History tab to display the history list of the process instance activities. The history list contains the following columns for the previous work items and the current work item for that specific process instance: Start Date The date the work item was started. 136 Chapter 7 Using OAA Workflow

137 Administration Guide Viewing Status End Date The date the work item was completed. Subject A brief description of the work item. To The name of the person or group assigned the work item. Status The status of the work item (such as, Done or In progress). You can view the status of the activities for a process instance. To view the status of the process instance: 1 From the My Messages page, click the magnifying glass icon next to the work item entry. The details page for the selected work item is displayed. 2 Click the Status tab to display a graphical representation of the process instance. Blinking yellow and orange arrows indicate the activities in the process instance that have been completed or are currently in progress. The date an activity was completed is displayed above the activity. When the cursor is placed over an activity, a ScreenTip will display additional information about the activity. Using the Worklist 137

138 OAA Platform Modifying a Process Instance Workflow There may be times that an activity needs to be added to a process instance, or other changes to the workflow are required. A user, who has been assigned the required capabilities (permissions) by the system administrator, can change the workflow through a graphical workflow designer for that specific process instance. Note: Changes to the process instance workflow does not change the workflow process template. After a process instance is started, it is no longer linked to the workflow template. To modify the workflow for a process instance: 1 Click Modify Process Workflow to display the graphical workflow designer for the process instance. 2 Add activities using the toolbar icons, or modify or delete activities. See Creating a Workflow Template on page 100 for information on using the graphical workflow designer. Note: You can only add, modify, or delete activities that are not completed or active for this iteration. 138 Chapter 7 Using OAA Workflow

139 Administration Guide 3 Click Update to save the changes, or click Go Back to cancel changes and return to the work item Delegating Your Worklist to Another User There may be times when you need to delegate your work items to another user. For example, when you go on vacation, or when you will be out of the office for several days. To temporarily delegate your worklist to another user: 1 Access your Home page or the My Messages page. 2 Click Temporary Delegation to display the Delegate Approval page. 3 If you want to delegate all your tasks to one user: a Select the Delegate all my tasks to one user option button. b Click the magnifying glass to display the Employee Lookup window. c Using this window, select the person to assign your worklist. The name of the person selected will display next to the magnifying glass. 4 If you want to delegate your task to multiple users by role: a Select the Delegate my tasks by Role to different users according to the following option button. Using the Worklist 139

140 OAA Platform b On the Remove/Add bar (below the Delegate my tasks by role... check box), click Add to display the Delegate Add page. c Click the magnifying glass next to Role to display the Role Lookup window. d Using this window, select the role. e Click the magnifying glass next to Delegate to User to display the Employee Lookup window. f Using this window select the user. 5 If you want the delegation to last until further notice, select the Until further notice option button. 6 If you want the delegation to be until a specific date, select the Until specified date option button. 7 Select the end date from the End date drop-down lists. 8 Click Submit. Your work items will display in the worklist of the person assigned in the delegation, and will also continue to display in your worklist. To cancel a delegation 1 Access your Home page or the My Messages page. 140 Chapter 7 Using OAA Workflow

141 Administration Guide 2 Click Temporary Delegation to display the Delegate Approval page. 3 Click Cancel Delegation. Using Workflow Administration The Administration function of Workflow provides the ability to start new process instances, monitor all process instances started in the system, update or delete process instances, view event errors, set up the request list, and upload Javascriptfiles. Accessing the Administration Function The workflow administration functions can be accessed only by users having the required capabilities (permissions). To access the Administration function: 1 Log on to your Web application to display the Navigation Menu on your Home page. 2 Click the Workflows tab, or click Workflows from the Navigation Menu. The Workflows menu will display in the left pane. 3 Click Administration from the Workflows left pane menu to display the Administration of processes page. Using Workflow Administration 141

142 OAA Platform From this page you can select the following areas of administration: Process list Start a new process Rejected events Request List Setup Upload JavaScript Files Monitoring Process Instances Using the Process list administration function, you can monitor the status of all process instances started in the system. To view the process list: 1 From the Administration of processes page, click Process list. The Process list page opens. A list of all processes started in the system is displayed. The list contains the following columns of information about the associated process instance: Reference The reference number assigned to the process instance. Start The date the process instance was started. 142 Chapter 7 Using OAA Workflow

143 Administration Guide End The date the process instance was completed. Status The current status of the process instance (Timed out, Completed, Running, Error). Document A description of the process instance. 2 If you want to sort the list according to a particular column attribute, click on the heading of that column. 3 Click Search. The Template Search page opens. 4 Enter your search criteria in the fields provided, and then click Perform Search. A list of the processes matching your search appears. 5 Click Search again to rerun your search, or click the Administration link to return to the Administration of processes page. Updating a Process Instance A process instance can be updated through the Details for process page. The most common reason to update a process instance is that an error has occurred during routing and the process instance has stopped. Important: After you update a process instance because an error occurred, use the procedure in Viewing Error Events on page 148 to locate the process instance error and restart the process instance. Using Workflow Administration 143

144 OAA Platform To update a process instance: 1 From the Administration of processes page, click Process list to display the Process list page. 2 If you want to sort the list according to a particular column attribute, click on the heading of that column. 3 Use the process instance Reference number to locate the process instance you want to update, or click Search to search for existing work processes. 4 Click the process instance to display the Details for process page for the selected process instance. 5 Make the necessary changes to the process instance activities. Note: You cannot change a process instance activity that has already been processed. 6 Click Update to apply the changes and return to the Process list page. 144 Chapter 7 Using OAA Workflow

145 Deleting a Process Instance Administration Guide Projects and certain contracts are associated with a workflow process. When these projects or contracts are created, a workflow process instance is started. If a project or contract using a workflow process is deleted, the workflow process continues, delivering task messages to users on the system. These messages may be distributed not only to the user assigned a task, but also to all users with the same role. After a project or contract is deleted, the process instance associated with the deleted project or contact must also be deleted. To delete a process instance: 1 From the Administration of processes page, click Process list to display the Process list page. 2 Use the process instance Reference number to locate the process instance you want to delete. 3 Click the process instance to display the Details for process page for the selected process instance. 4 Click Delete to delete the process instance and return to the Process list page. Starting a New Process Instance You can manually start processes that are not related to projects or contracts using the Start a new process administration function. Using Workflow Administration 145

146 OAA Platform To start a process instance: 1 From the Administration of processes page, click Start a new process to display the Browse process templates page. 2 From the list of templates, select the template you want to use to start the workflow process. 146 Chapter 7 Using OAA Workflow

147 Administration Guide The Process submit page is displayed. 3 In the Start Date fields, select the date and time that you want the process to start. You can use either the drop-down lists by each field, or click the calendar to select a date. 4 In the Description text box, type a description for the new process instance. 5 Click Submit. Using Workflow Administration 147

148 OAA Platform The Process submitted page is displayed. Viewing Error Events The process number assigned to the new process will display in the Process information frame. Note the process number. 6 Click Continue to return to the Administration of processes page. Using the Rejected events administration function, you can view a list of all workflow errors encountered and perform the necessary interventions. 148 Chapter 7 Using OAA Workflow

149 Administration Guide To view errors: 1 From the Administration of processes page, click Rejected events to display the Events in error page. A list of all event errors is displayed. The list contains the following columns of information about the event: Date The date the error occurred. Process Id The reference number assigned to the process instance. Activity The activity in error. 2 To view the details of an error event, click any of the column entries associated with that event. Using Workflow Administration 149

150 OAA Platform The Event detail page is displayed. 3 After reviewing the error information, you can do one of the following: Setting Up the Request List Click Update for processing to restart processing. Click Go Back to return to the Events in error page. The Request List is a collection of request definitions that process a specified workflow template. A workflow template of any process type can be used for the request definition. However, when the process type is Embedded Data, the data is embedded in the workflow process. For example, a request list definition could be used to order business cards for employees, or to process change of address requests. When the workflow process type is Embedded Data, the employee information data is available to each workflow activity. A request definition can be used to provide various request functions. However, you may need a programmer to write specific scripts that provide the functionality required by your request definitions. After a request definition is created for the request list, a user who has the required capabilities can view the list and create new requests through My Requests. 150 Chapter 7 Using OAA Workflow

151 Administration Guide Searching for a Request Definition The Request Search page provides search functionality. You can search using the available text box. To narrow the search, provide as much information as possible. To search for a request definition: 1 From the Administration of processes page, click Request List Setup to display the Request Search page. 2 Type the request definition name in the Name text box. If you know part of the name, you can type it between % (percent) signs. Using Workflow Administration 151

152 OAA Platform 3 Click the magnifying glass next to Workflow Template to display the Lookup Contact Phone window. 4 Using this window, locate and select the workflow template. 5 Click Search to filter the list of request definitions and display only those matching the search criteria. 152 Chapter 7 Using OAA Workflow

153 Administration Guide Note: You can sort the search results list by any of the displayed columns. To sort the list, click the column title. The Request Search Results page will display only the request definitions matching the search criteria. From the list, you can access the details for a request definition by selecting one of the column entries for a specific request definition. The Request Details page will display the details for the selected user. To view all request definitions defined in the system: Click View All. To perform a new search: From the Request Search Results page, click New Search to display the Request Search page. Setting Up a New Request Definition Use the following procedures to define, modify, or delete request definitions. To set up a request definition: 1 From the Administration of processes page, click Request List Setup to display the Request Search page. 2 Click New. 3 The Create New Request page is displayed. Using Workflow Administration 153

154 OAA Platform 4 Type a name for the request definition in the Name text box. 5 Type the path for the icon in the Icon text box. 6 Click the magnifier glass next to Workflow Template to display the Lookup Workflow Template window. a Using this window, define your search criteria. b Click Search. 154 Chapter 7 Using OAA Workflow

155 Administration Guide The Lookup Workflow Template window will display a list of all workflow templates matching the search criteria. c From the list, select the workflow template to associate with the request definition. 7 Select the Show Startup Screen check box when the workflow template was created as an Embedded Data process type. See To create a workflow template: on page 101. Using Workflow Administration 155

156 OAA Platform 8 Click the magnifier glass next to Startup Script to display the Script File Lookup window. 9 Locate and select the script file you want to use. 10 To add a capability, type the capability in the Capabilities required text box. Important: The user must be assigned a role with that capability. 11 Click Submit Changes. Modifying a Request Definition Request definitions can be modified through the Request Details page. To modify a request definition: 1 To search for the request definition you want to modify, see Searching for a Request Definition on page 151 for information on using the search function. 2 Select the request definition from the Request Search Results page to display the Request Details page. The Request Details page will display the information for the selected request definition. 3 Make any changes to the request definition information. 156 Chapter 7 Using OAA Workflow

157 Administration Guide 4 Click Submit Changes to save all changes to the request definition information. Deleting a Request Definition Request definitions can be deleted from the system through the Request Details page. To delete a request definition: 1 To search for the request definition you want to delete, see Searching for a Request Definition on page 151 for information on using the search function. 2 Select the request definition from the Request Search Results page to display the Request Details page. The Request Details page will display the information for the selected request definition. 3 Click Delete. A delete confirmation message is displayed. 4 Click OK to delete the request definition from the system. Uploading JavaScript Files Javascriptfiles must be uploaded to the server before they can be assigned to a workflow process activity. Use the following procedure to upload all Javascriptfiles you want to make available for use in your workflow templates. Using Workflow Administration 157

158 OAA Platform To view uploaded Javascriptfiles: 1 From the Administration of processes page, click Upload JavaScript Files to display the List page. A list of all script files that have previously been uploaded to the server is displayed. The list contains the following columns of information about the script file: Description A description of the script file function. File Name The name of the script file. 2 To view the script file details, click any of the column entries associated with the file. 158 Chapter 7 Using OAA Workflow

159 Administration Guide To upload a new script file: 1 From the List page, click New to display the New File page. 2 Type a description of the script file in the Description text box. 3 Click the Plus icon to display the Select a File window. Using Workflow Administration 159

160 OAA Platform 4 Use the Browse button to display the Choose file window. 5 Locate and select the script file to upload. 6 Click OK. The Script File entry will display the selected file name. 7 Click New to save the new script file. 160 Chapter 7 Using OAA Workflow

161 Administration Guide The JavaScript File List page will display the new script file in the list. Updating a Script File A script file can be updated through the Update File page. Warning: Use caution when updating a script file. Changing the information may produce unwanted or unexpected results. To update a file: 1 From the JavaScript File List page, select the file you want to update. Using Workflow Administration 161

162 OAA Platform The Update File page will display. 2 Make any required changes in the Description text box. 3 If you want to add a new file attachment: a Click the Minus icon to remove the current file attachment. b Click the Plus icon to display the Select a File window and add a new file attachment. c To view the script, click the Magnifier icon. 4 Click Save to save the changes and return to the JavaScript File List page. Deleting a Script File Script files can be deleted from the system through the Update File page. Warning: Use caution when deleting a script file. Deleting a script file that is used in conjunction with a workflow may produce unwanted or unexpected results. To delete a script file: 1 From the JavaScript File List page, select the file you want to update. The Update File page will display. 162 Chapter 7 Using OAA Workflow

163 Administration Guide 2 Click Delete. A delete confirmation message box is displayed. 3 Click OK to confirm the delete and return to the JavaScript File List page. Using the Request List Accessing My Requests Request list users view their request list through the My Requests component. This chapter provides information on how to view request definitions, start a new request workflow, and view overdue requests. Use the following procedure to access My Requests. To access My Requests: 1 Log on to your Web application to display the Navigation Menu on your Home page. 2 Click the Workflows tab, or click Workflow on the Navigation Menu. The Workflow menu will display in the left pane and the My Messages page will display in the right pane. 3 In the left pane menu, click My Requests to display the My Requests page. Using the Request List 163

164 OAA Platform Viewing Request Details Use the following procedure to view the details of a request. To view the request details: Click any of the column entries for a request definition to display the request details page. The General tab will display the general information about the request, the request description, and the request process history. The Workflows tab will display the workflow template used for this process instance. 164 Chapter 7 Using OAA Workflow