• This web contains the official documentation of the TWiki-6.0 Release, code named JerusalemRelease.
• It is a read-only web for reference. Please update documentation at TWiki.IfThenActionPlugin.
Tags:
create new tag
view all tags

If-Then-Action Plugin

diagram.png
Execute if-then actions on topic view, save, file upload, and user registration, with rules defined in a topic

Introduction

This plugin is intended to help automate workflows. Administrators can define if-then actions in a rules table. For example, every time a topic is updated, another topic should be viewed in the background, with the purpose to refresh that other topic's cache.

Description

Administrators define if-then-action rules in a table. The rules have format "if source then target". The "if" is the trigger (if-action), "source" is the source topic, "then" is the action to take (then-action), and target is the target topic to take action on.

Developers can create additional if-actions and then-actions as needed.

To avoid infinite loops, if-then-actions are not recursive. For example, a save if-action does not trigger a new save if-action on a target topic.

If-Then-Action Rules Table

If-then-action rules are defined in a table at Main.IfThenActionRules. By default it is access restricted to members of the TWikiAdminGroup.

Sample table, for illustration:

If Source Then Target Comment
save Sandbox.SourceTopic view Sandbox.TargetTopic This does a normal topic view on the target
register %WEB%.%TOPIC% touch Main.RegisteredUsers This does an edit-save cycle on the target topic on successful user registration

Help on rules table:

  • If: The if-action is the trigger.
    • Currently implemented if-actions:
      • register - take action after successful user registration.
        ALERT! Note: The Source must be set to: %WEB%.%TOPIC%
      • save - take action after saving a topic.
      • upload - take action after uploading a file attachment.
      • view - take action on topic view. The action is triggered at the end of the page rendering process.
    • Note: If-actions can be disabled in configure, some might not be available.
      • Available if-actions: action, register, save, upload

  • Source: Source topic or source condition. Syntax:
    • Specify the Web.TopicName of the topic that should trigger an action, or a comma-space list of topics such as Web1.Topic1, Web2.Topic2.
    • Wildcards can be used for the topic name, such as CID-* to indicate names starting with CID-.
    • A condition can be crafted using TWikiVariables such as %IF{}% or %CALCULATE{$IF()}%.
      • Use %WEB% and %TOPIC% to indicate the source web and topic, respectively.
      • The result of the condition should a Web.TopicName to take action on, a topic list, or an empty string to cancel the action.

  • Then: The then-action is the action taken.
    • Currently implemented then-actions:
      • email - send an e-mail based on an e-mail template topic.
      • setformfield - update a form field of a target topic.
      • touch - edit and save a target topic without making any content change.
      • view - view a topic and wait for the rendering.
      • viewdaemon - view a topic asynchronously, e.g. non-blocking; useful if the topic to view is slow.
    • Note: Then-actions can be disabled in configure, some might not be available.
      • Available then-actions: attachsection, email, setformfield, touch, twikiorgdsp, twikiorgview, view, viewdaemon

  • Target: Target topic and more. Syntax:
    • Web.TopicName of the topic to take action on, or a comma-space list of topics such as Web1.Topic1, Web2.Topic2.
    • The web name is optional; the source web is used if omitted.
    • Tokens can be used instead of the topic name:
      • $topic - name of source topic.
      • $parents - parent trail, up to 64 parents up.
      • $parents(5) - parent trail, up to 5 parents up.
      • $parent - topic parent.
      • $parent(5) - the 5th parent up in the parent trail.
      • $children: expands to all direct children.
      • $children(5): expands to all children recursively 5 levels deep.
      • $children(10 CID-*): expands to all children 10 levels deep, using only topic names starting with CID-* (if possible specify a topic name filter with wildcards for better performance).
    • The then-action is cancelled in case the target topic does not exist, such as if there is no parent when using $parent
    • Example target: Web.SomeTopic, Web.NotExistingTopic, Web.$parent, Web.$children
    • Example output: Web.SomeTopic, Web.ItsParent, Web.ItsChild1, Web.ItsChild2, Web.ItsChild3
    • The target can be crafted dynamically using TWikiVariables such as %FORMFIELD{}% and %CALCULATE{}%.
      • Use %WEB% and %TOPIC% to indicate the source web and topic, respectively.
    • The syntax differs based on the then-action.
      • Example setformfield then-action target: $children/$formfield(Status) = $formfield(Status)

