create new tag
, view all tags

Automate Workflows with If-Then-Actions

2015-04-30 - 04:28:29 by PeterThoeny in Deployment
TWiki has a new IfThenActionPlugin to automate workflows. Administrators can define if-then actions that are triggered when a topic is viewed or saved, an attachment is uploaded, or a user registers. As an example action, every time a topic is viewed, another topic should be viewed in the background, with the purpose to refresh that other topic's cache.

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

If-then-action rules are defined in a table at IfThenActionRules. For security it is access restricted to members of the TWikiAdminGroup by default. Here is a 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

The if-action is the trigger. Four if-actions are currently implemented:

  • register - take action after successful user registration.
  • 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.

The source is the TopicName or Web.TopicName of the topic that should trigger an action. The if-action on a source topic can be defined dynamically using TWikiVariables such as %IF{}% or %CALCULATE{$IF()}%. The result of the TWiki Variable should be a Web.TopicName if you want to take action on the source topic; or an empty string if you want to cancel the action.

The then-action is the action to take. Five then-actions are currently implemented:

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

Developers can create additional then-actions. For example, a publish then-action could create a styled HTML file from the topic content each time a topic is updated.

The target is the target topic and content to take action on. The format depends on the then-action; in its simplest form it is TopicName. As in the source, the target can be crafted dynamically with a TWiki Variable; to cancel can action, return an empty string. Tokens can be used instead of the topic name, such as $topic to indicate the name of source topic, $parent to indicate the parent of the source topic, or $children to indicate all direct children of the source topic. For details see IfThenActionPlugin documentation.

The syntax of the then-action target differs based on the then-action. For example, the setformfield then-action target looks like $children/$formfield(Status) = $formfield(Status).

To make this more concrete, let's look at some examples of if-then actions that are currently deployed.

1. TWiki application for requirements management using tree hierarchy:

The applications has requirements that are arranged in a tree hierarchy. Requirement topics have sequential names Rqmt-0001, Rqmt-0002, etc. Among other TWikiForms fields, each requirement has a "Status" field.

Need: If a status field at a higher level is updated, all status fields of dependent requirements need to be updated recursively to match the status of the updated topic.

Solution: Define an if-then-action rule to update the Status field of all children topics:

If Source Then Target Comment
save Eng.Rqmt-* setformfield $children(32 Rqmt-*)/$formfield(Status) = $formfield(Status) This updates all children's Status form field to the current topic's Status form field value

2. TWiki application for parts management:

The parts database has 20K parts. Parts topics are named PID-00001, PID-00002, etc. A sales order form has an autoselect field to select a part. That autoselect is too slow if done with a dynamic query on all parts. To get the required performance, we create a PartsData topic to cache the parts data in a format the autoselect JavaScript code can use. The topic has a dynamic query that generates the JSON object needed by autocomplete, and stores it in a persistent SET variable using the latest SetGetPlugin:

%SET{ autocompleteObject = [ %SEARCH{...}% ] store="parts" }%

A named section in PartsData is used to GET the persistent variable:

%GET{ "autocompleteObject" store="parts" }%

This named section in turn can be included to set a partsObject JavaScript object:

  var partsObject = %INCLUDE{ "%WEB%.PartsData" section="autocompleteObject" }%;
  // followed by autocomplete logic

Viewing the PartsData topic (thus updating the cache) is slow, but including the section to get the cached data for the autoselect of the sales order form is fast.

Need: Update the JSON object so that it remains in sync whenever a part topic is updated.

Solution: On save of a part topic, do a topic view on PartsData to refresh the JSON object. The topic view is done asynchronously (e.g. non-blocking) so that the topic save is not slowed down. If-then-action rule:

If Source Then Target Comment
save Parts.PID-* viewdaemon Parts.PartsData This does a non-blocking view on the parts data topic to update the JSON object that is stored in a persistent SET variable

3. Send SMS on suspicious user registration:

Anybody can create an account on TWiki.org. This attracts SEO spammers. Spammers often add link spam for clients located in other countries. For example, a spammer in India, Indonesia, Pakistan, Philippines, Sri Lanka, Ukraine or Vietnam might add spam for a company in Germany or USA. So, we have a potential spammer if someone with a Pakistani IP address registers on TWiki.org, and specifies USA as the country in the registration form. Cleaning up spam quickly is key - before Google indexes the spam. Spammers search for existing spam targets, and you do not want your TWiki site to be a magnet for spammers.

Therefore I defined an if-then action rule to send an SMS to my iPhone if a user registers on TWiki.org, and the country specified in the registration form does not match the country by IP address. Here is the if-then action rule:

If Source Then Target Comment
register %WEB%.%TOPIC% email Main.IfThenActionRegisterSMS Send an SMS if the country in the user's form does not match the country by IP address

The %WEB%.%TOPIC% is generated dynamically:

  $SET(ipCountry, %GEOLOOKUP{ "%REMOTE_ADDR%" format="$country_name" }%)
  $SET(formCountry, %FORMFIELD{Country}%)
  $IF($EXACT($GET(ipCountry), $GET(formCountry)), , %WEB%.%TOPIC%)

We use a CALCULATE to conditionally return an empty string or %WEB%.%TOPIC%, depending if the countries match or not. The GEOLOOKUP looks up the country by IP address, it is handled by the GeoLookupPlugin. The FORMFIELD returns the country in the user's form. We assign the two countries to two variables, then we compare them. If they match, we return an empty string, else we return the Web.TopicName of the registered user.

The IfThenActionRegisterSMS target is the e-mail template that sends the SMS. The e-mail is addressed to the e-mail-to-SMS-gateway of my mobile carrier. Here is an example:

To: 4085551212@vzwpix.com
Subject: [TWiki.org] Registration: Country mismatch

By IP:   %GEOLOOKUP{ "%REMOTE_ADDR%" format="$country_name" }%;
Country: %FORMFIELD{Country}%;
URL:     %SCRIPTURL{view}%/%WEB%/%TOPIC%

Now, whenever a user registers, and the countries do not match, I get a text message. That allows me to quickly take action if a spammer registers.

I hope these examples give you some ideas how to automate your own workflows. What do you have in mind? Please share in the comments below.

-- PeterThoeny - TWiki.org Founder


The plugin now has a new then-action:

  • attachsection - attach 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.

-- Peter Thoeny - 2015-05-29


Edit | Attach | Watch | Print version | History: r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r2 - 2015-04-30 - PeterThoeny

Twitter Delicious Facebook Digg Google Bookmarks E-mail LinkedIn Reddit StumbleUpon    
  • Help
  • 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-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.