Workflow Templates

The stages that a workflow goes through, and the transitions between them, are defined by in a so-called workflow template. Workflow templates are selected whenever a new workflow is started, and remain with that workflow for the rest of its life cycle.

The Workflow Templates page, available from near the bottom of the main menu on the left, shows the templates that define the available workflow types, e.g., the Basic Workflow. Users with administration permission can customize these workflow types.

The workflow templates are defined in TopBraid in a dedicated RDF graph. To access the workflow templates graph from SPARQL or ADS scripts, use the function teamwork:workflowsGraph().

Warning

Editing workflow templates is a low-level operation that should be handled with care. It is technically possible to modify workflow templates that are already in use and, as a result of this, an existing working copy may be in a state that gets disconnected from the other states in the template, or its whole workflow template may get deleted. We therefore strongly recommend that the development and editing of workflow templates is performed by expert users only, and tested in a sandbox environment (such as a TopBraid EDG Studio) before deployment to a production server. Alternatively, consider having TopQuadrant services develop custom workflows for you.

EDG comes with a default workflow called Basic workflow.

Hint

If you delete the basic workflow by accident you can bring it back via Install Default Workflow Templates.

The editing of workflow templates is currently best performed through source code editing. You may elect to use TopBraid EDG Studio but any other 3rd party source code editor is also suitable. For administrators, the basic mechanism is:

  1. Go to the Workflow Templates on the production server

  2. Click Download as Turtle File to a local file

  3. Edit this file using an editor of your choice

  4. In a test environment such as TopBraid EDG Studrio, use Upload Turtle File to replace the current definitions and try them out

  5. If any syntactic or semantic errors are detected, the Upload feature present a report of all the errors found in the file. These errors must be addressed in order for the file to be successfully uploaded.

  6. Carefully test the workflows in your test environment.

  7. When satisfied, use Upload Turtle File to replace the definitions on the production server.

Defining a Workflow Template

Workflow templates must be instances of one of the following classes:

  • teamwork:TagWorkflowTemplate for general asset workflows teamwork:ExistingResourceTagWorkflowTemplate for workflows that are specific to an existing asset) teamwork:NewResourceTagWorkflowTemplate for workflows that create a new asset

Each workflow template defines a start status (e.g. Uncommitted) and a set of transitions that specify which steps are possible and by whom, until the workflow is ended (e.g. by committing). The properties are typically used at workflow templates:

  • rdfs:label: a human-readable label that is used to name the workflow template in the user interface

  • teamwork:initialStatus: specifies the initial status of a Workflow. Example values include teamwork:Uncommitted or teamwork:New.

  • teamwork:defaultTagWorkflowTemplateForProjectType: enumerates the asset collection types for which the workflow template is the default. Asset collection types that don’t have any default workflow template fall back to the system-wide default workflow template. For example, use edg:GlossaryProjectType as a value to make the workflow template the default for EDG Glossaries.

  • teamwork:suitableWorkflowForProjectType: enumerates the asset collection types for which the workflow template is suitable for use. If left empty, it applies to all types. For example, use edg:GlossaryProjectType as the value to make the workflow template only applicable to EDG Glossaries.

  • teamwork:suitableWorkflowForSubjectArea: the subject areas that asset collection must have so that the workflow template is suitable for them. If left empty, then it applies to all subject areas. Details about defining subject areas can be found at EDG Governance Model: Governance Areas.

  • teamwork:editorWorkflowParticipantProperty: lists the workflow participant properties (e.g. edg:responsible) whose users are automatically granted editing permission. By default, workflow participants only get viewer permission.

  • teamwork:managerWorkflowParticipantProperty: lists the workflow participant properties (e.g. edg:responsible) whose users are automatically granted manager permission. By default, workflow participants only get viewer permission.

  • teamwork:tagShape: (advanced feature) SHACL shapes that the working copy needs to conform to before it can be committed. See Using SHACL Shapes to control Workflow Transitions.

An additional property for templates that have the type teamwork:ExistingResourceTagWorkflowTemplate:

  • teamwork:editedResourceShape: the shape that edited resources need to have. Used to filter applicable workflows for a given resource. If multiple values are present then they are interpreted as a union, i.e. a candidate resource must conform to any one of them. An example of this is teamwork:editedResourceShape [ sh:class ex:Person ] to limit a workflow for instances of ex:Person.

Defining Workflow Statuses

All individual statuses of a workflow are represented by instances of the class teamwork:TagStatus. Often you would simply reuse existing instances in your workflow templates.

Hint

Copy and paste from existing workflow templates to get started with your own templates.

Defining Workflow Template Transitions

