\Dissemination{PUBLIC}
\DocumentLink{}
-\Abstract{This user's guide is intended for a user of the Job
- Provenance (JP) service. The service architecture characteristic is
- followed by description of main JP use case scenarios. Technical
+\Abstract{
+
+ Job Provenance (JP) service provides long-term storage of data
+ related to job live in a Grid. JP provides a query interface
+ allowing to perform data-mining. The possibility to annotate jobs
+ stored in JP is also provided.
+
+ There is a overview of the service architecture followed by main JP
+ use case scenarios in this document. Technical reference
documentation for both JP user and JP administrator is included in
- this document too. This version of user's guide is part of the
- first release of JP and it also contains release notes describing
- corrent limitations of JP implementation.}
+ this document too. This user's guide also contains release notes
+ describing current JP implementation.}
\def\todo#1{\textbf{TODO:} #1}
\begin{figure}[htpb]
\centering
- \includegraphics[scale=0.5]{JP-interactions}
+ \includegraphics[scale=0.7]{JP-interactions}
\caption{Data flow into gLite Job Provenance}
\label{fig:psinter}
\end{figure}
\begin{figure}[htpb]
\centering
- \includegraphics[scale=0.5]{JP-query}
+ \includegraphics[scale=0.8]{JP-query}
\caption{Index Server interactions}
\label{fig:query}
\end{figure}
The interface exposed by JPIS to the end user is described in the
chapter~\ref{reference}. Command line interface tool for end-user
-interface to the JPIS is described in the chapter~\ref{CLI}.
-
+interface to the JPIS is described in the chapter~\ref{CLI}. See the
+next chapter (use cases) for futher description of JP to user
+interactions.
\section{Job Provenance use cases}
-\todo{In next release}
+
+\subsection{Prerequisities}
+
+\subsubsection{LB/JP relationship}
+When JP deployed, any job in a terminal state will disappear from LB
+after preconfigured timeout (one week for example). If a user wants
+any information about such a job before this timeout (or before it
+reach a terminal state) he must use the LB service (please refer to LB
+user's guide). After that timeout he must use the JP service.
+
+\subsubsection{JP service location}
+To call JP you need to know JP services address. There are two services:
+\begin{itemize}
+\item JP primary storage (JPPS)\\
+ From JP design point of view there are only few PS in the
+ grid. Expected implementation is that these JPPS locations
+ are preconfigured in a UI instance while one of them is configured as
+ default JPPS.
+\item JP index server (JPIS)\\
+ Each index server is build (configured and started) by site/VO/user
+ group administrator (or even "senior user") based on given
+ community needs (expected queries and its optimization). So in
+ principle the index server location for a given query is to be
+ provided by the user. We expect that the UI instance will provide
+ mechanism allowing selection from preconfigured JPIS servers list.
+\end{itemize}
+
+\subsection{JP use case 1 -- get job info}
+
+The scenario:
+\begin{itemize}
+\item The user wants information about a particular job. He knows a
+ job id. Job isn't longer in the LB. Procedure: Ask the JPPS to get all
+ or selected attributes of job.
+\end{itemize}
+
+The implementation:
+\begin{itemize}
+ \item Let a user to specify attributes to be returned. See section
+ \ref{attributes}.
+ \item Call GetJobAttributes operation of a JPPS and display the values
+ returned.
+\end{itemize}
+
+Examples and hints:
+\begin{itemize}
+ \item \texttt{org.glite.jp.primary/examples/jpps-test.c}\\
+ This utility is used for all JPPS operations. Some hints how to use it
+ can be find in the test plan document.
+\end{itemize}
+
+\subsection{JP use case 2 -- get job files}
+
+The scenario:
+\begin{itemize}
+ \item The user knows a job id, job is in a terminal state. The user wants
+ all files (LB event dump, sandbox) stored by JP for futher processing.
+\end{itemize}
+
+The implementation:
+\begin{itemize}
+ \item Call GetJobFiles operation of a JPPS. You will get a list of URLs
+ which can be used to download the files.
+\end{itemize}
+
+Examples and hints:
+\begin{itemize}
+ \item The same as use case 1.
+\end{itemize}
+
+\subsection{JP use case 3 -- job lookup}
+
+The scenario:
+\begin{itemize}
+ \item The user is looking for jobs with specific properties. In this case
+ (no job id known) a JPIS must be used. There are the same query interface
+ provided by any JPIS but if a particular query can be answered by
+ the given JPIS depends on its configuration (configuration
+ determines which attributes are uploaded by PS to IS, and which of
+ them are indexed).
+ \item The user should know the proper JPIS to use for its particular
+ needs.
+ \item The scenario can continue by the JP use cases number 1 and 2 described
+ above (JPIS answer will contain job ids and identification of JPPSs
+ to ask for all available JP data about the jobs).
+\end{itemize}
+
+The implementation:
+\begin{itemize}
+ \item The user will select a JPIS and provide query. The JPIS operation
+ QueryJobs is called and list of jobs matching the query is returned.
+\end{itemize}
+
+Examples and hints:
+\begin{itemize}
+ \item JPIS CLI tool\\
+ org.glite.jp.index/examples/jpis-client.c
+
+ \item example in org.glite.jp.index/examples/jpis-test.c (starting
+ from line 161)
+\end{itemize}
+
+\subsection{JP use case 4 -- job annotation}
+
+The scenario:
+\begin{itemize}
+ \item The user wants to add a user tag (annotation) to a job. He must know
+ the job id(s) (or use the JP use case number 3 to find it).
+\end{itemize}
+
+The implementation:
+\begin{itemize}
+ \item Call RecordTag operation of JPPS for the job(s) to add requested
+ user tag.
+\end{itemize}
+
+Examples and hints:
+\begin{itemize}
+ \item The same as use case 1.
+\end{itemize}
+
+
+\subsection{Job attributes}
+\label{attributes}
+Job attributes are referenced by its names. Each attribute belongs to
+one namespace (represented by a prefix in the attribute name).
+
+A namespace is defined by a service (currently we have one for LB and
+one for JP) providing its data to the JP or a user group/experiment
+etc. who wants to attach its own data to the job.
+
+It is expected that UI have preconfigured list of available namespaces
+and XML schema for each namespace (the schema can be automatically
+retrieved based on the namespace name). A list of available attributes
+is generated from these schemas when user have to select attributes to
+be retrieved from JP.
+
+\begin{itemize}
+ \item The namespaces (schema is available at the URL representing namespace):\\
+ http://egee.cesnet.cz/en/Schema/LB/Attributes\\
+ http://egee.cesnet.cz/en/Schema/JP/System <<<<<<<(NOT YET)\\
+ \item There are header files with known names of attributes generated from
+ these schema files in our build procedure:\\
+ org.glite.lb.server/build/jp\_job\_attrs.h\\
+ org.glite.jp.common/interface/known\_attr.h <<<<<<<\\
+\end{itemize}
+
+\subsection{Authentication and authorization}
+All the calls must be authenticated by user credentials. In the
+current JP release only implicit ACLs are available -- the job
+information is available for job owner only.
+
\section{Release notes}
\todo{TBD}
-\section{Documentation for JP users}
+\section{References}
%\subsection{Role of the JP administrator}
% Podle Ljochy sem nepatøí. Podle mne musí u¾ivatel vìdìt kdy a s èím
% otravovat administratora (zejména IS).
+In general, the page \texttt{http://egee.cesnet.cz/en/JRA1} should
+contain actual versions of JP documentation.
+
+Interfaces (WS):
+\begin{itemize}
+ \item In source code tree the WSDLs are located in these files:\\
+ \texttt{org.glite.jp.ws-interface/src/JobProvenanceIS.xml,\\
+ org.glite.jp.ws-interface/src/JobProvenancePS.xml,\\
+ org.glite.jp.ws-interface/src/JobProvenanceTypes.xml
+ }
+\end{itemize}
+
\subsection{Command line interface (CLI)}
\label{CLI}
{
git://scientific.zcu.cz / jra1mw.git / commitdiff