Workflows

To help teams maintain asset collections, EDG workflows provide special views and functions that coordinate multiple users in defined change-management processes.

Users can start workflows for an entire asset collection or for a specific asset in a collection. Multiple workflows can be active at the same time. Changes made in each workflow are isolated from other workflows and are not part of the asset collection until authorized users review, approve, and commit the workflow’s changes back to the “production copy”. To isolate its changes, each workflow has a “working copy” of changes from the production state.

*Note that the any includes always refer to other collections’ production copies, never to working copies. In other words, uncommitted changes to an asset collection can not be included into a workflow for another asset collection.

EDG is shipped with a pre-defined workflow template called Basic. Additional workflow templates can be developed for your EDG installation. These templates can implement different process-flows with different scope of applicability. A template determines what users can perform various actions in a workflow:

  • A template can specify what governance roles should have editor and manager privileges for the associated working copy
  • A template always specify who can transition a workflow from one state to another. Authorizations for the workflow transition actions can be defined for permission levels (v/e/m) or for governance roles. For an example of such workflow transitions, see the main Workflow View tab for the Basic workflow.

If an asset collection you are working with has any workflow in progress you can access them by clicking on Workflows tab for the collection.

Any changes you will make will stay in the working copy associated with this workflow and will not be visible outside it. The tabs (import, reports,…) for a workflow operate  the same as for the production copy but in the scope of the workflow only. Until it is committed to production, changes remain here only.

Starting a Workflow

There are two places in EDG where you can start a workflow by selecting Start Workflow:

  • When viewing a specific asset in the Editor, user can select Start Workflow from the asset menu.
  • Start Workflow button is also available on the Workflows tab.

Workflow can be started for a specific asset or for an entire collection if you will be creating a new asset(s) or making changes to multiple assets.

 

Start workflow dialog will let you select a workflow template (if more than one template is available) and provide a short description. TopBraid EDG will auto-generate a unique name for a workflow. If desired, you can override the generated name.

Working in a context of a Workflow

You will always know when you are working in a context of a workflow because the horizontal menu bar on top of asset collection pages will change its color from grey to light yellow.

In a context of a workflow you will see the same tabs as in the context of the asset collection it is performing updates to, although some tabs will be greyed out. For example, you can not start a workflow within a workflow which is why the Workflows tab is greyed out.

To make edits, use the same features as those normally available to you for an asset collection.

You will also see a new tab with a gear  icon on it – shown in the screenshot below. This tab lets you see information about the current state of workflow and lets authorized users move it to the next state.

When you click on the Diagram View link, the page switches to a view that visually depicts the workflow state and transitions. For example, if we, after making changes, click on the Freeze for review link and then switch to the Diagram View, the diagram will look as follows:

State that a workflow is currently in is shown in the diagram as a green colored box. If you could move a workflow into a next state, the diagram will depict transition actions as green clickable buttons. On the diagram above, you see three possible actions – to approve, to reject and to request further changes by reverting the workflow back to the Uncommitted state.

You can easily navigate from a workflow to the asset collection itself (production copy) by clicking on the icon next to the workflow name.

Rights Entailed by Permission Profiles

 

Whoever starts a workflow becomes the manager of its working copy, even if that user only had viewer privileges of the asset collection itself. Such user can then make changes in the context of a workflow but cannot commit them to Production because only users with editor privileges for an asset collection can make changes to them.

The same permission profiles of manager, editor and viewer are applicable to production copies and working copies, but the rights they entail are slightly different – as described below:

For an asset collection (production copy)

  • A viewer of an asset collection can:
    • view and browse it,
    • view a history of its changes,
    • display various reports,
    • export it in a variety of formats,
    • enter its usage information,
    • create tasks, change the status of a task assigned to them and comment on tasks, and
    • create a workflow copy of it to make changes, which will not be applied back to the production one until the changes are reviewed and committed by an editor or manager of that production asset collection.
  • An editor has all viewer permissions and can also make changes.
  • manager has all editor permissions and can also:
    • perform operations on the Manage tab (for details, see the Manage View section in the $ModelTypes Utilities),
    • assign permission profiles and governance roles to others,
    • save searches and hierarchy views as “default” for a collection.

For a working copy

  • viewer of a working copy can:
    • view and browse it,
    • view reports of changes contained in it,
    • view reports of what other working copies will be affected by changes made as part of this particular workflow,
    • run a report comparing a working copy to the production asset collection,
    • export data to a variety of formats.
  • An editor has all viewer permissions and can also make changes.
  • manager has all editor permissions and can also:
    • control permission privileges to a working copy (i.e., grant viewer/editor/manager roles to users) and
    • if a workflow is based on the Basic template, WF managers can freeze/unfreeze it to prevent/allow changes, e.g., for reviewing, and they can change the status to Approved or Rejected. This is defined in the Basic Workflow template.

Workflow Transitions and Governance Roles

