System Administrator Manual

Transcription

1 NOTE: This excerpt from the Probaris SP manual was created with the permission of Probaris Technologies, Inc. to be used as a work sample for the author, Tom Wrona. System Administrator Manual April 2005 Easy to Deploy Compliance and Process Security

2 Documentation and Online Help by Tom Wrona Probaris SP Version 1.7 Probaris SP System Administrator Manual 1.7B Copyright Probaris Technologies, Inc., All rights reserved. This document is proprietary to Probaris Technologies, Inc. It is protected by copyright laws in the US and abroad, and is licensed for use by customers only for the purpose of evaluating Probaris SP. Probaris Technologies, Inc. 718 Arch Street Suite 300 S. Philadelphia, PA Telephone: (215) Probaris is a registered trademark of Probaris Technologies, Inc.

3 Table of Contents What is Probaris SP?...1 People Who Work With Probaris SP... 2 SP System Administrator... 2 SP Form Designer... 2 SP Forms Administrator... 2 Forms Central Administrator... 2 End User... 2 Text Conventions Used in This Manual... 3 Anatomy of the System...4 How End Users See The System... 4 Hardware and Software... 4 Software... 6 Installation...8 Overview... 8 Installation Step-by-Step Download required software components Install the Java SDKs Install and configure the Application and HTTP servers Install HTMLDoc Install the MultipartRequest Java Library Install DBConnectionBroker Java Library Install Sun s Java Web Services Developer Pack (JWSDP) Install Sun s JAXM Java Library Install the JDBC driver Install Forms Central s Database Probaris Technologies Page - i -

4 11. Install and configure Forms Central Install SP s Database Install and configure SP Install Signature Server s Database Install and configure Signature Server Forms Central Configuration... FormsCentralSetup Servlet Configuration Parameters... Forms Central Mode Configuration... SP Configuration... The web.xml File... InitializationServlet Servlet Configuration Parameters... Configuring SP s Interfaces... The global.properties File... The dao_config.xml File... The schedule.xml File... Signature Server Configuration... Startup Servlet Configuration Parameters... Admin Servlet Configuration Parameters... Key Concepts... Custom User Profile Properties... Robot Users... Plug-ins... Overview... Authentication Modalities... Routing Behaviors... Routing/Finalization Triggers... Property Validation... Probaris Technologies Page - ii -

5 Enrollment/Registration... Operating The System... Command Line Utilities... Provision Manager... How to Create a New User With a Default Profile... How to Set or Change a User s Authentication Credentials... How to Create a New User Role With Default Privleges... Managing User Accounts with the Graphical User Interface Overview How to Add a User Account How to Find a User Account How to Edit a User Account How to Edit a User s Profile How to Change a User s Authentication Modality Robot Users System Management with the Graphical User Interface... How to Add a Role... How to Edit a Role... How to Manage Form Tracker... How to Add a Custom Property... How to Edit a Custom Property... Appendix 1: The Standard Plug-ins... Default Routing Behavior... Overview... Configuration... Explicit Routing Behavior... Overview... Probaris Technologies Page - iii -

6 Configuration... Password Authentication... Overview... Configuration... X.509 Certificate Authentication... Overview... Configuration... OneOf Validator... Overview... Configuration... Integer Validator... Overview... Configuration... Regular Expression Validator... Overview... Configuration... X.509 Certificate Enrollment... Overview... Configuration... Probaris Technologies Page - iv -

