IGX Actions (v.3.0)

From Skip2PBX-WIKI

Jump to: navigation, search

Contents

Variables related actions

set-var

This action sets all the given arguments as variables for the current event context.

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

...
<action to="igx" name="set-var">
  <arg name="new-message-body">Hello ${user-name}!</arg>
</action>
...
<action to="skype" name="chatmessage-send">
  <arg name="user-name">${user-name}</arg>
  <arg name="message-body">${new-message-body}</arg>
</action>
...

Scripts related actions

script-plain

This action runs a local file with path file.
The variable async specifies if the script must be run in synchronous mode so we can have a result from it or in asynchronous mode in a spawned process.

One script can run other actions and return variables only if async variable is False. The returned variables are returned by the script-plain action itself.

The variable async can assume two values:

  • False: the script is run in synchronous mode
  • True: the script is run in asynchronous mode


Action Variables

  • file: The file to be executed
  • async: The execution mode


Errors

  • invalid-argument: A required argument is missing or misspelled
  • file-missing: The file does not exist

Reading variables from external scripts

The context variables are passed to the script as environment variables with the minus symbol ('-') translated to underscore symbol ('_').

The next example shows you how to create a simple chat logger to save all the incoming messages to a text file.

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

...
<event name="chatmessage-incoming-received">
  <action to="igx" name="script-plain">
     <arg name="file">/usr/local/bin/save_chat_messages.sh</arg>
     <arg name="async">false</arg>
  </action>
</event>
...

/usr/local/bin/save_chat_messages.sh 

#!/bin/bash

echo "$user_name: $message_body" >> /var/log/chatlog.txt

Returning variables from external scripts

One external script can return variables simply displaying them in the STDOUT with the syntax key=value.
The next example shows you how to send a different chat message depending on the remote Skype user name and how to run different commands on the local machine depending on the message body.

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

...
<event name="chatmessage-incoming-received">
  <action to="igx" name="script-plain">
     <arg name="file">/usr/local/bin/answer_chat.sh</arg>
     <arg name="async">false</arg>
  </action>

  <action to="skype" name="chatmessage-send">
     <arg name="message-body">${reply-message-body}</arg>
  </action>
</event>
...

/usr/local/bin/answer_chat.sh 

#!/bin/bash

if [[ "$user_name" == "john.doe" ]]; then

  if [[ "$message_body" == "backup" ]]; then

    echo "reply_message_body=Hello John, I'm starting the backup now."
    /one/my/script/somewhere.sh &

  elif [[ "$message_body" == "uname" ]]; then

    echo "reply_message_body=Hello John, my uname is: `uname -a`."

  else
    echo "reply_message_body=Hello John, I did not understand your command."
  fi

else

  echo "reply_message_body=You are not allowed to chat here."
fi

If john.doe sends a Skype message containing the test "backup" the script will return the following output: 

reply_message_body=Hello John, I'm starting the backup now.

Otherwise if any other user tries to send a chat message the output will be as follows: 

reply_message_body=You are not allowed to chat here.

And as you can see in the previous XML code, the variable reply_message_body is used as text for the reply message.

Running actions from external scripts

One external script can run other actions calling them with an INI like syntax. The action name must be enclosed by squared parenthesis and preceded by the action's destination. The action's variables are expressed with the syntax with the syntax key=value.

The next example works like the previous with some extra features.

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

...
<event name="chatmessage-incoming-received">
  <action to="igx" name="script-plain">
     <arg name="file">/usr/local/bin/answer_chat.sh</arg>
     <arg name="async">false</arg>
  </action>

  <action to="skype" name="chatmessage-send">
     <arg name="message-body">${reply-message-body}</arg>
  </action>
</event>
...

/usr/local/bin/answer_chat.sh 

#!/bin/bash

if [[ "$user_name" == "john.doe" ]]; then

  if [[ "$message_body" == "backup" ]]; then

    echo "[skype:chatmessage-send]"
    echo "user_name=system.administrator"
    echo "message_body=John asked for a backup at `date`"
    echo "[skype:chat-leave]"

    echo "[skype:chatmessage-send]"
    echo "user_name=john.doe"
    echo "message_body=Hello John, I started the backup and I notified the System administrator"
    echo "[skype:chat-leave]"

    /one/my/script/somewhere.sh &
 
  else
    echo "[skype:chatmessage-send]"
    echo "message_body=I did not understand your command"
    echo "[skype:chat-leave]"
  fi
 
else
 
   echo "[skype:chatmessage-send]"
   echo "user_name=system.administrator"
   echo "message_body=One unauthorized user asked for a command"
   echo "[skype:chat-leave]"
fi

If john.doe sends a Skype message containing the test "backup" the script will return the following output: 

