Contents

Requirements

The workflow system provides two important services to repository clients.  These services are implemented within the repository and only exposed through the REST API. Hiding the implementation details is good modularity and security practice.

...

Here is the typical expected use of workflow.  The blue states are unpublished (and thus not indexed nor visible to the public); only the gold state is published. Lines with arrows show the possible transitions, and the role(s) permitted to take them.  The New state is implicit, it is where new instances come from. 

Two Isolated Labs

The other proposed use case is a pair (or more) of labs which share a repository, but they must not be allowed to see each other's unpublished resources.  In this picture, Lab A's resources are stored in separate workspaces - including a separate published graph and separate withdrawn graph - from Lab B's. 

...

• :hasWorkflowState - identifies the current state this instance is "in"; value is one of the WorkflowState object URIs
• :hasWorkflowOwner - names the repository user who is currently asserting a claim on the instance.  Value is URI of that user account.

WorkflowState

This is the existing repo class; no ontological changes, it is essentially a controlled vocabulary with which to enumerate the possible states.  Unlike fake workflow, the state does not grant access, it is transitions which have access controls. An instance has the following properties:

...

We will add a state, named "New", representing a  resource instance in the process of being created.  The state only exists momentarily inside the creation process to drive a workflow transition.

WorkflowTransition

This class represents a possible transition from an initial state to a final (relatively) in the workflow engine.  Think of workflow as a graph, with states as nodes, the transitions are the edges.  An instance has the following properties:

...

Transitions are actively managed by the repo administrator through an admin UI page. They live in the NG_Internal (intenral metadata) graph.  There is a sample set of transitions loaded at repo initialization but they are expected to be modified locally.

Actions

Actions are instances of a Java class implementing the WorkflowAction interface.  Its onTransition() method gets called with  the resource instance, and a transition-specific parameter (an RDF value object specific to the workflow transition, provided so the same action class can be re-used with different transitions).  For example, a transition that moves a resource instance to a different named graph would use a common move-to-graph action with the destination graph as its parameter.  Planned stock actions include:

• New instance in a designated graph
• Move instance to a new graph

About Access Control

Workflow manipulates the Repository's internal access control system to grant write (insert/delete) access to a resource when a user establishes a claim on it.  Since this mechanism circumvents the established rules of access control, it is absolutely essential that it only grant write access in the correct circumstances.  The repository administrator ought to be easily tell who can obtain write access to what resources by examining a small, manageable, amount of data.

...

QUESTION: What if the Claim operation is bound to a specific transition?  The user would have to make the claim in the context of a transition, and we could then have a customizable method associated with the claim.  This would let us configure e.g. whether or not to make the instance writable.  When claiming a Withdrawn or Published instance, for example, you might not want to allow it to be written until it goes back to Curation.  Is this useful or necessary?

API

The REST API requests are:

Show Transitions/repository/workflow/transitions

Method: GET or POST
Args:
 workspace=URI - restrict results to transitions applying to given workspace (includes wildcards). Default is to list all.
 format=mime - type of result.

...

• Subject URI
• Label
• Description
• Workspace URI
• Workspace Label
• initial-state URI
• initial-state Label
• final-state URI
• final-state Label
• allowed - boolean literal, true if current user has permission on this transition

Show Resources/repository/workflow/resources

Method: GET, POST
Args:
 state=URI|all - workflow state by which to filter, or 'all' for wildcard.
 type=URI - include only instances of this tyep (by inference counts) - default is no restriction.
 unclaimed=(true|false) - when true, unclaimed resources are included in the report.  Default is true.
 owner=(self|all|none) - show, in addition to any selected unclaimed resources:
     self  - those claimed by current user
     all - instances claimed by anyone
     none - includes no claimed resources. 
     Default is self.  Note that the combination unclaimed=false and owner=none is illegal.
 workspace=URI - restirct results to resources in a  given workspace; optional, default is all avaialble worksaces.
  format=mime - tyep of result, one of hte SPARQL query formats.
  detail=(brief|full) - columns to include in results, see description below.
  addPattern=SPARQL-text - add this triple pattern to SPARQL query.  May refer to variables as described below.  Value is a literal hunk of triple pattern ready to be inserted into the patterns of a SELECT query.  It may refer to the result variables mentioned below, e.g. ?r_type.
  addResults=query-variable.. - add these variables to results columns. value is expected to be a space-separated series of query variables (which must appear in the triple pattern), e.g. "?lab ?labname"
  addModifiers=modifiers.. - add a SPARQL modifiers clause to the query.  Modifers include ORDER BY, LIMIT, and OFFSET and can be used to implement pagination.

...

• The brief level of detail includes columns:
  • r_subject - URI of resource instance
  • r_label - label of resource instance
  • r_type - URI of instance's asserted type
• The full level of detail adds the fields:
  • r_created - created date from provenance
  • r_owner - URI of workflow claimant if any
  • r_ownerLabel - the rdfs:label of r_owner if it is bound (and has a label)
  • r_state - URI of workflow state
• Any query variables you specified in the addResults list are added to either result.

Create New Resource Instance/update?action=create

The /update action that creates a new resource instance now includes some implied workflow behavior: There is an transition into the New workflow state.  This means there must be a transition available to the current user and chosen destination workspace; if there are multiple transitions, one is chosen arbitrarily. 

Note that /update?action=create still requires that the user have Add access to the workspace graph in which the instance is created.  This might be an anachronism since workflow transitions bound to workspaces (provided there is no wildcard workspace) can also enforce access control.  Also, there is also no way to create an instance as a proxy for another user.

Claim Resource Instance/repository/workflow/claim

Method: POST
Args:
 uri=URI - subject to claim
 user=UserURI - optional, user who asserts the claim; default is authenticated user.

...

1. Adds insert and delete access to the instance for the claiming user.
2. Sets :hasWorkflowOwner property to the claimant (in an internal metadata graph)

Release (claimed) Resource Instance/repository/workflow/release

Method: POST
Args:
 uri=URI - subject to release

...

1. Implied release of any current claim (and all applicable side-effects of that)
2. Executes action associated with this transaction, if any.
3. Resource's workflow state will become the final state of the transition.

Administrative UI

The workflow mechanism also requires a couple of administrative UI pages, so admins can configure and examine the workflow system, and manage instances.  All of these functions require the Administrator role.

Manage Workflow Transitions

This page lists all workflow transitions, along with salient details of each - enough to select the one to edit.  E.g. label, initial/final states, workspace.  The master page also includes a link to create a new transaction (by filling in the detail page).

...

Possibly add a link to export selected transitions (see next section).

Export and Import Transitions

Dump a serialized-RDF representation of the transitions which can be imported later in any repository.  Options to select transitions, include access controls or not, etc.  This may only appear as a REST-type HTTP transaction, not an interactive Web form.

Manage Claims

List resource claimed instances (restricted by workspace, user, etc) and allow the admin to release the claim, either individually or on a group.  Includes sorting and pagination since results may be large.