Note: You are currently viewing documentation for Moodle 3.7. Up-to-date documentation for the latest stable version of Moodle may be available here: The OU workflow system.

The OU workflow system: Difference between revisions

From MoodleDocs
No edit summary
No edit summary
Line 68: Line 68:


===What happens at the end of the workflow===
===What happens at the end of the workflow===


===Automatic script actions===
===Automatic script actions===
There are two scripts associated with each task. The '''On step activation''' script is always run when the step starts. The '''On completion step''' script only runs if the step finishes normally with someone clicking the finish step button. This distinction is subtle, but important.
Any line of the script that starts with a # character is considered to be a comment and ignored. You are encouraged to use comments to document what your script does.
Remaining lines are commands, which are a sequence of words separated by spaces. The first word on the line determines which command this is. The meaning of the remaining words depends on the type of command. The available commands are:
; email {templatename} to {role1} {role2} ...
: Sends an email to all the users with any of these roles in the context the workflow applies to. If a user has multiple roles, they only get one email. templatename refers the shortname of one of the email templates that has been defined.
; assignrole {newrole} to {role1} {role2}
: This assigns the new role to any user who has any of the other roles in this context (not parent contexts), and who does not already have newrole in this context. The roles are identified by their shortnames.
; setactivityvisibility {hidden|visible}
: sets the course_module.visible column to 0 or 1 as appropriate. Can only be used in activity workflows.
; setcoursevisibility {hidden|visible}
: sets the course.visible column to 0 or 1 as appropriate. Can only be used in course workflows.
; override {role} {inherit|allow|prevent|prohibit} {capability} in {course|activity}
: sets a role override. The role is identified by its shortname. In course workflows, only course can be used as the last word. In activity workflows, either course or activity can be used.
; setactivitysetting {column} to {value}
: This can only be used in activity workflows. Sets that column in the module’s table, for example in the quiz table. value has to be a fixed value, and (at least at present) only values that are a single word need to be supported. (The word may be a number or a string.)
; setactivitylinkedsetting {tablename} by {foreignkeycolumnname} clear
; setactivitylinkedsetting {tablename} by {foreignkeycolumnname} set {field1} {value1} {field2} {value2} ...
: This one is quite complex. See https://github.com/moodleou/moodle-block_workflow/blob/master/classes/command_setactivitylinkedsetting.php#L28 for more.


===Email templates===
===Email templates===


These are used by the <tt>email</tt> script command. Each template has a shortname, which is how the email command refers to it. They also have a subject and a message body.
The subject and the message body can contain the following tokens, which are replaced the the appropriate value:
; %%workflowname%%    : the name of this workflow.
; %%stepname%%        : the name of the current workflow step.
; %%contextname%%    : the name of the context the workflow applies to. For example “Course B747-11B” or “Quiz iCMA41”. For courses, that is using the course shortname. For activities, it is using the activity name.
; %%contexturl%%      : the URL of the course of activity that this workflow relates to.
; %%coursename%%      : for course workflows, this is the same as %%contextname%%. For activity workflows, it is “Course B747-11B” with the applicable course shortname.
; %%usernames%%      : a comma-separated list of all the users who will be receiving this email.
; %%currentusername%% : the name of the user who triggered the action that lead to this email being sent.
; %%instructions%%    : the instructions for the current step.
; %%tasks%%          : the list of tasks for the current step.
; %%comment%%        : when executing the onactivescript this is set to the comment from the step that was just completed. When executing the oncompletescript, this is set to the comment from this step. If the comment is blank, this is set to ‘[none]’.
So, a typical email template for an On step activation email might look like:
; Subject : Please do workflow step %%stepname%% for %%contextname%%
; Message
: Dear %%usernames%%,
: You are responsible for performing the workflow step %%stepname%% as part or workflow %%workflowname%% for %%contextname%%.
: The step instructions are:
: ---------------------------------------------------------------------
: %%instructions%%
: ---------------------------------------------------------------------
: To perform this step, please go to <%%contexturl%%>
: The people working on the previous step left the comment:
: ---------------------------------------------------------------------
: %%comment%%
: ---------------------------------------------------------------------




Line 80: Line 139:


