Developing an EDG Workflow Template 

In this section we will walk through the process of creating a workflow template. For more information on workflows, see Understanding and Using Workflows. For more information on workflow templates, also see Workflow Templates. The workflow template developed here will demonstrate how to create new statuses, transitions, restrictions on transitions, and script to execute code when entering or leaving a state.

The scripts we demonstrate here use some basic Active Data Shapes ADS. For these sections, it is therefore strongly recommended that you are comfortable programming in JavaScript to complete this section, and also that you become familiar with the ADS documentation Introduction to ADS. If you are interested in integrating with external systems via your workflows, this section is extended in more detail in Accessing the External APIs from within an EDG workflow.

Contents

Developing an EDG Workflow Template

1. Workflow template overview 

We will begin by designing our workflow. So, we must consider what workflow we wish to represent. Our workflow will consist of an option to review changes, before it is committed to production. The workflow will restrict those who can create new workflows to the “data governor” role and “data producer” role, it will also restrict those who can accept changes during review to “data governor”. In other words, only people assigned that role in the governance model will be able to transition the state to the next state.

The workflow will therefore require the following states;

Uncommitted: A start state
Under review: A state for reviewing changes
Approved: A state before a workflow is finally committed
Committed: A state to export the result and commit to production

It also has the following transitions;

Transition: “Commit for review” which takes status “Uncommitted” -> “Under review”

Transition: “Request further changes” which takes status “Under review” -> “Uncommitted”

Transition: “Approve changes” which takes status “Under review” -> “Approved”

Transition: “Accept changes to production” which takes status “Approved” -> “Commited”

Ultimately, the workflow should look like this -

**Workflow template states and transitions”**

Finally we need to have two transition scripts. Here we will use some simple ADS code to indicate how you can interact with EDG and they will both be placed on our “Under review”.

Now let us begin developing the workflow template in EDG.

2. Setting up your workflow template 

Workflow templates are stored in the governance areas, which you can access via the Collections menu, Governance and “Workflow templates”.

Naming the workflow ontology — **Accessing “Workflow Template”**

You can create a new workflow template by clicking the “New” button

Configure ontology to be editable — **Creating a new “Workflow Template”**

The next step is to configure the workflow instance. We begin by specifying an initial status. Here we are putting uncommitted. This means when we start our workflow, we begin in this state. We can also then configure some restriction here in the UI panel, such as the required governance roles to be able to create a workflow. Here we are specifying data governor role and data producer role. This means that only those users who are assigned these roles on these asset collections in the governance model, will be able to create new workflows.

Create a workflow template instance — **Configure the initial workflow state of the template**

Here we see the result after we add our initial status and required governance roles and save.

Now let us look at the creation of transitions. You create new transitions via the plus button on the right of the transition in the form.

You will then have a prompt to create a new transition. We have called our first transition “Commit for review” and specified the transition label the same. The transition label can be different from the instance label, and is what you will see in the UI as the name of the transition. You must also specify the from and to status. Here we want the transition to take use from the Uncommitted status to the Frozen for review status.

To access our new transition to edit it, we must click on it in the form.

Workflow template with transitions — **Edit a transition**

Here we see the new transition, we see its labels, type and the to and from status. Now let us add some more transitions.

Add the following transitions; “Accept changes to production”, “Approve changes” and “Request further changes”. The transitions should be to and from the status that are visible in the diagram on the left.

After adding each of your transitions, you can now view the result via the “Workflow Templates”, accessible on the top right of EDG. From here select your template.

You should see the following. You can read the different states and transitions, or use the diagram view option.

We can also create a new status instead of using one of the pre built ones in EDG that we have so far been using. You must do this from one of the transitions, and via the to or from status. Lets create a new status that we move into from Uncommitted called “Under review” to replace the existing “Frozen for review”.

Here we have selected the “Under review” status. We can click the edit button (or chose to show properties that have no values via the gear icon) to see the available properties for status. As you can see you can make it so that the content of the workflow is “read only” when in this state. Or you can edit the icon associated with the status, i.e. a pause icon, the same as for “Frozen for review”. You can access icons from Font Awesome . Or you can specify actions on state entry. We will discuss the options for actions later in this session.

2.1 Adding restrictions to the workflow template 

We can also add some additional restriction to our transitions. To do this, we must make use of the source panel. The first restriction we will add, is to require that some changes be made before you can transition to “Frozen for review”. Select the “Freeze for review” transition, drag and drop the Source Panel, and add the following triples teamwork:requiresChanges true ;.

<urn:x-tb-governance:CommitForReview>
   a teamwork:TagStatusTransition ;
   teamwork:fromStatus teamwork:Uncommitted ;
   teamwork:toStatus <urn:x-tb-governance:UnderReview> ;
   teamwork:transitionLabel "Commit for review" ;
   rdfs:label "Commit for review" ;
   teamwork:requiresChanges  true ;
.

Next we will add a second restrition, so that only a “data governor” can accept the changes.

<urn:x-tb-governance:ApproveChanges>
   a teamwork:TagStatusTransition ;
   teamwork:fromStatus <urn:x-tb-governance:UnderReview> ;
   teamwork:toStatus teamwork:Approved ;
   teamwork:transitionLabel "Approve changes" ;
   rdfs:label "Approve changes" ;
   teamwork:requiredGovernanceRole edg:dataGovernor ;
.

Okay, now we have our workflow template and our transitions and new status.

Let us now add some transition scripts.

3. Writing a transition script which writes some triples to the workflow graph 

We begin with a “workflow status entry script”. You can create a new status entry script via the tag status. Let us add one to the tag status we create, i.e. the “Under review” status. We again click on the plus icon, this time for our status entry script. We can call it “Workflow status entry script”.

EDG Workflow Status Add Entry Script — **Adding a transition script to a status”**

This entry script will simply write some logging data to the workflow asset collection. The SPARQL query adds a timestamp based on the current time on the EDG server, and a string.

graph.update(`
   INSERT {
   <http://example/log>
      <http://example/preInProgressOneTimestamp> ?ts ;
      <http://example/preInProgressOne> "Completed Enter Script" ;
   .
   } WHERE {
   BIND(NOW() AS ?ts) .
}`)

And that is the transition script. It should look something like this in your EDG workflow template.

EDG Workflow Status Entry Script — **How your transition script should look**

Now, let us create a second transition script. Add this to the “Frozen for Review” status, but this time choose “status exit script”. Call this “workflow exit transition script”.

graph.update(`
INSERT {
<http://example/log>
   <http://example/preInProgressOneTimestamp> ?ts ;
   <http://example/preInProgressOne> "Completed Exit Script" ;
.
} WHERE {
BIND(NOW() AS ?ts) .
}`)

And that is our two transition scripts. You can now test your workflow template in EDG.

4. Test your workflow template 

You can once again see the textual description of all the states, their transitions, and any restrictions or actions associated with it.

Accessing EDG workflow templates — **Viewing your finished workflow template**

Now you can test your workflow by creating a new asset collection, and then starting a workflow and choosing this template. To test your script is running correctly you can query the asset collection either from within the workflow, or after commit, via the SPARQL panel using the following query:

SELECT * WHERE {
   <http://example/log> ?p ?o
}

Developing an EDG Workflow Template

1. Workflow template overview

2. Setting up your workflow template

2.1 Adding restrictions to the workflow template

3. Writing a transition script which writes some triples to the workflow graph

4. Test your workflow template