7 What is Probaris SP? Probaris Technologies Secure Process (SP) is an electronic forms application that supports a flexible workflow model within a highly secure, audited system. Probaris SP s electronic routable forms save time and money and increase the accuracy and security of the many forms any large organization must process. Process in this case refers to the entire life cycle of a form. The creation of the blank form (called a template) and the processing of each instance of the form from its origination, to the routing of it to the (sometimes many) people who must enter information and/or approve it, to its final disposition. SP supplies extensive support for real world business processes, like optional routing, withdrawing forms, copying forms to other users and data masking. A full audit trail is maintained, preserving the full transaction history of every form. In addition, SP maintains a full version history of every form so earlier versions of a form can be viewed. SP is a web-based application; all functionality is available using a web browser (Microsoft Internet Explorer 5.5 or later). SP s form repository, Forms Central is also web-based. It permits users to search for and find forms in any file format. So in addition to SP routable electronic forms, Forms Central can also contain forms in PDF and MS Word format. A glossary is usually located at the end of a manual but by the time you get to it you ve already figured out the jargon the hard way. Here are the key terms in the Probaris SP lexicon. Editor Instance Originate Robot User Routing Section A Probaris SP user who is responsible for filling in a form section. One electronic copy of a form, which, in the normal course of events, will be filled-in by one or more users, approved and filed. To create a new instance of a form. An SP function that permits a form to be routed to a pool of users with identical roles. The robot user can assign each incoming form to users in the pool randomly or in a predetermined sequence. The sending of a form instance to the next authorized user in its lifecycle. Every form has two or more sections. Each section is completed by one editor. The two required sections are the Origination section (filled-in by the editor who originates the form) and the Final section (filled-in by the editor who finalizes the form). Probaris Technologies Page - 1 -

8 SP Form SP Tags Template An electronic form that has built-in logic that models the routing a paper version would take. An SP Form also has security features like electronic signature capability and a complete audit trail. HTML-like tags used in the creation of SP forms. The system comes with a plug-in for Macromedia Dreamweaver to make applying SP tags easy. A blank electronic form. People Who Work With Probaris SP Every computer system has its own way of looking at the world and its own language for describing the people who interact with it. Every UNIX system, for example, has a UNIX system administrator, even though the person who fulfills that role may go by the actual job title of technical lead, help desk manager or even vice president of engineering or CEO in a small company. Probaris is no exception. Here is the Probariscentric view of the people who work with it, starting with you, the SP System Administrator: SP System Administrator Installs, configures and maintains SP and required components (e.g., Solaris, Oracle, Apache and so on.). Other people who interact with the system: SP Form Designer Designs and tests SP forms and XML guide documents. Works closely with and may also play role of SP Forms Administrator. SP Forms Administrator Analyzes operations to model workflow and form routing in SP. Works closely with and may also play role of SP Form Designer. Deploys forms. Forms Central Administrator Manages Forms Central, the intranet website that serves as a repository for all SP form templates. End User Originates, routes, signs, finalizes forms. Sends templates (blank forms) to other users. Also called an editor. Probaris Technologies Page - 2 -

9 Text Conventions Used in This Manual Text that looks like this is a code sample: <init-param> <param-name>dbpassword</param-name> <param-value>(password)</param-value> </init-param> Variables are shown italicized and in parentheses to indicate that they should be replaced with the appropriate text. Optional parameters are shown in square brackets: jdbc:oracle:thin:@(server name)[:port]:(database name) The code style is also used to identify filenames and the names of variables: The web.xml file contains parameters that configure SP s application context. Probaris Technologies Page - 3 -

10 Anatomy of the System How End Users See The System End users work with Probaris SP through a browser-based GUI. The user s home page comprises several tabbed folders. To understand the system from the end user s perspective be sure to read the SP Online Help. You can access it by logging in to the system as an end user and clicking on any question mark icon in the UI. System Administrators work with a GUI that is identical except for the addition of a couple of buttons for accessing system tools. Some sysadmin tasks are performed at the Solaris command line. Hardware and Software The system runs on any hardware platform that supports the Java2 SDK version 1.4.x. The size and power of a machine running SP and its supporting applications depends on the number of users and the forms they interact with. The following figure depicts the SP system architecture at the server level. There can be any number of web servers, added as needed for scalability or redundancy. Probaris Technologies Page - 4 -

11 Probaris Technologies Page - 5 -

12 Software The system requires the following software packages: Any operating system capable of hosting the Java2 SDK version 1.4.x o Solaris 8.1 or 9 o Red Hat Linux 9 o Microsoft Windows 2000 Server HTTP Server o Apache HTTP server Version 2.0.x Requires JK Apache-to-Tomcat connector (if using Apache Tomcat) Application Server/Servlet Container o Apache Tomcat 4.1.x Java 2 SDK version HTMLDoc document conversion utility (Configure it for SSL support before compiling.) MultipartRequest 1.30b4 Java library DBConnection Broker Java library (This is required only for Forms Central and Signature Server, not SP itself.) Sun Java Web Services Developer Pack (JWSDP) version 1.3 (This is required only for Forms Central.) Sun JAXM Java Library A supported database o Oracle 9i DBMS JDBC driver must be version or later. o MySQL 4.0.x Probaris SP (SP) Proprietary java classes to support forms, routing, etc. Probaris Technologies Page - 6 -