In the Basic Workflow, the state-action transitions (e.g., freezing/resuming, accepting/rejecting, etc.) are defined in terms of the permission profiles: viewer, editor, and manager. Workflow templates also allow workflow transitions to be defined in terms of governance roles (e.g., data steward, subject matter expert, etc.).

Depending on the workflow design, state transitions can also happen automatically e.g., on a timer or as a result of some other event.

Workflow Scope

When you start a workflow, you may be able to select a workflow type from a dropdown if multiple workflow templates are installed in your EDG system. Only workflow types applicable to the workflow context will be available for selection. Otherwise, Basic Workflow is automatically selected.

Workflow templates in EDG can be scoped to be applicable only to a given type of collection or to a given asset type or to a given governance area. This lets users develop different workflows for change management. For example, Review and Approval process for Glossaries can be different from Data Assets.

If no scope is set for a workflow template, it is applicable EDG-wise. The Basic Template has no scope which is why it can be used in all contexts.

 

Workflow Status and Transition Tab

This is the first tab in the horizontal navigation menu. It has a gear icon and contains a name of the workflow and its description. If you have manager privileges you will be able to edit either one by clicking on the text, editing, and confirming by clicking on the edit-box’s check-mark.

The page shows shows the current state of the workflow and a diagram depicting its state transitions. This page also lets a user transition the workflow to the next state. Depending on the current state and the role you play in the workflow process, you may see action buttons for moving the workflow to the next state.

 

The Basic Workflow

 

The standard EDG workflow template includes the Basic workflow, which supports optional review cycles and staging before committing changes to production.

 

 

The Basic workflow’s states and actions (transitions)

Basic WF Status Action

 

Role(s): Graph(s) *

 

Description Resulting Status
Cancel this workflow Manager: either Irrevocably deletes the entire WF N/A

 

Uncommitted

 

(editable)

 

Commit changes to production Editor: Production Applies all WF changes into production Complete
Freeze for review Manager: WF Pauses WF editability Frozen for Review
Frozen for Review Request further changes Editor: WF Resumes WF editability Uncommitted
Reject changes Editor: WF Blocks applying any WF changes into production Rejected
Approve changes  Editor: Production Ends WF editability (staged for production) Approved
Rejected Allow further changes Editor: Prod. & Manager : WF Resumes WF editability Uncommitted
Approved Accept changes to production Editor: Production Applies all WF changes into production Complete
Complete Complete
* All actions require at least viewer permissions on both the production and WF copies.

 

Workflow Templates

This shows the collection of templates that define the available workflow types, e.g., the Basic Workflow. To customize these workflow types externally from EDG (e.g., via TopBraid Composer – Maestro Edition), admin users can download and upload the templates as a Turtle file. For details on developing custom workflows, see EDG Developer Guide: Adding Custom Workflow Templates.

 

Workflows Page (tab) in an Asset Collection

 

The workflows tab allows users to start workflows for a particular asset collection, and it lists both the active and completed workflows, if any in this collection.

Start new Workflow button

This button opens a form for starting a workflow for this collection. If multiple workflow templates (types) are available, select the appropriate one. The new workflow requires a name and allows you to enter an optional description, both of which remain editable by managers.

Users can also create a workflow pertaining to a selected asset (see View or Edit > Actions > Additional asset actions). Such workflows record the identity of the selected asset but are otherwise ordinary.

If you are responsible for transitioning a workflow to the next state, you will also see it listed in the My Workflows page that you can access directly from the left Navigation Bar.

Workflows in Progress

This section lists any active (uncommitted) workflows of the collection. To access a particular workflow, select its row and click Go to Workflow. You will see a page showing you the status of the workflow and, depending on the workflow’s status and your role, allowing you to move the workflow to the next state.

Also depending on workflow’s status and your role, you can view or edit the workflow and view or execute various utility actions on it. A workflow can be used to process changes to multiple assets or changes to one specific asset. Each workflow isolates its changes to its own workflow copy, which does not affect other workflows or the production version, until and unless the workflow is committed back into production.

If the workflow was created for a specific asset, its name will appear in the row. Selecting the row and clicking  Go to Asset will open the asset’s details view, which workflow editors can also modify.

Completed Workflows

This table works similarly to Workflows in Progress except that it lists the workflows that reached the terminal state. Typically, this means that changes have been finalized and committed to the asset collection. Users can view the history of workflow transitions. Each completed workflow shows its number of changed statements (triples), giving users information about the volume of changes made as part of the workflow.

For completed workflows with extensive changes, preserving such history of changed triples might occupy considerable space. Therefore, asset collection managers can select a completed workflow and use the Archive action to remove the audit trail from the change history. The change records are copied into a file in a new project that an administrator can access if the change history details are ever needed again. The only information retained in the audit trail is the transition history of the workflow itself, without any detail of the data changes.

To browse archived files, use the Base URI Management page in the Server Administration area. The files will be located in a project (or folder) called “Archive”. If these are no longer needed you can move them off the server.