Username Password
Bookmark and Share


The WebGUI workflow system controls the flow of content through the system. Because the workflow is customizable, you can control what actions are performed, and when those actions take place. Sometimes viewing an existing workflow on the site helps envision how all the activities come together.

To view current workflows in the system, select Workflow from the Admin Console. This will open the “Manage Workflows” screen.


This screen contains the name of each existing workflow, an indication whether the workflow is currently enabled, and icons to delete or edit each workflow. To edit an existing workflow, simply click on its edit button. This will open the “Edit Workflow” screen.

At the top of the screen is the “Workflow ID.” This is a unique identifier generated by WebGUI at the time of workflow creation. Next is the “Object Type.” In this case, it is WebGUI::Version Tag, which means this workflow can be applied to version tags. The “Title” is simply the name of the workflow, and the “Description” field contains an explanation of the workflow’s function. The “Is Enabled?” toggle indicates if the workflow is enabled for use.

The “Mode” field currently has four options: Serial, Parallel, Realtime, and Singleton.

  • Serial means that if multiple instances of this workflow are created they will be executed one at a time in order. The first in line will be executed, then the next, and so on. This will be executed behind the scenes as the workflow engine has the time and resources to complete the tasks. An example for this workflow mode is checking an email box. If the workflow instances were allowed to execute in a parallel fashion then we might download the same message multiple times. By keeping it serial we will get exactly one copy of each email message.

  • Parallel means that multiple instances of this workflow will all be executed simultaneously. This will be executed behind the scenes as the workflow engine has the time and resources to complete the tasks. An example for this workflow mode is content publishing. We want our content published as quickly as possible, we don't care about publishing in the order the content was committed.

  • Realtime means that this workflow will be executed while the user waits, instead of letting the workflow engine execute it when it has time and resources. This can be dangerous if the workflow takes a long time to complete because the user may believe that the process has stalled and may refresh their browser, or leave before the process is done. However, from a user's perspective there is also “instant gratification” because whatever work they were expecting to be done, will be done right then and there. An example of this mode is also content publishing, but only if there is no approval process.

  • Singleton means that multiple instances of this workflow will not be allowed. If one instance already exists and another is created, the second will be discarded. This will be executed behind the scenes as the workflow engine has the time and resources to complete the tasks. An example of this mode is sending out email. We know we want to send out all of our email messages. We also know we are going to try to send out messages every X minutes, so we don't ever need more than one process sending out the messages.



At the bottom of the screen are listed a number of links. These links indicate activities that can be added to the workflow. Simply click on a link, add the appropriate information and save it to the workflow.

The activities listed in black are already part of the workflow. Next to these are icons that allow you delete an activity, edit it, or change its position in the order of performance.


Note: If someone performs an action on the web site that uses this workflow while it is being edited, the system will use an instance of the workflow that mirrors it as it is being edited. Because of this, the content may not move through the system as expected. Therefore, you should always disable a workflow before editing it, and re-enable the workflow when you're done editing.


Add a Workflow

  1. To add a new workflow, click on the “Add a new worfklow” link on the far right hand side of the “Manage Workflows” screen. In this example a workflow will be added that commits a version tag on a specific date, in this case the day the workflow is created.

  2. In the “Add a New Workflow” screen, select the “Object Type” the workflow will be applied to. “No Object” includes maintenance tasks like decaying karma and cleaning the file cache. “WebGUI::User” applies to a user; “WebGUI::VersionTag” applies to version tags.

  3. Click save.

  4. The “Edit Workflow” screen will appear.


  1. Enter a title for the workflow in the “Title” field.

  2. Enter a description of the workflow’s function in the “Description” field.

  3. Set the “Is Enabled?” toggle to Yes.

  4. Select an activity to include in the workflow from the links at the bottom of the screen. In this example, ”Create a Scheduled Event” was selected.

  5. A screen will open on which to enter information about the workflow activity you selected. This screen and its fields will differ depending upon which activity you selected.


  1. You can give the activity a title and enter text in the description field explaining the activity's purpose.

  2. Toggle the “Is Enabled?” field to Yes (default setting is No).

  3. If the “Run Once?” field is toggled to Yes this task will execute at the scheduled time and then delete itself.

  4. Next, select a workflow from the “Workflow” dropdown menu. This indicates the workflow you want to run at the time the event is scheduled. In this example, Commit Without Approval.


  1. In the “Priority” field select the option that best indicates the priority of this activity; the higher the priority the faster the activity will be performed.

  2. Set the time and date fields to indicate when the event should occur.

  3. Click save. You will be returned to the “Edit Workflow” screen where you will notice the task now added to the workflow. This appears at the bottom of the screen in black, with a number of editing icons. You will also see it added on the “Manage Workflows” screen.