The system will only let you delete a workflow that it not used anywhere, so instead of deleting a workflow, you may prefer to hide it using the 'eye-con'. If a workflow is hidden, then it will go on working in any place where it is used, but you will not be able to start using it in any new place. In other words, the workflow will be hidden from the list available when you select the workflow to add to a course or activity.
The system will only let you delete a workflow that it not used anywhere, so instead of deleting a workflow, you may prefer to hide it using the 'eye-con'. If a workflow is hidden, then it will go on working in any place where it is used, but you will not be able to start using it in any new place. In other words, the workflow will be hidden from the list available when you select the workflow to add to a course or activity.


==Importing and exporting workflows==
==Importing and exporting workflows==

Revision as of 12:51, 24 August 2012

The Workflow system is used at the OU to manage the production of courses and some activities. It comprises a block and a related admin report.

Overview

A workflow (for our purposes) is a linear sequence of steps. A step has

  • a name
  • some instructions;
  • a check-list of actions;
  • a list of roles who are responsible for performing this step;
  • a list of actions that are taken automatically when the step is started/finished, for example assigning roles or changing activity settings.

The system allows the definition of different workflows. Each workflow has

  • a name
  • a description
  • an indication of the type of thing it relates to (e.g. ‘course’, ‘mod_quiz’)

Under Admin -> Plugins -> Blocks -> Workflow, there is an interface for Administrators to define and edit workflows, and to import and export workflow definitions as XML.

To use a workflow to manage the production of, say, a course, you go to the course, and add a workflow block to it. Initially, the block will display a message “There is currently no workflow associated with this course.” with an Add workflow button. Clicking the button allows you to select from any of the workflows that are appropriate for ‘course’.

When the workflow is added to the course, the first step in the workflow becomes active. The workflow block now displays the step instructions for the currently active step; the checklist items as a list of check-boxes; a comments area; a Finish step button; and a link to the workflow overview.

When a step becomes active, all the people responsible for completing the step are sent an email informing them that they should do the step. These people may also get an additional role assigned to them in the context the workflow applies to.

The comments area in the workflow block is a simple editable text area where people working on the step can leave notes for each other.

The Finish step button leads to a confirmation page. If the action is confirmed, then the workflow advances to the next step. When the last step of the workflow is finished, the workflow either stops, or loops back to one of the other steps.

The workflow overview gives an overview of all the steps in this workflow, and the progress through it. The system tracks the timestamp, and the user, each time a step is finished or made active.

The overview page also allows workflow administrators (those with an appropriate capability) to jump the workflow to any particular step.

There is also a report that summarise the workflow across a selection of courses or activities.


Setting up a workflow

Before you can use the workflow system, you have to create a workflow. To set up workflows, you need to go to Admin -> Plugins -> Blocks -> Workflows.


Creating a workflow

To create a workflow, click on the 'Add workflow' icon at the bottom of the 'Manage Workflows' section of the page. This takes you to the Add workflow form.

Like with Roles, you need to give your workflow both an internal 'Short name' and a human-readable name. It is a good idea to use the description to explain what this particular workflow is for.

You need to specify what type of thing the workflow applies to, either a course, or a type of activity.

Finally, you can say whether they workflow is available for use yet. You should probably leave the 'Current status' as 'Disabled' until you have finished building the workflow.

Once you have got this far, click Save changes.


Adding steps to a workflow

Once the workflow is created, you are taken to a page where you can edit this list of steps in the workflow.

The newly created workflow will have one step already. Click the edit icon by that step, to see what you can change.

You can edit the Steps name, and instructions, and you should probably do that.

The 'On step activation' and 'On step completion' boxes let you cause things to happen automatically when a step starts or finishes. This is an advance feature,


Defining the list of tasks for a step

What happens at the end of the workflow

Automatic script actions

There are two scripts associated with each task. The On step activation script is always run when the step starts. The On completion step script only runs if the step finishes normally with someone clicking the finish step button. This distinction is subtle, but important.

Any line of the script that starts with a # character is considered to be a comment and ignored. You are encouraged to use comments to document what your script does.

