XML Scripting

From Skip2PBX-WIKI

Jump to: navigation, search

NB: This document refers to version v.3.0.

Contents

Introduction to XML Scripting

Skip2PBX version 3.0 supports XML scripting in order to allow a very good level of system integration and features customization.

The XML scripting mechanism is based on events and actions. In other words you can define the Skip2PBX reaction to a predefined set of events.

One event can be a Skype event, a PBX event or even a user defined event and one action can be for example to run a script, to answer a call or to send a chat message.

In a standard Skip2PBX 3.0 installation the base XML file is: /s2p/apps/igx/config/actions.xml.

This file is basically composed by two sections: skype-events and chan-events. As you can immagine skype-events contains the list of actions that must be executed when certain Skype events are raised and chan-events contains the list of actions that must be executed when certain PBX events are raised.

In order to make the actions.xml file smaller and well organized it contains special tags for external files inclusion.

File: /s2p/apps/igx/config/actions.xml 

<?xml version="1.0" encoding="UTF-8"?>
<config>
   <skype-events>
      <?include actions-skype.xml ?>
   </skype-events>

   <chan-events>
      <?include actions-chan.xml ?>
   </chan-events>
</config>

This simple and self-explaining code shows you that actions-skype.xml file contains the Skype client events handling and actions-chan.xml file contains the Channels manager events handling.

Both the files are included in the same /s2p/apps/igx/config path.

What is an event

An event is a generic event raised by the Skype client or the Channels manager. One event can be for example one incoming call. Each raised event is defined by an event name and a set of events variables.

Here a small example:

File: /s2p/apps/igx/config/actions-skype.xml 

...
<event name="chatmessage-incoming-received">

  <action to="skype" name="chatmessage-send">
    <arg name="message-body">Hello ${user-dispname}, chat is not allowed here. Goodbye.</arg>
  </action>	

  <action to="skype" name="chat-leave" />

</event>
...

As you can see the event name is chatmessage-incoming-received and when it is raised, Skip2PBX is asked to run two actions:

  1. chatmessage-send: Send a chat message
  2. chat-leave: Leave the opened chat

Event variables

You can refer an event variable with the syntax ${variablename} where "variablename" is the name of the variable you want to use.
Each event has a specific variables set depending on its structure.

Intercepting more events with one tag

It is possible to run the same set of actions when an event is raised. This can be useful to define common actions for different events. To catch more than one event you have to specify the events with a comma separated syntax.

File: /s2p/apps/igx/config/actions-skype.xml 

...
<event name="chatmessage-incoming-received,call-incoming-ringing">

  <action to="skype" name="chatmessage-send">
    <arg name="message-body">Hello ${user-dispname}, chat and calls are not allowed here. Goodbye.</arg>
  </action>	

  <action to="skype" name="chat-leave" />

</event>
...

What is an action

One action is a generic operation that must be executed from the Skype client, from the Channels manager or from the Core system.

As you can see from the previous example an action is introduced with the XML tag <action>. This tag needs exactly two attributes:

  • to: Specifies the action's destination. It can have 3 different values:
  • name: The name of the action

Action variables

Each action can accept one or more arguments defined by the XML tag <arg>.
As said for the events, each action has its specific arguments set depending on its structure.

Hidden Action variables

If an argument value is not defined, its value is inherited from the event variables set. In the above example we have two inherited variables:

  • user-name that defines the Skype username to send the message to
  • chat-name that defines the chat to close

To better understand you could rewrite the previous example as follows:

File: /s2p/apps/igx/config/actions-skype.xml 

...
<event name="chatmessage-incoming-received">

  <action to="skype" name="chatmessage-send">
    <arg name="user-name">${user-name}</arg>
    <arg name="message-body">Hello ${user-dispname}, chat is not allowed here. Goodbye.</arg>
  </action>	

  <action to="skype" name="chat-leave">
    <arg name="chat-name">${chat-name}</arg>
  </action>

</event>
...

Error's handling

Each action can raise one error while running for various reasons. The main important consequence is that the actions execution will be stopped if not specified in other way.

The errors handling can be approached in two ways:

  • With the on-error XML tag
  • With an external errors handler

If an error occurs two new context variables are set:

  • error: This variable assumes the value of true
  • error-name: The error code

Some extra variables can be set depending on the error type.

The "on-error" XML tag

When present, the on-error XML tag intercepts all the error raised by an action and executes a list of actions.

In the following example you can see how to intercept a call filter error and send a message to the Skype user who is calling you.

Example: /s2p/apps/igx/config/actions-skype.xml 

...
<event name="call-incoming-ringing">
  <action to="igx" name="check-incoming-filter">
    <arg name="file">filters/filters-in.xml</arg>

      <on-error>
        <action to="skype" name="chatmessage-send">
          <arg name="message-body">Hello ${user-dispname}, you are not allowed to call here. (code 1)</arg>
        </action>
        <action to="skype" name="call-hangup" />
      </on-error>

  </action>
  ...
  next actions executed only if the action does not raise the error
  ... 
</event>
...

In this example the execution will be stopped if the error occurs.

How to continue the actions execution if an error occurs

If you need to ignore the error you can set the error-ignore variable either in the on-error context or in the event context.

Example: /s2p/apps/igx/config/actions-skype.xml ... 

<event name="call-incoming-ringing">
  <action to="igx" name="check-incoming-filter">
    <arg name="file">filters/filters-in.xml</arg>

    <on-error>
      <action to="skype" name="chatmessage-send">
        <arg name="message-body">Hello ${user-dispname}, you are not allowed to call here. (code 1)</arg>
      </action>
      <action to="skype" name="call-hangup" />

      <action to="igx" name="set-var">
        <arg name="error-ignore">true</arg>
      </action>
    </on-error>

  </action>
  ...
  next actions executed even if the action raises the error
  ... 
</event>
...

With an external error handler

Capturing the error with an external handler can be done using the IGX action script-plain or script-xml. You can detect the error checking the variable error and error-name.

The event execution can be stopped using the IGX action exit.

Retrieved from "http://docs.skip2pbx.com/index.php/XML_Scripting"