Now, you can assign this workflow when manually creating a version tag, or you can edit an existing version tag and assign a workflow to it. To do this, select Version Tags from the Admin Console, and click on the edit button next to the version tag you would like to assign this workflow to in the “Edit Version Tag” screen. This will open a screen from which you may select the appropriate workflow. Also, the workflow can be assigned globally so that any new version tags created will have this workflow applied. To assign the workflow globally, select Settings from the Admin Console and alter the “Default Version Tag Workflow” field. This is where you assign the workflow to be executed on all version tags in the system.


Examples of Workflows

The Object Type you select in the “Add a New Workflow” screen will determine the list of available tasks to add to a workflow in the “Edit Workflow” screen.


Object Type: No Object



Available Workflow Tasks:

  • Decay Karma: allows you to set the minimum value a user's karma can decay to, and how many points of karma will be removed when the workflow runs.

  • Empty Clipboard to Trash: allows you to establish a length of time content is allowed to sit in the Clipboard before the system removes it to the trash.

  • Clean Temp Storage: allows you to set an amount of time to pass before temp files are cleared from the system.

  • Clean File Cache: allows you to set how big the file cache can get before WebGUI begins pruning old cache entries.

  • Clean Login History: allows you to set an amount of time to pass before WebGUI will begin deleting entries in the Login History.

  • Archive Old Threads: when this task is run old threads, based on each Collaboration System's settings, will be archived.

  • Trash Expired Events: allows you to set an interval of time to pass before an event in the Calendar is moved to the trash. The default interval is 30 days.

  • Create a Scheduled Event: allows you to schedule an event in the system for a specific date and time; an example would be to schedule a version tag to be committed at specific date and time.

  • Delete Expired Sessions: this workflow deletes expired sessions.

  • Expire User Groupings: this workflow activity will go through all groups and handle group expiration notifications and deletions. For example, if a group expiration notificaiton has been set up, this workflow activity will send out the appropriate emails to group members to alert them of the upcoming expiration. Once the group's delete offset has passed, this workflow activity will delete users from the group.

  • Purge Old Asset Revisions: this workflow activity allows you to set an amount of time to pass before WebGUI will delete versions of assets stored in the Versioning system. The default setting in WebGUI is to delete versions of assets older than one year.

  • Expire Subscription Codes: this activity will go through all subscription codes and expire any subscription code that is unused after the expiration date has passed.

  • Purge Old Trash: allows you to set a length of time to pass before assets are deleted from the Trash. WebGUI's default setting is to purge assets from the Trash after 30 days.

  • Get Syndicated Content: allows the Syndicated Content asset to serve pages more quickly by pre-fetching syndicated content URL's.

  • Process Recurring Payments: this activity will process all recurring payment transactions in the Commerce system. When the activity is finished, an email with the details of those transactions is sent to the user assigned in the Settings to receive such information.

  • Sync Profiles to LDAP: this activity will synchronize the profiles of all users configured for LDAP authentication (this runs from LDAP to WebGUI).

  • Summarize Passive Profile Log: summarizes passive profiling data for all registered users and then deletes the log.

  • Send Queued Mail Messages: processes queued emails. This activity will only run in one minute intervals.

  • Clean Database Cache: prunes the size of a database cache based on the user configured cache size and the expiration time of items in the cache. If pruning expired items does not reduce the size of the cache to the value configured by the user, then the expiration time will be increased by 30 minutes and the process will repeat until it meets the size requirement.

  • Update Calendar Feeds: fetches iCal feeds for the Calendar asset.


Object Type: WebGUI::User

Available Workflow Tasks:

  • Create a Scheduled Event: allows you to schedule an event in the system for a specific date and time; an example would be to schedule a version tag to be committed at specific date and time.

  • Notify About User: sends out an email about a user.



Object Type: WebGUI::Version Tag

Available Workflow Tasks:

  • Commit Version Tag: this activity commits a version tag; in a workflow dealing with committing version tags, this should be last activity.

  • Rollback Version Tag: rolls back a version tag, effectively eliminating all versions of assets contained in that tag.

  • Trash Version Tag: moves all assets contained within a version tag to the trash; after this is done, the tag is locked.

  • Create a Scheduled Event: allows you to schedule an event in the system for a specific date and time; an example would be to schedule a version tag to be committed at specific date and time.

  • Unlock Version Tag: unlocks a locked version tag so assets can be edited; usually this is used to unlock a committed tag that was rejected in an authorization process.

  • Notify About Version Tag: sends out an email containing information about a version tag. The message contains text input when setting up this activity as well as the URL to the first asset in the tag.

  • Request Approval for Version Tag: sends out an email to all members of a selected group. The email contains any comments input by commiter as well as the URL to the first asset in the tag. The first user to respond to the email can either approve or deny the commit. If the tag is approved, the tag will be committed, if denied it will move on to the next assigned workflow task.

  • Export Version Tag to HTML: exports each asset contained within a version tag to HTML.



