<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more contributor
license agreements.  See the NOTICE.txt file distributed with this work for
additional information regarding copyright ownership.  The ASF licenses this
file to you under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License.  You may obtain a copy of
the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
License for the specific language governing permissions and limitations under
the License.
-->
<document>
   <properties>
      <title>CAS Workflow Manager User Guide</title>
      <author email="Chris.Mattmann@jpl.nasa.gov">Chris Mattmann</author>
      <author email="woollard@jpl.nasa.gov">Dave Woollard</author>
   </properties>

   <body>
   
      <div class="warning">This document is in the process of being reorganized as
      part of our ongoing documentation effort. Please check back for updates.</div>
      
      <section name="Introduction">
      
      <p>This document serves as a basic user's guide for the CAS Workflow Manager 
      project. The goal of the document is to allow users to check out, build, and 
      install a base version of the CAS Workflow Manager, as well as perform basic 
      configuration tasks. For advanced topics, such as configuring the Workflow 
      Manager to Scale and other tips and tricks, please see our 
      <a href="../user/advanced.html">Advanced Guide.</a></p>
      
      <p>The remainder of this guide is separated into the following sections:</p>
      <ul>
        <li><a href="#section1">Download and Build</a></li>
        <li><a href="#section2">Configuration in 2 Minutes or Less</a></li>
        <li><a href="#section3">Learn By Example</a></li>
      </ul>  
      </section> 
     
      <a name="section1"/>
      <section name="Download and Build">
        <p>The most recent CAS-Workflow Manager project can be downloaded from the Apache OODT
        <a href="/">website</a> or it can be checked out 
        from the OODT repository using Subversion. The CAS-Workflow Manager project is 
        located at <code>../../workflow/</code>. We recommend checking
        out the latest released version (v1.5.1 at the time of writing).</p>
      
        <p>Maven is the build management system used for OODT projects. We currently 
        support Maven 2.0 and later. For more information on Maven, see our 
        <a href="../development/maven.html">Maven Guide.</a></p>
      
        <p>Assuming a *nix-like environment, with both Maven and Subversion 
        clients installed and on your path, an example of the checkout and 
        build process is presented below:</p>
        
         <source>
> mkdir /usr/local/src
> cd /usr/local/src
> svn checkout https://svn.apache.org/repos/asf/oodt/trunk/workflow workflow
      </source>
        
      <p>After the Subversion command completes, you will have the source
      for the CAS-Workflow project in the <code>/usr/local/src/workflow</code>
      directory.</p>
      
      <p>In order to build the project from this source, issue the following 
      commands:</p>
      
      <source>
> cd /usr/local/src/workflow
> mvn package    
      </source>   
      
      <p>Note that this command performs a number of tasks, including performing
      unit tests which can take a long time depending on your system. At the end of 
      the process, you will see a Maven success banner.</p>
      
      <p>Once the Maven command completes successfully, you should have a 
      <code>target</code> directory under <code>-workflow</code>. 
      The project has been built in this directory as a distribution tar ball.
      In order to move the built project out of the source directory and unpack the
      tar ball, issue the following commands:</p>
      
      <source>
> cd /usr/local
> mv src/workflow/trunk/cas-workflow-vX.Y.Z-dist.tar.gz ./
> tar -xvzf cas-workflow-vX.Y.Z-dist.tar.gz
> export WORKFLOW_HOME=/usr/local/cas-workflow-vX.Y.Z
      </source>       
      
      <p>The resultant directory layout from the unpacked tarball is as follows:</p>
           
      <source>