13 Probaris Forms Central (FC) Proprietary java classes to support form repository. Probaris Signature Server (SS) Proprietary java classes to support visual representation of digital signatures. Probaris Technologies Page - 7 -

14 Installation Overview As with all installations, it s a good idea to read through all of the instructions before beginning the actual installation. Step-by-step installation instructions follow this summary. NOTE: These instructions assume you are also installing Forms Central and Signature Server. If you are not you can simply skip references to these products. NOTE: All hyphens in source code should be typed. When a source code line is continued to the next line the standard line continuation character ( \ ) is used. 1. Download the required software components. 2. Install the Java SDKs. 3. Install and configure the Application and HTTP servers. 4. Install HTMLDoc. 5. Install MultipartRequest. 6. Install DbconnectionBroker. 7. Install Sun JWSDP. 8. Install Sun JAXM. 9. Install the JDBC driver. 10. Install Forms Central s Database. 11. Install and configure Forms Central. 12. Install SP s Database. 13. Install and configure SP. 14. Install Signature Server s database. 15. Install and configure Signature Server. Probaris Technologies Page - 8 -

15 Installation Step-by-Step 1. Download required software components. In all cases you should download the exact version number of the component listed. Using other software versions may cause system instability. 2. Install the Java SDKs. If the required Java2 SDK is not already installed, you must follow the directions for installing the appropriate SDK according to the package you downloaded. For example on a 32-bit platform, you will need to only unpackage and install a single installation package where on some 64-bit architectures, you will need to unpack and install the 32-bit package as well as a 64-bit add-on package. When complete, make sure the JAVA_HOME environment variable is set appropriately for your operating system. 3. Install and configure the Application and HTTP servers. If appropriate application and HTTP servers are not already installed, you must follow the directions for installing supported servers as indicated by the distribution you chose to install. Be sure to note any external port numbers. For example the standard HTTP port is 80 and the standard HTTPS port is Install HTMLDoc. Unpack the HTMLDoc distribution and follow the directions. Be sure to include SSL support before compiling. 5. Install the MultipartRequest Java Library. Unpack the MultipartRequest distribution files, then copy the MultipartRequest JAR to some location within the application server s classpath. This JAR does not need to exist within a privileged classpath. 6. Install DBConnectionBroker Java Library. Unpack the DBConnectionBroker distribution files, then copy the DBConnectionBroker JAR to some location within the application server s classpath. This JAR does not need to exist within a privileged classpath. Probaris Technologies Page - 9 -

16 7. Install Sun s Java Web Services Developer Pack (JWSDP). Unpack the JWSDP distribution and then execute the installer. After the installer is finished some of the JARs need to be copied to the application server s privileged classpath while other need to be copied to a non-privileged classpath. Endorsed Classpath <JWSDP_HOME>/jaxp/lib/endorsed/dom.jar <JWSDP_HOME>/jaxp/lib/endorsed/sax.jar <JWSDP_HOME>/jaxp/lib/endorsed/xalan.jar <JWSDP_HOME>/jaxp/lib/endorsed/xercesImpl.jar <JWSDP_HOME>/jaxp/lib/endorsed/xsltc.jar Privileged Classpath <JWSDP_HOME>/jaxp/lib/jaxp-api.jar <JWSDP_HOME>/jaxrpc/lib/jaxrpc-api.jar <JWSDP_HOME>/jaxrpc/lib/jaxrpc-spi.jar <JWSDP_HOME>/jaxrpc/lib/jaxrpc-impl.jar <JWSDP_HOME>/jwsdp-shared/lib/activation.jar <JWSDP_HOME>/jwsdp-shared/lib/jta-spec1_0_1.jar <JWSDP_HOME>/jwsdp-shared/lib/namespace.jar <JWSDP_HOME>/jwsdp-shared/lib/jaas.jar <JWSDP_HOME>/jwsdp-shared/lib/jax-qname.jar <JWSDP_HOME>/jwsdp-shared/lib/xsdlib.jar <JWSDP_HOME>/saaj/lib/saaj-api.jar <JWSDP_HOME>/saaj/lib/saaj-impl.jar Shared Classpath <JWSDP_HOME>/jwsdp-shared/lib/commons-beanutils.jar <JWSDP_HOME>/jwsdp-shared/lib/commons-logging.jar <JWSDP_HOME>/jwsdp-shared/lib/relaxngDatatype.jar <JWSDP_HOME>/jwsdp-shared/lib/commons-digester.jar 8. Install Sun s JAXM Java Library. Unpackage the JAXM distribution files, then copy the JAXM JARs to some location within the application server s privileged classpath. The following JARs will be needed: jaxm-api.jar jaxm-runtime.jar Probaris Technologies Page