Then-Action: Email

The "email" then-action sends an e-mail based on an e-mail template topic.

Example if-then-action rule:

If Source Then Target Comment
save Sandbox.IfThenActionTest email Sandbox.IfThenActionEmailTemplate This sends an e-mail based on the target template when the source topic is updated

Target syntax:

  • Specify Web.EmailTemplateTopic containing the e-mail template.
  • Tokens such as $parent can be used for the topic name, as documented in the rules table help.
  • Specify %WEB%.%TOPIC% as the Source if you want to get e-mail on every topic save.
  • Format of the e-mail template:
    • Content outside %STARTINCLUDE% and %STOPINCLUDE% is ignored.
    • The template must conform to an e-mail format with e-mail header and e-mail body separated by two newlines.
    • The header must contain at least To: and Subject: fields.
    • Do not specify the From: header field, it is added automatically.
    • TWikiVariables can be used in the e-mail header and body.
  • Example e-mail template:
    The part before STARTINCLUDE is ignored
    %STARTINCLUDE%
    To: %WIKIWEBMASTER%
    Subject: [TWiki Notification] %WEB%.%TOPIC% has been updated

    %WIKINAME% just updated %WEB%.%TOPIC%
    URL: %SCRIPTURL{view}%/%WEB%/%TOPIC%

    This is mail has been sent by TWiki's IfThenActionPlugin
    %STOPINCLUDE%
    The part after STOPINCLUDE is ignored

Then-Action: SetFormField

The "setformfield" then-action updates a form field of a target topic to any value, such as the value of a form field of the source topic.

Example if-then-action rule:

If Source Then Target Comment
save Sandbox.IfThenActionTest setformfield $children/$formfield(Number) = $formfield(Number) This updates all children's Number form field to the current topic's Number form field

Target syntax: target = expression, such as Web.SomeTopic/$formfield(Status) = $children/$formfield(Status)

  • target   - target form field, defined by topic/$formfield(Name):
    • topic   - this is Web.TopicName as described in the rules table help; tokens such as $children can be used.
    • /   - a slash to separate topic and form field.
    • $formfield(Name) - the form field.
  • =   - an equal sign.
  • expression   - either a value, or a source form field of format $formfield(Name) or topic/$formfield(Name):
    • topic   - this is Web.TopicName as described in the rules table help; tokens such as $topic can be used.
    • /   - a slash to separate topic and form field.
    • $formfield(Name)   - the form field.
    • The topic is optional, the source topic is assumed if missing
    • If $formfield(...) is missing, the value is used verbatim - useful if the expression is set dynamically by the result of %SYSTEMWEB.TWikiVariables.

Then-Action: Touch

The "touch" then-action edits and saves a target topic without making any content change.

Example if-then-action rule:

If Source Then Target Comment
save Sandbox.IfThenActionTest touch Sandbox.IfThenActionTouch This does an edit & save of the target topic

Target syntax:

  • Specify Web.TopicName, or a comma-space delimited list, such as Web1.Topic1, Web2.Topic2.
  • Tokens such as $parent can be used as well, as documented in the rules table help.

Then-Action: View

The "view" then-action views a target topic. The primary purpose is to refresh a topic cache, or a persistent SET variable embedded in a topic. The topic is viewed synchronously, e.g. it is blocking until the topic view has rendered.

Example if-then-action rule:

If Source Then Target Comment
save Sandbox.IfThenActionTest view Sandbox.IfThenActionView This does a normal topic view

Target syntax:

  • Specify Web.TopicName, or a comma-space delimited list, such as Web1.Topic1, Web2.Topic2.
  • Tokens such as $parent can be used as well, as documented in the rules table help.

Then-Action: ViewDaemon

The "viewdaemon" then-action views a target topic asynchronously. The primary purpose is to refresh a slow topic that is cached, or has a persistent SET variable embedded in the topic. The topic is viewed asynchronously, or non-blocking, e.g. it does not slow down the current process. It starts a daemon process to handle the topic view, and returns immediately.