Remaining lines are commands, which are a sequence of words separated by spaces. The first word on the line determines which command this is. The meaning of the remaining words depends on the type of command. The available commands are:

email {templatename} to {role1} {role2} ...
Sends an email to all the users with any of these roles in the context the workflow applies to. If a user has multiple roles, they only get one email. templatename refers the shortname of one of the email templates that has been defined.
assignrole {newrole} to {role1} {role2}
This assigns the new role to any user who has any of the other roles in this context (not parent contexts), and who does not already have newrole in this context. The roles are identified by their shortnames.
setactivityvisibility {hidden|visible}
sets the course_module.visible column to 0 or 1 as appropriate. Can only be used in activity workflows.
setcoursevisibility {hidden|visible}
sets the course.visible column to 0 or 1 as appropriate. Can only be used in course workflows.
override {role} {inherit|allow|prevent|prohibit} {capability} in {course|activity}
sets a role override. The role is identified by its shortname. In course workflows, only course can be used as the last word. In activity workflows, either course or activity can be used.
setactivitysetting {column} to {value}
This can only be used in activity workflows. Sets that column in the module’s table, for example in the quiz table. value has to be a fixed value, and (at least at present) only values that are a single word need to be supported. (The word may be a number or a string.)
setactivitylinkedsetting {tablename} by {foreignkeycolumnname} clear
setactivitylinkedsetting {tablename} by {foreignkeycolumnname} set {field1} {value1} {field2} {value2} ...
This one is quite complex. See https://github.com/moodleou/moodle-block_workflow/blob/master/classes/command_setactivitylinkedsetting.php#L28 for more.


Email templates

These are used by the email script command. Each template has a shortname, which is how the email command refers to it. They also have a subject and a message body.

The subject and the message body can contain the following tokens, which are replaced the the appropriate value:

%%workflowname%%
the name of this workflow.
%%stepname%%
the name of the current workflow step.
%%contextname%%
the name of the context the workflow applies to. For example “Course B747-11B” or “Quiz iCMA41”. For courses, that is using the course shortname. For activities, it is using the activity name.
%%contexturl%%
the URL of the course of activity that this workflow relates to.
%%coursename%%
for course workflows, this is the same as %%contextname%%. For activity workflows, it is “Course B747-11B” with the applicable course shortname.
%%usernames%%
a comma-separated list of all the users who will be receiving this email.
%%currentusername%%
the name of the user who triggered the action that lead to this email being sent.
%%instructions%%
the instructions for the current step.
%%tasks%%
the list of tasks for the current step.
%%comment%%
when executing the onactivescript this is set to the comment from the step that was just completed. When executing the oncompletescript, this is set to the comment from this step. If the comment is blank, this is set to ‘[none]’.

So, a typical email template for an On step activation email might look like:

Subject
Please do workflow step %%stepname%% for %%contextname%%
Message
Dear %%usernames%%,
You are responsible for performing the workflow step %%stepname%% as part or workflow %%workflowname%% for %%contextname%%.
The step instructions are:
---------------------------------------------------------------------
%%instructions%%
---------------------------------------------------------------------
To perform this step, please go to <%%contexturl%%>
The people working on the previous step left the comment:
---------------------------------------------------------------------
%%comment%%
---------------------------------------------------------------------


Managing workflows

On the main manage workflows page, as you might expect, you can edit or delete any workflow.

The system will only let you delete a workflow that it not used anywhere, so instead of deleting a workflow, you may prefer to hide it using the 'eye-con'. If a workflow is hidden, then it will go on working in any place where it is used, but you will not be able to start using it in any new place. In other words, the workflow will be hidden from the list available when you select the workflow to add to a course or activity.


Importing and exporting workflows

On the manage workflows page, you can export any workflow to an XML file, and import a workflow from an XML file. The import/export automatically includes all the necessary email templates.


Using the workflow system

For definiteness, in this section, I will talk about using a workflow on a course. Using a workflow on an activity is very similar, you just add the block in a different place.

Adding a workflow to a course

On the course page, turn editing on. Then do Add a block -> Workflow. That adds the workflow block, but it does not yet add a workflow. The block will be showing

The list of tasks

Using comments

The workflow overview

The workflow report

See also