17 9. Install the JDBC driver. The JDBC driver must be installed in the application server s privileged class path. Example JDBC Drivers: Oracle: ojdbc14.jar MySQL: mysql-connector-java stable-bin.jar 10. Install Forms Central s Database. Forms Central can use either an Oracle 9i or MySQL 4.0.x database. Installation scripts for each have been provided in the Forms Central distribution. Follow database-specific installation routines to prepare for and create the Forms Central database. 11. Install and configure Forms Central. 1. Uncompress the distribution files. (java_home)/bin/jar -xf fc_distribution.jar 2. Create or Edit the deployment properties file a) Copy the default deployment properties file from (fc_dist_home)/resources/deploy/default_deploy.properties to (fc_dist_home)/resources/deploy/deploy.properties b) Edit (fc_dist_home)/resources/deploy/deploy.properties 3. Execute the deployment ant script (ant_home)/bin/ant [-Ddeploy.dir=(deploy-dir)] [- \ Dproperties.file=(properties-file)] deploy deploy-dir is the relative or absolute path to the directory in which to deploy the Forms Central application. If this value is set to /var/tomcat4/webapps/formscentral, then a) /var/tomcat4/webapps/formscentral will be created if it doesn t exist. b) Forms Central application files will be copied to /var/tomcat4/webapps/formscentral Probaris Technologies Page

18 If this value is not set, the default deployment location is../deploy This default value is set in the relevant build.properties file. (properties-file) is the relative or absolute path to the deployment properties file. This properties file contain values used to generate the Forms Central configuration files. If this value is not set, the default deployment properties file location is: (fc_dist_home)/resources/deploy/deploy.properties 4. Verify the installation. a) Check the web.xml file (fc_deploy_home)/web-inf/web.xml 5. Create the custom disclaimer file (optional). If desired (and set in the web.xml file), a custom disclaimer may be declared. (See The web.xml File section.) The disclaimer is boilerplate text that appears at the bottom of all SP pages. It can contain a privacy statement or other necessary information. 6. Configure the application server to load Forms Central. Tomcat 4.x: Copy and edit the context descriptor file. a) Copy (fc_dist_home)/resources/deploy/formscentral.xml to (tomcat_home)/webapps/formscentral.xml b) Edit (tomcat_home)/webapps/formscentral.xml. i. Set the Context element's path attribute appropriately. ii. Set the Context element's docbase attribute appropriately. iii. Set the Logger element's prefix attribute appropriately. (Appropriately means relative to the webapps directory or an absolute path to the application s deployment directory.) Probaris Technologies Page

19 12. Install SP s Database. SP can use either an Oracle 9i or MySQL 4.0.x database. Installation scripts for each have been provided in the SP distribution. Follow database-specific installation routines to prepare for and create the SP database. 13. Install and configure SP. 1. Uncompress the distribution files. (java_home)/bin/jar -xf sp_distribution.jar 2. Create or edit the deployment properties file. 3. Copy the default deployment properties file from (sp_dist_home)/resources/deploy/default_deploy.properties to (sp_dist_home)/resources/deploy/deploy.properties 4. Edit (sp_dist_home)/resources/deploy/deploy.properties. 5. Execute the deployment ant script. (ant_home)/bin/ant [-Ddeploy.dir=(deploy-dir)] [- \ Dproperties.file=(properties-file)] deploy (deploy-dir) is the relative or absolute path to the directory in which to deploy the SP application. If (deploy-dir) is set to /var/tomcat4/webapps/sp, the following will happen: /var/tomcat4/webapps/sp will be created if it doesn't exist. SP application files will be copied to /var/tomcat4/webapps/sp If this value is not set, the default deployment location is../deploy. This default value is set in the relevant build.properties file. (properties-file) is the relative or absolute path to the deployment properties file. This properties file contains values used to generate the SP configuration files. If this value is not set, the default deployment properties file location is (sp_dist_home)/resources/deploy/deploy.properties Probaris Technologies Page