ALERT! Restriction: This feature does not work on a native TWiki installation on Windows. It works fine on Linux based TWiki installations, including a TWiki-VM that runs in a VMware environment on a Windows server.

Example if-then-action rule:

If Source Then Target Comment
save Sandbox.IfThenActionTest viewdaemon Sandbox.IfThenActionViewDaemon This does a daemon view, e.g. is non-blocking

Target syntax:

  • Specify Web.TopicName, or a comma-space delimited list, such as Web1.Topic1, Web2.Topic2.
  • Tokens such as $parent can be used as well, as documented in the rules table help.

Info For Developers

You can ignore this section unless you want to enhance the plugin.

IFTHEN Variable

This plugin handles the %IFTHEN{}% variable. At this time it is only used to define the "if" and "then" picklists in the edit table of the if-then-action rules topic:

  • %IFTHEN{if-actions}% - returns the "if-action" list: action, register, save, upload
  • %IFTHEN{then-actions}% - returns the "then-action" list: attachsection, email, setformfield, touch, twikiorgdsp, twikiorgview, view, viewdaemon

NOTE: This defines the edit table format of the if-then-action rules table, DO NOT REMOVE! format="| select, 1, , action, register, save, upload | text, 50 | select, 1, , attachsection, email, setformfield, touch, twikiorgdsp, twikiorgview, view, viewdaemon | text, 50 | text, 50 |"

Then-Action Classes

The then-actions are defined by classes that are auto-discovered. The base class is TWiki::Plugins::IfThenActionPlugin::ThenAction. All then-action classes are located in lib/TWiki/Plugins/IfThenActionPlugin/ThenAction/, such as TWiki::Plugins::IfThenActionPlugin::ThenAction::View for the "view" then-action. The name of the then-action is the lowercase class name. To create a new then-action, clone one of the existing classes.

The Then-Action class has a method to handle the then-action:

$this->handleAction( $web, $topic, $text, $meta, $target )

  • $web: Name of source web
  • $topic: Name of source topic
  • $text: Text of source topic, possibly undef
  • $meta: Metadata of source topic, possibly undef
  • $target: Target string
  • Return: none

The handleAction method is expected to call the expandTopics method to expand topics in the target string. That method returns an array of hash references. Loop through that array to handle all target topics.

$this->expandTopics( $sWeb, $sTopic, $sMeta, $target, $hasAccessor ) -> @webTopics

  • $sWeb: Name of source web, used to normalize the Web.TopicName of the target topic
  • $sTopic: Name of source topic, used to expand tokens
  • $sMeta: Metadata of source topic, used to expand tokens
  • $target: Comma-space list of items with topics & tokens. Topics are normalized to Web.TopicName. Non-existing topics are removed. These tokens are expanded:
    • $topic: name of source topic
    • $parents: parent trail, up to 64 parents up; item is removed if none
    • $parents(5): parent trail, up to 5 parents up; item is removed if none
    • $parent: topic parent; item is removed if none
    • $parent(5): the 5th parent up in the parent trail; item is removed if none
    • $children: expands to all direct children; item is removed if none
    • $children(5): expands to all children recursively 5 levels deep; item is removed if none
    • $children(10 CID-*): expands to all children starting with CID-* recursively 10 levels deep
      Example target: Web.SomeTopic, Web.NotExistingTopic, Web.$parent, Web.$children
      Example output: Web.SomeTopic, Web.ItsParent, Web.ItsChild1, Web.ItsChild2, Web.ItsChild3
  • $hasAccessor: '1' if items may contain accessors like /formfield(Status); accessors are extracted and returned.
    Example: Web.SomeTopic/formfield(Status)
  • Return: @webTopics: Array of hash references Example: ( { w => 'web1', t => 'topic1', a => 'formfield(Status)' }, { w => 'web2', t => 'topic2', a => '' }, ... )

Plugin Installation & Configuration