A workflow is started in the status specified by teamwork:initialStatus in the template. From there, the possible transitions are defined by the values of teamwork:transition. These values must be URI or blank nodes of type teamwork:TagStatusTransition, and can have the following properties:

  • teamwork:fromStatus: the status that the workflow (working copy) must be in for the transition to be applied.

  • teamwork:toStatus: the status that the workflow (working copy) will be in after the transition is applied.

  • teamwork:transitionLabel: the display label of the transition, e.g. “Accept changes to production”.

  • sh:order: an optional number that is used to order the transitions in the Workflow tab. Transitions with smaller numbers show up higher, with 0 being the default.

  • teamwork:requiredGovernanceRole: the minimum governance role (e.g. informed) that a user must have on an asset collection to perform the transition. For example, the required governance role can be an instance of edg:JobRole, which means that any user who has edg:assignedJobRole edg:JobRole is allowed to execute the transition. The user will in this case see a corresponding button in the UI, and under My Workflows.

  • teamwork:requiredProjectPermissionRole: the minimum permission role (e.g. editor) that a user must have on an asset collection (master graph) to perform the transition. These are the roles defined on the User Roles tab of an asset collection.

  • teamwork:requiredTagPermissionRole: the minimum permission role (e.g. editor) that a user must have on a working copy to perform the transition. These are the roles defined on the User Roles tab of a working copy/workflow.

  • teamwork:minVoteCount: the minimum number of votes required before the transition can be performed.

  • teamwork:voteAutoTransitions: if true then the transition will be performed automatically, as soon as sufficient votes have been registered. This property can only be used if teamwork:minVoteCount is present.

  • teamwork:autoTransitionHours: the number of hours after which a working copy will automatically transition to another state. For example this can be used to give users a chance to comment without explicitly waiting on such feedback.

Sample Workflow Templates

Example workflow templates can be downloaded from this page.

There is also a detailed training guide for workflow templates, custom governance roles and event condition actions. All of this content is also in the page above but without detailed screenshots. The screenshots may not be exact representations of the version you are on but should still be helpful in showing the process. This is meant to supplement what you have learned in the above sections of this guide.

Download the guide for details: * Teamworks-and-Workflow-Templates.pptx

  • Custom Governance Roles

  • Teamworks and Technical Underpinnings of Working Copies

  • Workflow Templates

  • Notifications

  • ECA Framework

Using SHACL Shapes to control Workflow Transitions

SHACL can be used to define constraints that must be satisfied before a workflow transition can be applied. The SHACL constraints are validated using the union of the working copy and the TCH graph as data graph, and the workflows definitions graph as shapes graph. The focus node is the teamwork:Tag instance.

The following example illustrates the use of teamwork:tagShape to specify that a working copy can only be committed if it contains exactly one new instance of edg:GlossaryTerm and no other subject. If teamwork:tagShape statements are present for a workflow template, then the Commit button will force the user to first go through a dedicated page that checks whether the working copy conforms to the specified shapes. If violations are detected, the user may still proceed, yet he or she has been warned about the consequences.

 1edg:SimpleGlossaryTermWorkflowTemplate
 2    rdf:type teamwork:NewResourceTagWorkflowTemplate ;
 3    teamwork:initialStatus teamwork:Uncommitted ;
 4    teamwork:tagShape glossary-term-workflow:TagHasExactlyOneGlossaryTermShape ;
 5    # ...
 6    .
 7
 8glossary-term-workflow:TagHasExactlyOneGlossaryTermShape
 9    rdf:type sh:NodeShape ;
10    sh:sparql [
11        sh:message "Working copy contains changes about {?other} while it should only be about {?newTerm}" ;
12        sh:prefixes <http://edg.topbraidlive.org/1.0/samples/workflows/glossary-term-workflow> ;
13        sh:select """
14            SELECT DISTINCT $this ?other ?newTerm
15            WHERE {
16                ?change teamwork:tag $this .
17                ?change a teamwork:Change .
18                ?change teamwork:added ?added .
19                ?added teamwork:subject ?newTerm .
20                ?added teamwork:predicate rdf:type .
21                ?added teamwork:object edg:GlossaryTerm .
22                ?otherChange teamwork:tag $this .
23                ?otherChange a teamwork:Change .
24                ?otherChange teamwork:added|teamwork:deleted ?aod .
25                ?aod teamwork:subject ?other .
26                FILTER (?other != ?newTerm) .
27            }""" ;
28    ] ;
29    sh:sparql [
30        sh:message "Working copy does not create a new instance of edg:GlossaryTerm." ;
31        sh:prefixes <http://edg.topbraidlive.org/1.0/samples/workflows/glossary-term-workflow> ;
32        sh:select """
33            SELECT $this
34            WHERE {
35                FILTER NOT EXISTS {
36                    ?change teamwork:tag $this .
37                    ?change a teamwork:Change .
38                    ?change teamwork:added ?added .
39                    ?added teamwork:subject ?gt .
40                    ?added teamwork:predicate rdf:type .
41                    ?added teamwork:object edg:GlossaryTerm .
42                }
43            }""" ;
44    ] .

State Entry Actions

Each workflow status may have a teamwork:stateEntryAction pointing at a script that shall be executed whenever the status is reached. This can be used to implement side effects, such as sending a notification to 3rd party systems when a certain state has been entered.

Although earlier examples may use SWP for this, we recommend using JavaScript/ADS to implement the business logic of those state entry actions. See Scripting with JavaScript and ADS if you are not yet familiar with ADS.

To get started, create an instance of teamwork:WorkflowActionScript and add a triple from a workflow status to the script using teamwork:stateEntryAction. The script that is the value of dash:js will be executed against the master graph (with imports) and can access the following JavaScript variables:

  • newStatus (NamedNode): the teamwork:TagStatus that was just entered

  • oldStatus (NamedNode): the previous teamwork:TagStatus

  • tag (NamedNode): the teamwork:Tag instance representing the workflow

Instances of this class should be declared in the workflow templates graph. During development, you may want to use the Script Editor panel (with the master graph as active graph) to try your code and later assign it to dash:js. Simulate the values of the variables above through let statements which you place before your actual code.