20 6. Verify the installation a) Check the web.xml file to ensure that all variables (e.g., $DisclaimerURL) have been replaced. (sp_deploy_home)/web-inf/web.xml b) Check the global application properties file (sp_deploy_home)/web-inf/config/global.properties c) Check the database access configuration file (sp_deploy_home)/web-inf/config/dao_config.xml d) Check the scheduler configuration file. (sp_deploy_home)>/web-inf/config/scheduler.xml 7. Create the custom disclaimer file (optional) If desired (and set in the web.xml file), a custom disclaimer may be declared. 8. Configure the application server to load SP Tomcat 4.x: Copy and edit the context descriptor file. a) Copy (sp_dist_home)/resources/deploy/sp.xml to (tomcat_home)/webapps/sp.xml. b) Edit (tomcat_home)/webapps/sp.xml. i. Set the Context element's "path" attribute appropriately ii. Set the Context element's "docbase" attribute appropriately iii. Set the Logger element's "prefix" attribute appropriately 9. Configure SP using the information from the SP Configuration section of this document. 14. Install Signature Server s Database. Signature Server can use either an Oracle 9i or MySQL 4.0.x database. Installation scripts for each have been provided in the Signature Server distribution. Follow data- Probaris Technologies Page

21 base-specific installation routines to prepare for and create the Signature Server database. 15. Install and configure Signature Server. Using various deployment tools, the Signature Server WAR file may be uncompressed and installed into the application server. See your application server s manual for instruction on deploying web applications. After Signature Server as been deployed, it must be properly configured. To do this, the application context s web.xml file must be edited. It is located in the following path: (application context root)/web-inf/web.xml For Example: (tomcat_home)/webapps/signatureserver/web-inf/web.xml Configure Signature Server using the information from the Signature Server Configuration section of this document. Note: This excerpt now jumps to the Managing User Accounts section which starts on page 64 of the manual. Probaris Technologies Page

22 Managing User Accounts with the Graphical User Interface Overview Many common system administration tasks can be performed from the SP GUI. Those tasks can t be must be performed from the command line interface (either interactively or via shell scripts). NOTE: You should always use the Back button embedded in a page to back up one page. Don t use the browser s Back button. As a System Administrator you ll see a couple of extra buttons when you log in to Probaris SP from your Web browser. End User Button Bar System Administrator Button Bar Here are what the additional buttons are used for: Allows you to add and delete forms from the Forms Central database and change form properties. This button is also available to users who are Forms Administrators. For more information on form management see the Probaris SP Form Designer Manual. User Management is where you add, edit and delete user accounts. This button is also available to users who are User Administrators. Probaris Technologies Page

23 This button opens the System Management page, from which you can perform system management tasks like managing roles, Form Tracker and custom properties. The System Management page also contains a link that opens a page that displays SP system properties. Use this button to manage robot user accounts. This button is also available to users who are User Administrators. The following sections describe how to perform the system administrator tasks that can be performed from the GUI. How to Add a User Account 1. Click the Manage Users button. The User Management page opens. 2. Click the Add New User button. Probaris Technologies Page

24 The Add New User page opens. 3. Enter the user s information. For an explanation of the fields see below. 4. Click the Submit button. After you ve entered the user s first name, last name and address, enter information for these fields: Type Role Status All human users are of type Normal. A Robot User is an account that can accept routed sections and distribute them to a pool of users with identical responsibilities. For more on robot users see Managing Robot Users. Roles define what a user is permitted to do. For example, the role Contractor might not be permitted to originate certain forms, like a vacation request. Roles are defined using the Manage Roles function, which is accessed from System Management page. In order to be routed form sections, a user must be routable. Most users are both Active and Routable. Inactive and Terminated users cannot be routable. For maximum flexibility, both Active and On Leave users can be routable or not routable. Your organization s policies and procedures will dictate how you use this feature. Probaris Technologies Page