bin/ etc/ logs/ doc/ lib/ policy/ LICENSE.txt CHANGES.txt
      </source>
      
      <p>A basic description of the files and subdirectories of the deployment is 
      presented below:</p>
      <ul>
         <li><strong>bin</strong> - contains scripts for running the Workflow Manager, 
         including the "wmgr" server script, and the "wmgr-client" client script.</li>
         
         <li><strong>etc</strong> - contains the logging.properties file for the 
         Workflow Manager, and the workflow.properties file used to configure the server 
         options.</li>
         
         <li><strong>logs</strong> - the default directory into which log files are 
         written.</li>
              
         <li><strong>doc</strong> - contains Javadoc documentation, and user guides 
         for using the Workflow Manager.</li>
         
         <li><strong>lib</strong> - the required Java jar files to run the Workflow 
         Manager.</li>
         
         <li><strong>policy</strong> - the default XML-based element and product type 
         policy in case the user is using the Lucene Workflow Instance Repository and/or 
         the XML Workflow Repository, along with the ThreadPoolWorkflowEngine.</li>
         
         <li><strong>CHANGES.txt</strong> - contains the CHANGES present in this 
         released version of the Workflow Manager.</li>
         
         <li><strong>LICENSE.txt</strong> - the LICENSE for the Workflow Manager 
         project.</li>
       </ul>
      
      <p>Now you have a built Workflow Manager at <code>/usr/local/cas-workflow-vX.Y.Z</code>.
      In the next section, we will discuss how you can configure the Workflow Manager for
      basic operations.</p>
      </section>
      
      <a name="section2"/>
      <section name="Configuration in 2 Minutes or Less">
      
      <p>The reason for entitling this section "in 2 Minutes or Less" is to show that
      in it's base deployment, with very minimal configuration, we can have the Workflow
      Manager in a usable state, capable of managing workflow tasks to completion. For 
      the record, I haven't timed it, but its pretty fast...</p>
      
      <p>We are going to set up the Workflow Manager to use the XML-based Workflow 
      Repository, the ThreadPoolWorkflowEngine, and Lucene Workflow Instance Repository 
      extension points. The first step is to edit the wmgr script in 
      <code>$WORKFLOW_HOME/bin</code>. Make the following 
      changes:</p>
     
       <ul>
         <li>Set the <code>SERVER_PORT</code> variable to the desired port on which 
         you'd like to run the Workflow Manager. Our default port is 9001.</li>
         
         <li>Set the <code>JAVA_HOME</code> variable to point to the location of your 
         installed JRE runtime. If you do not know where this is, type <code>&gt; which 
         java</code> and use that path.</li>
         
         <li>Set the <code>RUN_HOME</code> variable to point to the location to which
         you'd like the Workflow Manager PID file written. Typically this should default to 
         <code>/var/run</code>, but not all system administrators allow users to write 
         to <code>/var/run</code>.</li>
       </ul>
       
       <p>The second step in configuration is to edit 
       <code>$WORKFLOW_HOME/bin/wmgr-client</code> script, making the following 
       change:</p>
       
       <ul>
          <li>Set the <code>JAVA_HOME</code> variable to point to the location of 
          your installed JRE runtime.</li>
       </ul>
       
       <p>In the third step of this configuration, you will set the Workflow Manager's
       various extension points. For more information about the functionality of
       these extension points, see our 
       <a href="../development/developer.html">Developer Guide.</a> By default, 
       the Workflow Manager is built to use the XML-based Workflow Repository, the 
       ThreadPoolWorkflowEngine, and <a href="http://lucene.apache.org/">Lucene</a> 
       Workflow Instance Repository extension points.</p> 
       
       <p>Make the following changes to 
       <code>$WORKFLOW_HOME/etc/workflow.properties</code>:</p>
       
       <ul>     
         <li>Specify the path to the directory where the Workflow Manager will create the
         Lucene index and associated files by setting the 
         <code>org.apache.oodt.cas.workflow.instanceRep.lucene.idxPath</code> property
         to <code>$WORKFLOW_HOME/repo</code>. Make sure that this directory does
         NOT exist the time you run the Workflow Manager. If the Workflow Manager does 
         not find a directory at thie specified location, it will create all of the 
         necessary directory structure and ancillary files.</li>
         
         <li>Specify the path to the directory where the XML policy files are stored 
         for the the XML Workflow Repository. This path is set by 
         <code>org.apache.oodt.cas.workflow.repo.dirs</code>. The 
         default location (and default policy files) are located at 
         <code>$WORKFLOW_HOME/policy</code> in the vanilla deployment of the Workflow Manager.
         Note that these properties need to be fully specified URLs (e.g., they should 
         start with <code>file://</code>).</li>
       </ul>

       <div class="info">Optionally, you can change the default logging properties for
       the CAS Workflow Manager. This is done by editing 
       <code>$WORKFLOW_HOME/etc/logging.properties</code>. We have tried to select sensible
       defaults for the average user, but if you would like more or less information 
       generated in the Workflow Manager logs, you can edit the levels of different catagories
       of information in this proporties file. The following logging levels are available:
       <code>INFO</code>, <code>WARNING</code>, <code>FINE</code>, <code>FINER</code>,
       <code>FINEST</code>, and <code>ALL</code>.</div>
   
      <p>With this last step, you have configured the Workflow Manager. In order to test your 
      configuration, cd to <code>$WORKFLOW_HOME/bin</code> and type:</p>
       
      <source>
> ./wmgr start
      </source> 
       
      <p>This will startup the workflow manager XML-RPC server interface. Your Workflow Manager 
      is now ready to run! You can test out the workflow manager by running a command that 
      will execute our preconfigured hello world workflow.</p>

      <p>Run the below command, assuming that you started the Workflow Manager on the default 
      port of 9001:</p>
      
      <source>
> ./wmgr-client --url http://localhost:9001 --operation \
                              --sendEvent \
                              --eventName test 
      </source> 
      
      <p>You should see a variety of info messages, in including the following:</p>
      
      <source>
INFO: WorkflowManager: Received event: test
INFO: WorkflowManager: Workflow testWorkflow retrieved for event test
INFO: Task: [Hello World] has no required metadata fields
INFO: Executing task: [Hello World] locally
Hello World: Chris
INFO: Task: [Goodbye World] has no required metadata fields
INFO: Executing task: [Goodbye World] locally
 Goodbye World: Chris            
      </source>
      
      <p>Note that we have elided some of the timestamp information for the purposes of 
      clarity. If you see the cannonical Hello World statement, you have succeeded in 
      configuring the CAS Workflow Manager, hopefully in 2 minutes or less (and even if 
      it took a little more time, you have to admit it was by and large painless).</p>
      
      </section>
      
      <a name="section3"/>
      <section name="Learn By Example">
      <p>Coming Soon...</p>
      </section>
      
      <section name="Conclusion">
      
      <p>In this Basic User Guide, we have covered a number of topics, including Workflow 
      Manager installation, configuration, and a basic example of use. For more advanced 
      topics, including the use of alternative queuing strategies and best practices for 
      addressinbg scaling issues, see our 
      <a href="../user/advanced.html">Advanced Guide.</a></p>
      
      </section>
   </body>
   
</document>
