Features/Mass Deployment/Automatic Redirection

From Snom User Wiki

Author: Sven Fischer

Version: 1.1

1 General
2 Design aim
3 Customer requested functionality
4 Client Server Interface

General

This redirection service is able to register phones in order to redirect them on request to a specified provisioning server at an arbitrary location. Registered phones (MACs) can be listed and deregistered as well.

Design aim

The redirection service is designed to implement an easy to use interface for interaction with remote client applications.
The communication between server and remote client application is secure.

Customer requested functionality

The ability to redirect phones to any url and still have the registered phones show up and be owned by the same user, which isn't possible with the old system.
Don't let others delete my phones.

Client Server Interface

Protocol

The interface between client and server is built as XMLRPC services. To access them you may use XMLRPC libraries available in the internet or do it yourself by sending XML documents described further down via HTTP POST requests using Content-Type: text/xml.
TLS is used to encrypt the communication between client and server.
User authentication is done via basic authentication.

Service Port

The xmlrpc redirection service can be accessed at:

https://provisioning.snom.com:8083/xmlrpc

User Accounts

In order to access the redirection service you need to have a valid user account which you can get from snom technology AG. If you already have an account for the old provisioning shell you should be able to access the new redirection service with it as well. SSH keys are not supported anymore; you need to use the password.

Available XMLRPC Commands

redirect.registerPhone

A specific phone (MAC) can be registered at the redirection service in order to redirect it to a different setting server.

XMLRPC signature

redirect.registerPhone(mac, provisioningUrl)

Parameter:

mac: MAC address the requesting user would like to register to the service.
provisioningUrl: The URL the phone to be registered should be redirected to.

Return values:

Result code: True, False
Result text:
1. Ok, if the given mac address could be registered successfully to the mac addresses of the requesting user.
2. Error:owned_by_other_user if the requested mac is already registered to somebody else, Error:malformed_url if the given provisioningUrl is faulty or Error:malformed_mac if the given MAC is faulty.

The following snippets show examples of the handshake of the above described XMLRPC request.

Request:

<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.registerPhone</methodName>

 <params>

  <param>

   <value><string>000413244321</string></value>

  </param>

  <param>

   <value><string>http://fox.snom.com/prv2.php?mac={mac}</string></value>

  </param>

 </params>

</methodCall>

positive Answer:

<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>1</boolean></value>

    <value><string>Ok</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

negative Answer of Error:owned_by_other_user:

<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>0</boolean></value>

    <value><string>Error:owned_by_other_user</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

redirect.deregisterPhone

A specific registered phone (MAC) can be deregistered from the service.

XMLRPC signature

redirect.deregisterPhone(mac)

Parameter:

mac: MAC address the requesting user would like to deregister from the service.

Return values:

Result code: True, False
Result text:
1. Ok, if the requesting user owns the given mac address and the mac address could be deregistered successfully.
2. Error:owned_by_other_user if the requested mac is registered to somebody else or Error:malformed_mac if the given MAC is faulty.

The following snippets are showing examples of the handshake of the above described XMLRPC request.

Request:

<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.deregisterPhone</methodName>

 <params>

  <param>

   <value><string>000413244321</string></value>

  </param>

 </params>

</methodCall>

positive Answer:

<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>1</boolean></value>

    <value><string>Ok</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

negative Answer of Error:owned_by_other_user:

<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>0</boolean></value>

    <value><string>Error:owned_by_other_user</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

redirect.listPhones

A list including all registered phones (MACs) of the requesting user is provided.

XMLRPC signature

redirect.listPhones(phoneType, provisioningUrl=None)

Parameter:

phoneType: type of phone of which the requesting user wants to see the list of the phones he has already registered.
provisioningUrl: optional URL matching the already redirected MACs of the requesting user.

Return values:

Result: a list of mac addresses the requesting user has registered, an empty list otherwise.

The following snippets show examples of the handshake of the above described XMLRPC request.

Request:

<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.listPhones</methodName>

 <params>

  <param>

   <value><string>snom360</string></value>

  </param>

  <param>

   <value><string>http://fox.snom.com/prov.php?mac={mac}</string></value>

  </param>

 </params>

</methodCall>

Filled Answer:

<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><string>000413230c25</string></value>

    <value><string>000413230c24</string></value>

    <value><string>000413230c23</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

Empty Answer:

<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

   </data></array></value>

  </param>

 </params>

</methodResponse>

redirect.checkPhone

Checks if a phone (MAC) is registered to the requesting user.

XMLRPC signature

redirect.checkPhone(mac)

Parameter:

mac: MAC address the requesting user wants to check.

Return values:

Result code: True, False
Result text:
1. Ok, if the requesting user owns the given mac address.
2. Error:owned_by_other_user if the requested mac is already registered by somebody else, Error:no_such_mac if this mac isn't registered at all or Error:malformed_mac if the given MAC is faulty.

The following snippets show examples of the handshake of the above described XMLRPC request.

Request:

<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.checkPhone</methodName>

 <params>

  <param>

   <value><string>000413230c25</string></value>

  </param>

 </params>

</methodCall>

Answer:

<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>1</boolean></value>

    <value><string>Ok</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

redirect.registerPhoneList

A list of MACs can be registered at the redirection service in order to redirect the specified phones to a different setting server.

XMLRPC signature

redirect.registerPhoneList(macList, provisioningUrl)

Parameter:

macList: A list of MAC addresses.
provisioningUrl: The URL the phones to be registered should be redirected to.

