Overview of the SAM Request System

SAM provides interfaces, per the user requirements, that allow bookkeeping on simulation and reconstruction processing requests. This document outlines the envisioned use case; for more information on individual commands or interfaces, see the sam documentation.

1. User creates a request.
   A new request is entered into the system. It will have status 'new'. The user is able to modify the request (change the dataset definition, or the number of events, or modify any of the request params), as long as the status remains 'new'.

           # Examples:
   
           # simulation request for 1000 events:
           $ sam create request \
              --requestType=simulation \
              --nEvents=1000 \
              --paramFile=myRequestParams.py
   
           # reconstruction request for dataset definition 'myDefName':
           $ sam create request \
              --requestType=reconstruction \
              --definitionName=myDefName \
              --group=myWorkGroup \
              --paramFile=myRequestParams.py
           

   The user may also create a request by cloning an existing request, rather than by entering all of the information from scratch:

            $ sam clone request --requestId=12345
           

2. User modifies the request data.
   The new request is "tweaked" if necessary:

           # Example:
   
           # change number of events in a simulation request:
           $ sam modify request --requestId=12345 \
                 --nEvents=500 \
   
           # change dataset for reconstruction request:
           $ sam modify request --requestId=23456 \
                 --snapshotId=506
   
           

3. User 'freezes' the request.
   Once the user is satisfied that the request data is correct, the user 'freezes' the request by setting the status to 'pending'. This implies that the request data can no longer be modified.

           # Example:
   
           $ sam modify request --requestId=12345  --requestStatus=pending
           

4. Request is 'approved' (or not).
   Once a request has been 'frozen' (i.e., set to status 'pending'), it can be 'approved' for processing or put into a 'hold' state (not yet approved for processing). It can also be 'terminated', meaning that it will never be approved for processing.

           # Example:
   
           $ sam modify request --requestId=12345 --requestStatus=approved
           $ sam modify request --requestId=23456 --requestStatus=hold
           $ sam modify request --requestId=567   --requestStatus=terminated
           

5. RequestHandler(s) are assigned to the request.
   The SAM database is informed that a processing center intends to handle a particular request by entering one or more requestHandlers associated with the request. The first requestHandler created will automatically change the status of the request from 'approved' to 'partial', meaning that the request is partially handled (i.e., in the process of being handled). Each new requestHandler will have its requestHandlerStatus set to 'assigned'.

           # Example:
   
           $ sam create requestHandler --requestId=12345
           

6. Processing Center tracks and updates the requestHandler(s).
   The processing center is responsible for entering the particular details of the requestHandler into the SAM database. The requestHandler information includes:
   • status of the requestHandler ('assigned', 'running', 'complete', or 'terminated').
   • grid job identifier (global jobId for the process associated with this handler)
   • mc production center facility name (simulation requests)
   • number of events generated by this handler (simulation requests)
   • sam project that was run to handle this request (reconstruction requests)

           # Examples:
   
           # SIMULATION:
           # mark that a simulation request handler is running:
           $ sam modify request handler --requestHandlerId=101010 \
               --requestHandlerStatus=running \
               --gridJobIdentifier='MY_GLOBAL_JOB_ID' \
               --facilityName='My MC Production Center'
   
           # later, when this job has finished successfully, mark the number of events generated
           #  and the fact that it is complete:
           $ sam modify request handler --requestHandlerId=101010 \
               --requestHandlerStatus=complete \
               --nEvents=5000
   
           # or, if the job crashes and is not able to complete successfully,
           #  inform SAM that the job has terminated:
           $ sam modify request handler --requestHandlerId=101010 \
               --requestHandlerStatus=terminated
   
           # RECONSTRUCTION:
           # mark that a simulation request handler is running:
           $ sam modify request handler --requestHandlerId=202020 \
               --requestHandlerStatus=running \
               --project=myProject_toHandler_request456_part1
   
           # later, when this project has finished, inform SAM:
           $ sam modify request handler --requestHandlerId=202020 \
               --requestHandlerStatus=complete
   
           # or, if something went wrong with the project, inform SAM:
           $ sam modify request handler --requestHandlerId=202020 \
               --requestHandlerStatus=terminated
           

7. Inform SAM of the final Request Status.
   When all of the necessary requestHandlers have finished their work, the final status of the request is set to either 'complete' (all requested events were generated, or all files contained in the specified dataset were successfully processed) or 'terminated' (request cannot be completed for some reason).

           # Example:
   
           $ sam modify request --requestId=12345 --requestStatus=complete
           $ sam modify request --requestId=23456 --requestStatus=terminated