XmlRpcPlugin

Make XML RPC calls to remote web services.

Introduction

This plugin allows to make XML RPC (eXtensible Markup Language Remote Procedure Call) on the TWiki server to remote web services when rendering a topic. The result of the call is displayed in the topic or can be further processed by other macros. The necessary parameters are the URL of the XML RPC server, the name of the function and its parameters in JSON format. If the result is an object, it is returned in JSON format too. Since the call happens through the network, it can cause significant delays in rendering the topic, but without any I/O or CPU load on the TWiki server. A configurable timeout protections is available. A file based cache is also implemented to speed-up rendering of previously visited pages. A list of allowed domains to connect to can be specified by the administrators.

Syntax Rules

%XMLRPC{"..."}%

Parameter	Explanation	Default
"..."	The default parameter contains the required function call in the format "functionName(JSONpar1, JSONpar2, ...)". The parameters must follow the JSON format, but note that single quotes are allowed instead of double.	(none)
url="..."	The URL of the XML RPC web service.	URL preference
select="..."	If the result is an object, this option allows to select a particular member of the object with the notation "property", or "[arrayIndex]", or "property.[arrayIndex]...".	""
if_fails="..."	If the call fails for whatever reason, return the value of this parameter. Can be used as a default return value.	""
requires="..."	If this arguments evaluates to false in Perl, returns the if_fails value. Useful to avoid unnecessary calls when the arguments are not meaningful.	1 (true)
timeout="..."	The call timeouts and fails after the specified number of seconds.	TIMEOUT preference or 10
expires_in="..."	Duration after which the cache is invalid and the age above which the cache is invalid. Specified in the format of the Time::Duration::Parse Perl module.	EXPIRES_IN preference or 1 year

Caching is done separately for each occurrence of the XMLRPC variable with a key based on the function name, it's parameters and the URL. To force cache refresh of all XMLRPC variables in a topic, add the ?xmlrpc=refresh parameter to the URL.

Examples

• %XMLRPC{"foxrate.currencyConvert('USD', 'GBP', '100')" url="http://foxrate.org/rpc/"}% expanded to: {'flerror':'0','amount':'63.71','message':'cached'} on the date of writing this topic.
• %XMLRPC{"foxrate.currencyConvert('USD', 'GBP', '100')" url="http://foxrate.org/rpc/" select="amount"}% expanded to: 63.71 on the date of writing this topic.
• %XMLRPC{"foxrate.currencyConvert('USD', 'GBP', '%AMOUNT%')" url="http://foxrate.org/rpc/" select="amount" if_fails="N/A" requires="%AMOUNT%" timeout="5" expires_in="1day"}% shows usage of other parameters.
• %XMLRPC{"someFunction({'scalarProp':'1','arrayProp':['elem1','elem2']}, 'scalarParameter')"}% example object parameters.

Plugin Settings

This plugin can be configured with preferences settings in TWikiPreferences (site level), a WebPreferences (web level) or in a topic (page level). Do not change the settings here, they are here only to illustrate the default values. To overload, copy the settings to one of the aforementioned topics.

• Debug plugin: (See output in the topic)
  • Set XMLRPCPLUGIN_DEBUG = 1
• Default url parameter value:
  • Set XMLRPCPLUGIN_URL = http://foxrate.org/rpc/
• Allowed domains, list of space separated patterns required in the URL: (use with FINALPREFERENCES)
  • Set XMLRPCPLUGIN_DOMAINS = .org
• Default timeout parameter value:
  • Set XMLRPCPLUGIN_TIMEOUT = 10
• Default expires_in parameter value:
  • Set XMLRPCPLUGIN_EXPIRES_IN = 1 year

Plugin Installation & Configuration

Note: You do not need to install anything on the browser to use this plugin. The following 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 XmlRpcPlugin.zip in your twiki installation directory. Content:

File:	Description:
data/TWiki/XmlRpcPlugin.txt	Plugin topic
lib/TWiki/Plugins/XmlRpcPlugin.pm	Plugin Perl module
lib/TWiki/Plugins/XmlRpcPlugin/Config.spec	Plugin configuration spec

• • Set the ownership of the extracted directories and files to the webserver user.
  • Install the dependencies (if any).

• Plugin configuration and testing:
  • Run the configure script and enable the plugin in the Plugins section.
  • Configure additional plugin settings in the Extensions section if needed.
  • CachePath Path to cache directory.
  • Debug Debug plugin. See output in data/debug.txt.
  • Test if the installation was successful: See example above.

Plugin Info

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Make XML RPC calls to remote web services.

Plugin Author:	TWiki:Main.ZoltanGecse
Copyright:	© 2012 TWiki:Main.ZoltanGecse © 2012 TWiki:TWiki.TWikiContributor
License:	GPL (GNU General Public License)
Plugin Version:	2012-05-28 (V1.000)
Change History:
2012-05-28:	Initial version
TWiki Dependency:	$TWiki::Plugins::VERSION 1.1
CPAN Dependencies:	XML::RPC, Data::Dumper, URI, Time::Duration::Parse, CHI, JSON::PP, Sys::SigAction
Other Dependencies:	none
Perl Version:	5.005
TWiki:Plugins.Benchmark:	GoodStyle 100%, FormattedSearch 100%, XmlRpcPlugin 99%
Plugin Home:	http://TWiki.org/cgi-bin/view/Plugins/XmlRpcPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/XmlRpcPluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/XmlRpcPluginAppraisal

Related Topics: SoapClientPlugin, TWiki:Codev/TWikiAsWebServicesClient, TWikiPlugins