[[ucc_ogsabes]]
OGSA-BES functions
------------------

Assuming you have successfully installed UCC xref:ucc_install[], this section
shows you how to manage and monitor jobs on OGSA-BES services using UCC. 
The set of commands not only supports the UNICORE implementation, but may also 
work with implementations in other Grid middlewares compliant with OGF's 
http://www.ogf.org/documents/GFD.108.pdf[OGSA-BES specification]. 

OGSA-BES Setup 
~~~~~~~~~~~~~~
 
In UNICORE style, users are required to provide a Registry URL inside the preferences file. 
For BES users it is not always the case that an endpoint is advertised via a UNICORE 
Registry. Therefore, the configuration options allow user to modify this behaviour.
  
--------------
contact-registry=[true|false]	
--------------
     
Users who whish to disable UCC calling the registry can set the "contact-registry" 
option to false. By default the "contact-registry" option is true.  
            
When setting "contact-registry" to false, OGSA-BES users must provide at least 
one BESFactory URL using the following format. 

--------------
bes.1=https://site1.com/services/BESFactory
bes.2=https://site2.com/services/BESFactory
bes.3=https://site3.com/services/BESFactory
bes.4=file:///tmp/bes-jugene.xml
bes.5=/tmp/bes-juropa.xml
...
--------------
    
If the "contact-registry" option is set to false and no OGSA-BES URL is specified, 
UCC will report an error. 
To use an XML endpoint reference (EPR) read from a file for contacting a BESFactory 
service, the contents of a EPR file must validate against
the WS-Addressing's endpoint reference schema. See below the contents of the 
sample endpoint reference file,
	
--------------
<wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
  <wsa:Address>https://localhost:8080/DEMO-SITE/services/BESFactory?res=default_bes_factory</wsa:Address>
</wsa:EndpointReference>
--------------     	 

In the above XML snippet, under the "Address" tag, you must specify the URL of a target BESFactory service.  
	
For the sake of convenience, here is an XML infoset representation taken from the 
http://www.w3.org/TR/ws-addr-core/[WS-Addressing specification]:
	
--------------
<EndpointReference>
    <Address>xs:anyURI</Address>
    <ReferenceParameters>xs:any*</ReferenceParameters> ?
    <Metadata>xs:any*</Metadata>?
</EndpointReference>
--------------     	 
	
	
Running and monitoring OGSA-BES jobs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

UCC provides an easy to use command for submitting jobs on OGSA-BES complaint endpoints. 
To send a job read from a JSDL file,

--------------
ucc bes-submit-job -j hellompi.xml -s bes.3 -v
--------------     
  
Alternatively, the job can be submitted using a BESFactory URL or endpoint 
reference file path.

--------------
ucc bes-submit-job -j hellompi.xml -s https://example3.com/services/BESFactory -v
--------------	
 
or

--------------
ucc bes-submit-job -j hellompi.xml -s file:///tmp/bes-jugene.xml -v
--------------	

  
The JSON job description xref:ucc_jobdescription[] can also be used, although only 
a subset of JSON constructs are supported for the OGSA-BES extensions.

Users can fetch the job status by specifying the descriptor (.job) file. 
This file is automatically generated after a successful execution of "bes-submit-job" command. 
Example:

--------------
ucc bes-job-status jobid.job
--------------  	

Job can be terminated using a job descriptor file:

--------------
ucc bes-terminate-job jobid.job
--------------  	

  
To list BESFactory properties:
  
--------------
ucc bes-list-att -s bes.1
--------------  	
  
The above command will result in BESFactory's properties without jobs information. 
To see the list of the user's jobs on a BESFactory
  
--------------
ucc bes-list-job -s bes.1
--------------  	
    
Enabling username/password authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Some BES implementations support authentication using username and password.
To add username and password to the messages sent by UCC, the UCC preferences 
file must contain the following settings

---------------
#
# setup username/password
#
uas.security.out.handler.classname=de.fzj.unicore.bes.security.UsernameOutHandler
de.fzj.unicore.bes.security.UsernameOutHandler.wsUserName=<your_username>
de.fzj.unicore.bes.security.UsernameOutHandler.wsPassword=<your_password>
de.fzj.unicore.bes.security.UsernameOutHandler.wsActivateUsernameProfile=true
---------------