Return values:

Result code: True, False
Result text:
1. Ok, if the whole given list of mac addresses could be successfully registered to the requesting user.
2. Error:malformed_mac_list, if the given list of mac addresses is NIL or empty.
3. If only parts of the given list of mac addresses is faulty, those incorrect MAC addresses are returned in pairs together with the specific error message applying to this mac address respectively, like {000413250c24: Error:malformed_url, 000413250c25: Error:malformed_mac,000413250c26: Error:owned_by_other_user}

The following snipplets are showing examples of the handshake of the above described XMLRPC request.

Request:

<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.registerPhoneList</methodName>

 <params>

  <param>

   <value><array><data>

    <value><string>000413250c23</string></value>

    <value><string>000413250c24</string></value>

    <value><string>000413250c25</string></value>

   </data></array></value>

  </param>

  <param>

   <value><string>http://fox.snom.com/prv2.php?mac={mac}</string></value>

  </param>

 </params>

</methodCall>

positive Answer:

<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>1</boolean></value>

    <value><string>Ok</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

negative Answer of malformed_mac_list:

<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>0</boolean></value>

    <value><string>Error:malformed_mac_list</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

Another Request:

<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.registerPhoneList</methodName>

 <params>

  <param>

   <value><array><data>

    <value><string>000413244321</string></value>

    <value><string>000413270c23</string></value>

    <value><string>000413270c24</string></value>

    <value><string>000413270c25</string></value>

   </data></array></value>

  </param>

  <param>

   <value><string>http://fox.snom.com/prv2.php?mac={mac}</string></value>

  </param>

 </params>

</methodCall>

negative Answer of owned_by_other_user:

<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>0</boolean></value>

    <value><struct>

     <member>

      <name>000413270c24</name>

      <value><string>Error:owned_by_other_user</string></value>

     </member>

     <member>

      <name>000413270c25</name>

      <value><string>Error:owned_by_other_user</string></value>

     </member>

     <member>

      <name>000413244321</name>

      <value><string>Error:owned_by_other_user</string></value>

     </member>

     <member>

      <name>000413270c23</name>

      <value><string>Error:owned_by_other_user</string></value>

     </member>

    </struct></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

redirect.deregisterPhoneList

A list of registered phones (MACs) can be deregistered from the service.

XMLRPC signature

redirect.deregisterPhoneList(macList)

Parameter:

macList: A list of MAC addresses

Return values:

Result code: True, False
Result text:
1. Ok, if the requesting user owns the list of given mac addresses and the mac addresses could be deregistered successfully.
2. Error:malformed_mac_list, if the given list of mac addresses is NIL or empty.
3. If only some of the mac addresses on the list are faulty, the incorrect MAC addresses will be returned in pairs with the applicable error message for each mac address. For example: {000413250c24: Error:malformed_url, 000413250c25: Error:malformed_mac,000413250c26: Error:owned_by_other_user}

The following snippets show examples of the handshake of the above described XMLRPC request.

Request:

<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.deregisterPhoneList</methodName>

 <params>

  <param>

   <value><array><data>

    <value><string>000413250c23</string></value>

    <value><string>000413250c24</string></value>

    <value><string>000413250c25</string></value>

   </data></array></value>

  <param>

 </params>

</methodCall>

positive Answer:

<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>1</boolean></value>

    <value><string>Ok</string></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

Another Request:

<?xml version='1.0'?>

<methodCall>

 <methodName>redirect.deregisterPhoneList</methodName>

 <params>

  <param>

   <value><array><data>

    <value><string>000413260c23</string></value>

    <value><string>000413260c24</string></value>

    <value><string>000413260c25</string></value>

   </data></array></value>

  </param>

 </params>

</methodCall>

negative Answer of no_such_mac:

<?xml version='1.0'?>

<methodResponse>

 <params>

  <param>

   <value><array><data>

    <value><boolean>0</boolean></value>

    <value><struct>

     <member>

      <name>000413260c23</name>

      <value><string>Error:no_such_mac</string></value>

     </member>

     <member>

      <name>000413260c25</name>

      <value><string>Error:no_such_mac</string></value>

     </member>

     <member>

      <name>000413260c24</name>

      <value><string>Error:no_such_mac</string></value>

     </member>

    </struct></value>

   </data></array></value>

  </param>

 </params>

</methodResponse>

Retrieved from "http://wiki.snom.com/Features/Mass_Deployment/Automatic_Redirection"

Features/Mass Deployment/Automatic Redirection

From Snom User Wiki

Contents

General

Design aim

Customer requested functionality

Client Server Interface

Protocol

Service Port

User Accounts

Available XMLRPC Commands

redirect.registerPhone

XMLRPC signature

Request:

positive Answer:

negative Answer of Error:owned_by_other_user:

redirect.deregisterPhone

XMLRPC signature

Request:

positive Answer:

negative Answer of Error:owned_by_other_user:

redirect.listPhones

XMLRPC signature

Request:

Filled Answer:

Empty Answer:

redirect.checkPhone

XMLRPC signature

Request:

Answer:

redirect.registerPhoneList

XMLRPC signature

Request:

positive Answer:

negative Answer of malformed_mac_list:

Another Request:

negative Answer of owned_by_other_user:

redirect.deregisterPhoneList

XMLRPC signature

Request:

positive Answer:

Another Request:

negative Answer of no_such_mac:

Views

Personal tools

VoIP Phone Products

main navigation

Configuration

knowledgebase

Search

Toolbox