You do not need to install anything on the browser to use this plugin. These instructions are for the administrator who installs the plugin on the TWiki server.

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip IfThenActionPlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/IfThenActionPlugin.txt Plugin topic
      data/TWiki/IfThenActionRulesTemplate.txt If-then-action rules template topic
      data/Sandbox/IfThenActionEmailTemplate.txt E-mail template test topic
      data/Sandbox/IfThenActionForm.txt Test topic
      data/Sandbox/IfThenActionSetFormField.txt Test topic
      data/Sandbox/IfThenActionTest.txt Test topic
      data/Sandbox/IfThenActionTouch.txt Test topic
      data/Sandbox/IfThenActionView.txt Test topic
      data/Sandbox/IfThenActionViewDaemon.txt Test topic
      pub/TWiki/IfThenActionPlugin/diagram.png Image file
      lib/TWiki/Plugins/IfThenActionPlugin.pm Plugin Perl module
      lib/TWiki/Plugins/IfThenActionPlugin/Config.spec Configuration spec file
      lib/TWiki/Plugins/IfThenActionPlugin/Core.pm Plugin core module
      lib/TWiki/Plugins/IfThenActionPlugin/ThenAction.pm Then-action base class
      lib/TWiki/Plugins/IfThenActionPlugin/ThenAction/SetFormField.pm Then-action "setformfield" class
      lib/TWiki/Plugins/IfThenActionPlugin/ThenAction/Touch.pm Then-action "touch" class
      lib/TWiki/Plugins/IfThenActionPlugin/ThenAction/View.pm Then-action "view" class
      lib/TWiki/Plugins/IfThenActionPlugin/ThenAction/ViewDaemon.pm Then-action "viewdaemon" class
    • Set the ownership of the extracted directories and files to the webserver user.

  • Plugin configuration:
    • Run the configure script and enable the plugin in the Plugins section.

  • Test if the configuration is successful:

Plugin Info

  • Set SHORTDESCRIPTION = Execute if-then actions on topic view, save, file upload, and user registration, with rules defined in a topic

Author: TWiki:Main.PeterThoeny, TWiki.org
Copyright: © 2015 Alba Power Quality Solutions.
© 2015 Wave Systems Corp.
© 2015 TWiki:Main.PeterThoeny
© 2015 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Sponsor: Alba Power Quality Solutions; Wave Systems Corp.
Version: 2015-04-20
2015-04-20: TWikibug:Item7630: Small code change
2015-04-16: TWikibug:Item7630: New "view" if-action on topic view; check access permission in "setformfield" and "touch" then-actions; ability to disable if-actions and then-actions
2015-04-15: TWikibug:Item7630: New "email" then-action to send an e-mail based on a template; new "register" if-action on user registration; the Source field in the If-Then-Action Rules Table can be a Web.TopicName, or a list of topics
2015-04-08: TWikibug:Item7630: Expand TWiki Variables in Source and Target; support any value (not just $formfield(...)) in a setformfield expression; prevent recursive if-then-actions, e.g. a save action does not trigger another save action
2015-04-06: TWikibug:Item7630: New "setformfield" then-action to update a form field of a target topic; new "touch" then-action to edit & save a target topic; use login user for "view" and "viewdaemon" then-actions; add configure spec
2015-04-05: TWikibug:Item7630: Expand tokens $children, $children(n), $children(n CID-*) in target
2015-04-04: TWikibug:Item7630: Expand tokens $parents, $parents(n), $parent, $parents(n) in target
2015-04-03: TWikibug:Item7630: Possible to specify a comma-space list of topics as the target; add support for "upload" if-action; improve developer docs
2015-04-02: TWikibug:Item7630: Initial version of IfThenActionPlugin
TWiki Dependency: $TWiki::Plugins::VERSION 1.2, BackupRestorePlugin, SetGetPlugin, SpreadSheetPlugin (all plugins are pre-installed)
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.008
Plugin Benchmark: GoodStyle nn%, FormattedSearch nn%, IfThenActionPlugin nn%
Home: http://TWiki.org/cgi-bin/view/Plugins/IfThenActionPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/IfThenActionPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/IfThenActionPluginAppraisal

Related: IfThenActionRulesTemplate, IfThenActionTest, IfThenActionEmailTemplate, IfThenActionForm, IfThenActionSetFormField, IfThenActionTouch, IfThenActionView, IfThenActionViewDaemon, TWikiPlugins

Topic revision: r0 - 2015-04-20 - TWikiContributor
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.IfThenActionPlugin.