[skype:chatmessage-send]
user_name=system.administrator
message_body=John asked for a backup at mer giu 06 15:57:20 CEST 2008
[skype:chat-leave]

[skype:chatmessage-send]
user_name=john.doe
message_body=Hello John, I started the backup and I notified the System administrator
[skype:chat-leave]

Otherwise if any other user tries to send a chat message the output will be as follows: 

[skype:chatmessage-send]
user_name=system.administrator
message_body=One unauthorized user asked for a command
[skype:chat-leave]

If you need to return variables with this kind of script you should use the set-var action as last step.

script-xml

This action runs a local file with path file.
The variable async specifies if the script must be run in synchronous mode so we can have a result from it or in asynchronous mode in a spawned process.

One script can run other actions and return variables only if async variable is False. The returned variables are returned by the script-plain action itself.

The variable async can assume two values:

  • False: the script is run in synchronous mode
  • True: the script is run in asynchronous mode

The main difference between this action and the script-plain action is the output format of the script.
In this case the output MUST be XML formatted as it is in one action file like /s2papps/igx/config/actions-skype.xml .
There is not any other difference between script-plain and script-xml.

One output example can be the following: 

<?xml version="1.0" encoding="UTF-8"?>
<action to="skype" name="chatmessage-send">
  <arg name="user-name">john.doe</arg>
  <arg name="message-body">Hello John, I just started the backup</arg>
</action>

NOTE: A wrong XML formatted code can cause an internal error. Be sure that your XML is well formatted before using it in a production environment.


Action Variables

  • file: The faile to be executed
  • async: The execution mode


Errors

  • invalid-argument: A required argument is missing or misspelled
  • file-missing: The file does not exist

System policy related actions

check-outoing-auth

This action verifies if one user is allowed to place an outgoing call using the Skype service.

One user can authenticate himself preceding the phone number to call with a special code defined in /s2papps/igx/config/features.xml (TAG: auth-sequence) and his pin and his password defined in the /s2papps/igx/config/auth/users.xml.

To deeply understand the user's authentication procedure please refer to the IGX User's (v.3.0) document.

Immagine we have set the system in the following way:

  • auth-sequence: **
  • username: 10
  • password: 8899
  • number to call: 555123

To authenticate, the user must dial: 

** 10 8899 555123

NOTE: While dialing, the user can omit the password if it is not specified in the /s2papps/igx/config/auth/users.xml.

On success the action returns the user identifier, the user name (numerical), the belonging group identifier and the user's description as they are defined in the /s2papps/igx/config/auth/users.xml file, otherwise it raises an error.

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

...
<event name="call-incoming-start">
  <action to="igx" name="check-outgoing-auth">
    <arg name="file-users">auth/users.xml</arg>
    <arg name="file-groups">auth/groups.xml</arg>

    <on-error>
      <action to="chan" name="call-failed">
        <arg name="reason">forbidden</arg>
      </action>
    </on-error>
  </action>
  ...
</event>
...



Action Variables

  • call-id: The PBX call
  • file-users: The file containing the user's list
  • file-groups: The file containing the group's list


Returned variables

  • auth-id: auth-user
  • auth-group-id: auth-desc


Errors

  • invalid-argument: A required argument is missing or misspelled
  • invalid-user: The user does not exist
  • user-disabled: The user is disabled
  • invalid-group: The user does not belong to any group
  • group-disabled: The user's group is disabled

check-outgoing-filter

This action checks if a call can be placed depending on the system filters. A filter is basically an ACL.
To deeply understand the system filters please refer to the IGX Filter's (v.3.0) document.

If the filter is set to stop the outgoing call the actions returns an error code.

The file containing the filter rules must be specified in the file variable.

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

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

    <on-error>
      <action to="chan" name="call-failed">
        <arg name="reason">forbidden</arg>
      </action>
    </on-error>
  </action>
  ...
</event>
...


Action Variables

  • call-id: The outgoing PBX call
  • file: The file containing the rules


Errors

  • invalid-argument: A required argument is missing or misspelled
  • denied: The call must be stopped

check-incoming-filter

This action checks if a call can be received depending on the system filters. A filter is basically an ACL.
To deeply understand the system filters please refer to the IGX Filter's (v.3.0) document.

If the filter is set to stop the incoming call the actions returns an error code.

The file containing the filter rules must be specified in the file variable.


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

...
<event name="call-incoming-start">
  <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.</arg>
      </action>

      <action to="skype" name="call-hangup" />
    </on-error>
  </action>
  ...
</event>
...


Action Variables

  • call-id: The incoming Skype call
  • file: The file containing the rules


Errors

  • invalid-argument: A required argument is missing or misspelled
  • denied: The call must be stopped

Address book related actions

apply-map