The Scheduler allows you to customize the date and time tasks on the site take place. To access the Scheduler, click on its icon in the Admin Console. This will open the “Scheduler” screen.


On this screen are listed all currently scheduled tasks in the system, the time they are scheduled to run, and whether or not they are currently enabled. To the left of each scheduled task is a toolbar that allows you to either delete or edit a task.

If the edit button of a task is clicked, the main screen for that task will open.


The Title field contains the name of this task. In this example, the Is Enabled? field is currently toggled to Yes, meaning that the task is enabled and the workflow will be performed at the scheduled time. If the Run Once? field is toggled to Yes then the event will run at its scheduled time then retire; however, if set to No it will run as often as scheduled. The Workflow field indicates the workflow that will be performed at the scheduled time. The Priority field allows you set the level of priority this task holds; if several tasks are scheduled to perform at the same time, the higher priority tasks will run first. The remaining fields are used to set the minute, hour, day, month and week this task will be performed. If an asterisk( *) is entered for the day field this task will run at the scheduled time every day. Likewise for the month and week fields.

To add a new task to the Scheduler, click on the Add a new task link on the far right hand side of the screen. A blank Scheduler screen will appear, with the same fields as the example above. Simply enter your settings and click save. Upon saving you will be returned to the main Scheduler screen where your new scheduled task will be added to the list.


Workflow Engine

It's one thing to know how to use WebGUI Workflow, it's quite another to understand the engine that drives the whole thing. But if you know how it works, you can use it better, and troubleshoot problems better.

WebGUI's workflow engine is actually two systems, the first is WebGUI itself, the second is a governing application called Spectre. The diagram below shows a very high level view of this process. The components on the left are Spectre, and the components on the right are WebGUI.



Unfortunately, it's all a bit more complicated than that simple diagram. The next diagram shows the workflow engine in it's complete detail. It's too big to read like this, so we'll break it down section by section as we proceed.



Let's start by looking at what happens when Spectre first starts up.


Spectre starts and binds to an IP address so that WebGUI can communicate with it. Then it loads the site configs, and continues loading them until there are no more to load.


Workflow Governor

Then Spectre starts the workflow governor. And starts checking to see if it has any workflows to run. Note that it also checks that it's not running more than the maximum number of workflows; it doesn't want to overwhelm WebGUI. When it determines that there is a workflow to run, and that there's room to run it, Spectre will send the workflow off to WebGUI to be run.



When WebGUI receives the request from Spectre, it first validates that the request is genuine and not from a hacker. It also checks to make sure that you or another admin have not disabled the workflow; there's no sense in running a workflow that's disabled. It will then load the next activity module in the workflow and run it. There are four possible outcomes from this:

    1. done – This means that the workflow has executed all of it's activities successfully, and no longer needs to be run.

    2. complete – This means that a single activity has completed successfully, and that the workflow governor may request that the next activity be run.

    3. waiting – This means that the activity either ran out of time trying to complete it's work, or it's waiting on some external input; perhaps it's waiting on a user to approve some content. Either way, it tells the workflow governor that it needs to run this activity again later.

    4. error – This means that the workflow activity could not complete it's task. It could just be a network hiccup, but it also might be something more serious. The workflow governor will wait a while and try to run it again to see if the error goes away.


After execution is complete, WebGUI hands the result back to Spectre. Spectre doesn't return the workflow to it's in-memory queue if the workflow is “done”, but otherwise it does so that the workflow can be executed again until it's done.



Schedule Governor (Cron)

A very similar process to the workflow startup happens when the scheduler starts up. It begins checking it's newly loaded schedules to see if any of them match the current time. It checks every schedule once per minute to find a match. If it finds a match, it then triggers a process to create a new workflow instance by contacting WebGUI.



Once the scheduler has found a task that's ready to run, it sends it off to WebGUI, where WebGUI does the same validation process it does when the workflow governor sends over a workflow to execute. WebGUI then attempts to create a new workflow activity based upon the data it has. It then can return one of two status codes:

  1. success – When the workflow is created.

  2. error – When something bad happens. This can only really happen under two circumstances. The first is if there was some sort of network connectivity problem. The second is if there is some configuration problem or data corruption with the task and the workflow instance it's supposed to create.


Keywords: cron scheduler spectre version version tag workflow

Search | Most Popular | Recent Changes | Wiki Home
© 2022 Plain Black Corporation | All Rights Reserved