Tags:
admin_tool1Add my vote for this tag automation1Add my vote for this tag component1Add my vote for this tag workflow1Add my vote for this tag 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:
      • action - take action on a %IFTHEN{ "action" }% variable.
        • The variable takes an optional topic parameter to overload the current topic, such as: %IFTHEN{ "action" topic="Web.TopicName" }%.
      • 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: 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:
      • attachsection - attach the content of a section as a file attachment.
      • 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 view of the target topic is slow.
    • Note: Then-actions can be disabled in configure, some might not be available.
      • Available then-actions: 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: AttachSection

The "attachsection" then-action attaches the content of a section in a source topic as a file attachment to a target topic. Use this to generate style sheets (.css files) and other files from topic content. TWiki variables are expanded. Leading and trailing newlines are removed except for one trailing newline.

Example if-then-action rule:

If Source Then Target Comment
save Sandbox.StyleSheets attachsection $topic/*.css Attach the content of all sections where the name ends in .css as file attachments to the same topic

Target syntax:

  • Specify Web.TopicName/section, or a comma-space delimited list, such as Web1.Topic1/section, Web2.Topic2/section.
  • Tokens for topic names such as $topic can be used as well, as documented in the rules table help.
  • The section is the name of a section; wildcards can be used, such as *.css to indicate all section names ending in .css.

1. Create a topic, such as Sandbox.TestAttachSection, and add this content:

<verbatim>
%STARTSECTION{"helloworld.css"}%
.helloWorld {
  color: red;
  background-color: #eee;
  border: dotted gray 1px;
  padding: 3px 8px;
}
%ENDSECTION{"helloworld.css"}%
</verbatim>

Test:
%ADDTOHEAD{
 "helloWorld"
 text="<style type='text/css' media='all'>
@import url('%ATTACHURLPATH%/helloworld.css');
</style>"
}%
<span class="helloWorld">
Hello World
</span>

2. Add an if-then-action rule to the rules topic:

If Source Then Target Comment
save Sandbox.TestAttachSection attachsection $topic/helloworld.css Attach the content of the helloworld.css section as a file attachment of the same name to the current topic

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 TWikiVariables.

ALERT! Known limitation: The plugin does not check for validity of the form field value. For example, it is possible to set an empty value even if the field has the mandatory flag set. Or, it is possible to set an arbitrary value for a select field that is not in the list of options. Therefore make sure to validate the value before setting a form field.

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: register, save, upload
  • %IFTHEN{then-actions}% - returns the "then-action" list: 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, , register, save, upload | text, 50 | select, 1, , 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, start by cloning 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. The following 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-05-25
2015-05-25: TWikibug:Item7630: New "attachsection" then-action to attach the content of a section as a file attachment
2015-05-02: TWikibug:Item7630: New "action" if-action on IFTHEN{action} variable
2015-04-23: TWikibug:Item7630: Update diagram
2015-04-21: TWikibug:Item7630: Add ifthenaction log entries in TWiki logs
2015-04-20: TWikibug:Item7630: Small code change; doc fixes
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 attachments
I Attachment History Action Size Date Who Comment
Unknown file formatmd5 IfThenActionPlugin.md5 r25 r24 r23 r22 r21 manage 0.2 K 2015-05-26 - 05:03 PeterThoeny  
Compressed Zip archivetgz IfThenActionPlugin.tgz r25 r24 r23 r22 r21 manage 49.1 K 2015-05-26 - 05:03 PeterThoeny  
Compressed Zip archivezip IfThenActionPlugin.zip r25 r24 r23 r22 r21 manage 64.3 K 2015-05-26 - 05:03 PeterThoeny  
Unknown file formatEXT IfThenActionPlugin_installer r4 r3 r2 r1 manage 4.4 K 2015-05-26 - 05:03 PeterThoeny  
Edit | Attach | Watch | Print version | History: r20 < r19 < r18 < r17 < r16 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r20 - 2015-05-26 - PeterThoeny
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2016 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.