<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<chapter id="admin">
  <title>Administration</title>   
       
       <section>
       		<title>Overview</title>

       		<para> 
       		This section describes the administration capabilities associated with RiftSaw.
       		</para>
       		
       </section>
       
       <section>
       		<title>BPEL Console</title>

	       <section>
	       		<title>Overview</title>
	       		<para> 
	       		This section provides an overview of the BPEL Console.
	       		The console provides the ability to view:
	       		</para>
	       		
	       		<itemizedlist>
	       			<listitem>
	       			The process definitions deployed to the BPEL engine
	       			</listitem>
	       			<listitem>
	       			The process instances executing in the BPEL engine
	       			</listitem>
	       		</itemizedlist>
	       		
	       </section>
	       
	       <section>
	       		<title>Logging in</title>
	       		
	 			<para>
	 			The BPEL console can be located using the URL: 
	 			<ulink url="http://localhost:8080/bpel-console">http://localhost:8080/bpel-console</ulink>.
	 			</para>
	 			
	 			<para>
	 			The first screen that is presented is the login screen:
	 			</para>
	 			
				<imageobject>
					<imagedata fileref="images/BPELConsole-login.png" align="center" width="6in" />
				</imageobject>		
				
				<para>
				The default username is <emphasis>admin</emphasis> with password
				<emphasis>password</emphasis>.
				</para>
				
				<para>
				The Access Control mechanism used by the admin console is configured
				in the <filename>$deployFolder/bpel-console/bpel-identity.sar/META-INF/jboss-service.xml</filename>.
				The JAAS login module is initially set to use a property file based
				access mechanism, but can be replaced to use any appropriate alternative
				implementation.
				</para>
				
				<para>
				The users for the default mechanism are configured in the property file
				<filename>$deployFolder/bpel-console/bpel-identity.sar/bpel-users.properties</filename>.
				The entries in this file represent <emphasis>username=password</emphasis>.
				</para>
				
				<para>
				The user roles for the default mechanism are configured in the property file
				<filename>$deployFolder/bpel-console/bpel-identity.sar/bpel-roles.properties</filename>.
				The entries in this file represent <emphasis>username=role</emphasis>. The 
				only role of interest currently is <emphasis>administrator</emphasis>.	
				</para>
	       </section>
	       
	       <section>
	       		<title>Deployed Process Definitions</title>
	       		
	       		<para>
	       		Once logged in, the 'Process Overview' tab shows the currently deployed
	       		BPEL processes and their versions.
	       		</para>
	       		
				<imageobject>
					<imagedata fileref="images/BPELConsole-processes.png" align="center" width="6in" />
				</imageobject>			
				
	      </section>
	
			<section>
				<title>Process Instances</title>
	
	       		<para>
	       		When a process definition is selected, the list of active process instances for
	       		that process definition (and version) will be displayed in the right hand
	       		panel.
	       		</para>
	       		
				<imageobject>
					<imagedata fileref="images/BPELConsole-process-instances.png" align="center" width="6in" />
				</imageobject>			
	
	       		<para>
	       		When a process instance is selected, its details will be displayed in the lower
	       		<emphasis>Execution Details</emphasis>
	       		window. The <emphasis>Instance Data</emphasis> button will also become enabled, allowing
	       		further detail about the process to be displayed.
	       		</para>
	
				<imageobject>
					<imagedata fileref="images/BPELConsole-process-instance-data.png" align="center" width="6in" />
				</imageobject>			
	
			</section>
			
			<section>
				<title>Retiring and Reactivating Process Definitions</title>
				
				<para>
				When a process definition is initially deployed (i.e. the first version of the process),
				it automatically becomes the active process definition. If that BPEL process definition
				is subsequently change and redeployed, then the previous version is <emphasis>retired</emphasis>,
				and the new version becomes the <emphasis>active</emphasis> version.
				</para>
				
				<para>
				The only difference between an <emphasis>active</emphasis> and <emphasis>retired</emphasis>
				process definition is that a <emphasis>retired</emphasis> process definition can no longer
				create new process instances. However if there are current process instances associated
				with the <emphasis>retired</emphasis> process definition version, then these will continue
				to execute.
				</para>
				
				<para>
				On some occasions, the administrator may wish to change which version of a process definition
				is considered the <emphasis>active</emphasis> version. Or they may simply want to
				<emphasis>retire</emphasis> the currently active process definition, so that no more
				process instances can be created, only allowing the already running process instances to
				continue until completed.
				</para>
				
				<para>
				To change the status of a process definition, the administrator should select the
				<emphasis>Runtime</emphasis> tab from the lefthand panel, and then select the
				<emphasis>Deployments</emphasis> option. This will show the process definitions, their
				versions and their current status (active or retired).
				</para>
				
				<imageobject>
					<imagedata fileref="images/ActivateRetire.png" align="center" width="6in" />
				</imageobject>			

				<para>
				To change a particular version from <emphasis>retired</emphasis> to <emphasis>active</emphasis>,
				simply select the <emphasis>retired</emphasis> version and press the <emphasis>Activate</emphasis>
				button in the bottom right.
				</para>
				
				<para>
				To retire a currently active process definition, simply select the particular version and
				then press the <emphasis>Retire</emphasis> button in the bottom right.
				</para>
				
			</section>
	       		
       </section>
       
       <section>
       		<title>BPEL Properties</title>
       		
       		<para>
       		When RiftSaw has been installed within the JBossAS environment, there is a property file
       		located at <filename>${JBossAS}/server/default/deploy/riftsaw.sar/bpel.properties</filename>.
       		</para>
       		
       		<para>
       		This property file contains a number of properties that are specific to ODE, and if interested
       		in these properties, then you should refer to the ODE documentation. Only one point to note,
       		the name of the property in this file maybe prefixed with <emphasis>bpel.</emphasis>, however
       		in the ODE documentation the prefix would be <emphasis>ode.</emphasis>.
       		</para>
       		
       		<para>
       		This section will present the properties that are specific to RiftSaw.
       		</para>
       		
       		<table frame="all">
       		<title>RiftSaw specific properties</title>
       		<tr>
       		<td>bpel.uddi.*</td>
       		<td>These properties relate to the UDDI support, which is discussed in a subsequent chapter.</td>
       		</tr>
       		<tr>
       		<td>bpel.jaxws.client.initializer.impl</td>
       		<td>This property is automatically set upon installation, based on the JAXWS stack being used.
       		This value should not be changed.</td>
       		</tr>
       		<tr>
       		<td>bpel.ws.stableInterface (default false)</td>
       		<td>This property determines whether the Web Service interface, associated with a BPEL process,
       		will be updated when a new version of the BPEL process is deployed. The benefit of setting this
       		to <emphasis>false</emphasis> is that changes to the WSDL will be made active with the BPEL
       		process. However the issue is that during the transition between the interfaces, the web service
       		will momentarily be unavailble - which may cause heavily used services to reject requests. By
       		setting this value to <emphasis>true</emphasis>, then the web service will remain available
       		while the BPEL process is updated, however any changes in the WSDL will not be made available.</td>
       		</tr>
       		</table>
       </section>
       
</chapter>
