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.

...

• Remove the requirement for all users to have Administrator access to the repository:
  • Use Workflow transitions and claims to grant each individual user write access to an individual resource instance.
  • Rely on existing graph-based access control to manage read access to unpublished resources.
• Employ role-based access control to manage access to each workflow transition
• Allow separate, isolated, streams of workflow. For example, Lab A and Lab B can share a repository without being able even to see each other's unpublished resources.
• Produce user-sensitive reports on:
  • Transitions available to current user
  • Resources visible to current user with workflow implications
    (This might be used for auto-complete result sets)
• Highly configurable and extensible data-driven design, so some unanticipated needs can be met simply by changing internal data and configuration

Use Cases

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.

...

Presumably the repository's access controls are configured so only Lab A's personnel have read access to the Workspace A and Withdrawn A graphs. The two Published graphs must be world-readable, and of type Published, but they also have to be separate: Resources are not "owned" by any user or role. The workflow transitions available on a resource instance are governed by a combination of the resource's home graph and the user's role, so keeping Lab A's published resources in e.g. the Published A graph will let you configure workflow transitions on that graph so they are only available to Lab A's users.

Ontology and Design Principles

Resource Instance Properties

Workflow is expressed as two properties that may be asserted on resource instances. The statements using these predicates live on the internal metadata (:NG_Metadata ) graph, so they are visible to the world but can only be modified by administrators and internally-mediated actions. The properties are:

• :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 repository 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 repository administrator through an admin UI page. They live in the NG_Internal (intenral metadata) graph. There is a sample set of transitions loaded at repository 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:

...

• 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=---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. Removes insert and delete access to the instance for the current user.
2. Removes :hasWorkflowOwner* property (in an internal metadata graph)

Transition on Resource Instance/repository/workflow/push

Method: POST
Args:
uri=URI---subject to transition
transition=URI}}---indicates transition to take

...

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 enough salient details of each to select the one to edit. For example, label, initial/final states, and 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.