This action is used to convert a number sequence in a Skype destination. This is useful while using a non-SIP channel.
To deeply understand the system filters please refer to the IGX Map's (v.3.0) document.

The file containing the translation map rules must be specified in the file variable.

The function does not return any value, but it modifies the destination of the call before routing it out.

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

...
<event name="call-incoming-start">
  <action to="igx" name="apply-map">
     <arg name="file">maps/public.xml</arg>
  </action>
  ...
</event>
...


Action Variables

  • call-id: The PBX outgoing call
  • file: The file containing the map


Errors

  • invalid-argument: A required argument is missing or misspelled


check-name-in-map

This action is used to verify if a Skype destination exists in a map file. This is useful if you need for instance to stop all the callers that are not mapped in the map file.
To deeply understand the system filters please refer to the IGX Map's (v.3.0) document.

The file containing the translation map rules must be specified in the file variable and the Skype destination must be specified with the variable name.

If the Skype destination does not exist in the map the function raise an error.

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

...
<event name="call-incoming-start">
  <action to="igx" name="apply-map">
     <arg name="file">maps/public.xml</arg>
  </action>
  ...
</event>
...


Action Variables


Errors

  • invalid-argument: A required argument is missing or misspelled
  • not-exists: The map does not contain such Skype destination

Routing related actions

route-in

This action routes an incoming Skype call to its PBX destination depending on a routing table in an XML file.
To deeply understand the system filters please refer to the IGX Routing (v.3.0) document.

The file containing the routing table must be specified in the file variable and the Skype call-id must be specified with the variable call-id.

On success this function automatically links the incoming call with the PBX channel and manages all the events (such as disconnection, on-hold, ecc...).


Action Variables

  • file-route: The file containing the routing table
  • call-id: The incoming Skype call


Returned variables

  • channel-call-id: The PBX call
  • channel-to: The channel used to route in the call


Errors

  • invalid-argument: A required argument is missing or misspelled
  • error-on-call: One error occurred while contacting the PBX
  • cannot-route: The call cannot be routed in

route-out

This action routes an outgoing PBX call to a Skype destination depending on a routing table in an XML file.
To deeply understand the system filters please refer to the IGX Routing (v.3.0) document.

The file containing the routing table must be specified in the file variable and the PBX call-id must be specified with the variable call-id.

On success this function automatically links the outgoing call with the Skype client and manages all the events (such as disconnection, on-hold, ecc...).


Action Variables

  • file-route: The file containing the routing table
  • call-id: The outgoing PBX call


Returned variables

  • skype-call-id: The Skype call
  • skype-from: The account used to route out
  • skype-to: The Skype destination


Errors

  • invalid-argument: A required argument is missing or misspelled
  • error-on-call: One error occurred while routing the call to Skype
  • cannot-route: The call cannot be routed out
  • route-witout-skype: The route does not contain any valid Skype account to use
  • route-is-full: The selected route is full
  • not-exists: The route file does not exist

get-route-in

This action returns a route for an incoming Skype call depending on a routing table in an XML file. This is useful if you need to dynamically change the routing table.
To deeply understand the system filters please refer to the IGX Routing (v.3.0) document.

The file containing the routing table must be specified in the file variable and the Skype call-id must be specified with the variable call-id.


Action Variables

  • file: The file containing the routing table
  • call-id: The incoming Skype call


Returned variables

  • route-to-skype: The route used


Errors

  • invalid-argument: A required argument is missing or misspelled


get-route-out

This action returns a route for an outgoing PBX call to a Skype destination depending on a routing table in an XML file. This is useful if you need to dynamically change the routing table.
To deeply understand the system filters please refer to the IGX Routing (v.3.0) document.

The file containing the routing table must be specified in the file variable and the PBX call-id must be specified with the variable call-id.


Action Variables

  • file: The file containing the routing table
  • call-id: The outgoing PBX call


Returned variables

  • route-use-skype: The account used
  • route-from-channel: The route used


Errors

  • invalid-argument: A required argument is missing or misspelled


get-suitable-user

This action probes a set of active Skype clients defined by the variable local-user-names (comma separated) to check if at least one of them can handle a call with a remote Skype destination defined by the variable remote-user-name.

On success it returns the first available Skype client.

This function is useful to check if you have free channels to handle a new call, otherwise it raises an error


Action Variables

  • local-user-names: The list of Skype accounts
  • remote-user-name: The remote Skype destination


Returned variables

  • user-name: The available Skype account


Errors

  • invalid-argument: A required argument is missing or misspelled
  • none-found: No user is suitable for such Skype destination

Flow control actions

exit

This action simply stops the execution of the current context.

Retrieved from "http://docs.skip2pbx.com/index.php/IGX_Actions_%28v.3.0%29"
Personal tools