25 Administrative Privileges These are the types of administrator accounts and what each account type can do. Master Administrator Can do everything a system administrator can do plus create system administrator accounts. System Administrator Has full system privileges except creating master system administrator and system administrator accounts. User Administrator Can add and modify users including robot users. Can t upgrade account privileges. Can t add forms. Forms Administrator Can add and modify form templates. How to Find a User Account You can find an individual user account or all user accounts which meet criteria you specify using the Search panel at the top of the User Management page. The search text fields don t support the? and * wildcard characters. How to Edit a User Account To edit a user account first find the account using the Search User panel. Once you have found the account it s displayed in the main listing panel. 1. Click on the user s first or last name. The User Details page opens. Probaris Technologies Page

26 2. Click the Edit User Details button at the bottom of the page. The Edit User page opens. 3. Change the information as required. Probaris Technologies Page

27 An alias is an alternative address. In this example if Tom Wrona was the company s vice president you might want to create the alias vp@probaris.com. So Wrona would receive forms routed to both twrona@probaris.com and vp@probaris.com 4. Click the Update button. How to Edit a User s Profile The User Profile contains the parameters that define a number of user privileges and other characteristics. Here s how you can edit them 1. Open the User Details page as described in the How to Edit a User Account above. 2. Click the Edit User Profile button at the bottom of the page. The Edit User Profile page opens. 3. To change a profile property click the pencil icon to the right of it. For example you can change the user s time zone. Other parameters may be altered by typing in a text box, clicking a radio button and so on. Probaris Technologies Page

28 How to Change a User s Authentication Modality 1. Open the User Details page as described in the How to Edit a User Account above. 2. Click the Edit Authentication button at the bottom of the page. 3. The Configure User Authentication Modality page opens. 4. To change the user s authentication method select the method from the drop down list and click the Change button. 5. Click the Back button. To simply change the user s password click the Modify button and enter the new password in Modify Password page. Robot Users As the system administrator you will not be managing robot users. You just add them as you would any other user. (They re type Robot instead of Normal. ) Robot users are managed by end users, who usually have supervisory responsibilities. However, it s important that you understand the concept. Probaris Technologies Page

29 A robot user is an account that can distribute routed forms among a pool of end users. For example, vacation requests, changes to pension plans and other personnel forms might be routed to the human resources department at the address hr@agency.gov. Perhaps there are ten people in HR who can handle these kinds of forms. The address hr@agency.gov is a robot user account. Periodically a supervisor in HR logs in to the hr@agency.gov account and uses the transfer command to route incoming forms to the people in HR who can process them. In the current release the robot user does not automatically transfer forms. A human user who knows which forms to transfer to which users must login and do the transfers manually. Note that we use the term transfer and not route. Routing would imply the robot user filled in a form section and, if necessary, signed it. The robot user does neither of these things; it just acts like a middleman, transferring form sections from one human user to another. If you have robot users to manage you have a Manage Robot Users button on your Probaris SP home page. To manage a robot user means to check the account s Action Items folder and transfer each form in it to an authorized user. Here s how it works. 1. Log in as you normally would. 2. Click the Manage Robot Users button. The Robot User Management page opens. Probaris Technologies Page

30 In this example rlevas bot is a robot user. 3. Click on the name of the robot user you want to manage. The robot user s home page opens. Note the legend at the top of the page that identifies the robot user you re managing and that the little robot icon now sports an X. You ll click him again to exit. 4. Open the form and transfer it to the appropriate user. From here you use the UI exactly as if you were working in your regular Action Items folder. However, Route is missing from the Form Actions menu. When you re wearing your robot user hat you can only transfer, never route. For information on how end users work with Probaris SP see the online help. 5. When you re done working as a robot user manager click the Robot button and confirm that want to exit. You ll be returned to your regular home page. Probaris Technologies Page