Howto:Using the SOAP Admin Function

From innovaphone-wiki

Jump to: navigation, search

The PBX SOAP interface allows you to query and manipulate the entire PBX object configuration (i.e. users). Here is the syntax of the commands.

Contents

Applies To

This information applies to

  • all innovaphone PBX platforms


More Information

Problem Details

Sometimes, there is a need to access the PBX object configuration (that is, the defined users, trunk lines, nodes, etc.) programmatically. This could be done for examination or for manipulation.

There are various ways to accomplish this, one of it is using the Admin function available in the SOAP API.

This function takes a single argument xml, which is executed as a command and the resulting output is returned to the user.


System Requirements

The SOAP interface and thus the SOAP API's Admin is available when a working PBX is present in a Box. Please note that the usual restrictions apply for updating entries, namely, entries shall not be modified when LDAP replication is active on the box. Instead, connect to the LDAP masters SOAP interface and do the modifications.

Usage

The Admin() function may be used to retrieve information from and write information to the PBX. Information written to the PBX is effective immediately.

The xml argument to Admin() is an xml string, that has a single top-level element, which is interpreted as command.

Depending on the way the SOAP request is sent the provided xml argument must be manually XML escaped:

"   "
' '
< &lt;
> &gt;
& &amp;

Example:

&lt;show&gt;&lt;user cn=&quot;PBX User Four&quot; config=&quot;true&quot;/&gt;&lt;/show&gt;

A comple SOAP Request would be:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pbx="http://www.innovaphone.com/pbx"><SOAP-ENV:Header/><SOAP-ENV:Body>
<Admin><xml xsi:type="xsd:string">&lt;show&gt;&lt;user cn="PBX User Four" config="true"/&gt;&lt;/show&gt;</xml>
</Admin></SOAP-ENV:Body></SOAP-ENV:Envelope>

There are various commands implemented.

show

The show command will show details about an object, selected by its cn (which is the long name in the PBX user config), e.g.

<show><user cn="PBX User Four" config="true"/></show>

The attribute config="true" (available starting with version 9) is optional. If used only the pure config stored at a user is provided, without application of templates.

The command will return the data for PBX User Four (provided there is one):

<show time="2994">
    <user 
        cn="PBX User Four" 
        guid="4126ec4ee909d3119db10090330600e8" 
        e164="140" 
        h323="user-4" 
        pwd="********" 
        fake="123" 
        cfnr="99" 
        busy-out="4711" 
        loc="Sindelfingen" 
        node="root" 
        filter="normal" 
        cd-filter="normal" 
        type="ep">
    <cd 
        type="cfb">
        <ep 
            e164="0900123"/>
    </cd>
    <cd 
        type="cfnr">
        <ep 
            e164="0900321"/>
    </cd><
    <grp 
        name="test"/>
    <grp 
        name="soap"/>
    <ep 
        type="EP" 
        addr="172.16.10.38" 
        port="2069" 
        product="innovaphone IP230 [-/08-6090020/20080116-01]" 
        version="6.00 dvl-sr2 [08-60900.20/222/104]" 
        h323="user-4" 
        time="336" 
        lic="true"/>
    </user>
</show>

As a special case, you can use the cn * which will yield a list of all known objects. But be aware that the result of a SOAP request is limited to a fixed amount of bytes (version dependant, currently 300kB). Larger results will cause the request to fail. It is thus not recommended to use this feature as a general purpose mechanism. Also be aware in V9 the show request with wildcard as cn will deliver not complete object configuration (some fields are omitted to reduce the amount of data). It is thus recommended to use calls to FindUser to retrieve the list of all objects and to use Admin() with the specific cn for each object of interest. An example how to retrieve configuration of all objects can be found here Howto:Retrieve configuration of all PBX Objects using SOAP API.

Subtags underneath <user> include cd, grp, pseudo, gw. However, this list may change over time and you must not rely on this.

The list of currently known attributes to <user> is guid, cn, h323, e164, hw-id, pbx, loc, node, rep, phys, pwd, cfnr, busy-in, busy-out, type, filter, cd-filter, gi, local. Again, this list may change and you must not rely on it.

Please note the appearance of the pwd attribute (pwd="********"). It is - of course - not possible to retrieve the password using this interface (in fact, it is not possible to retrieve the password at all).

Some of the information is in fact runtime data, not configuration data. For example, the <ep> tag shows current registration information for the object.

The PBX will store some sensitive information about the current user sessions and push notifications. All this information was stored in the sessions tag. We will not deliver the sessions tag in the show method.

add

The add command will create a new PBX object, e.g.

<add>
    <user 
        cn="new PBX User Four" 
        e164="140" 
        h323="user-4" 
        cfnr="99" 
        busy-out="4711" 
        loc="Sindelfingen" 
        node="root" 
        filter="normal" 
        cd-filter="normal" 
        type="ep">
        <cd type="cfb">
            <ep e164="0900123"/>
        </cd>
        <cd type="cfnr">
            <ep e164="0900321"/>
        </cd>
        <grp name="soap"/>
        <grp name="test"/>
    </user>
</add>

If the addition is ok

<ok/>

will be returned.

There is no need to define all attributes, nor is it required to include all the subtags. For example, you can add the call diversions later using the <add-attrib> command. However, keep in mind that incomplete objects may cause harm (e.g. objects that have no setting for the node attribute).

To determine the available attributes and subtags, create an object manually using the web interface and retrieve the xml representation using the show command.

Any guid attribute will be ignored and the new object receives a new guid.


modify

To modify an existing entry, use the modify command. It has one subtag <user> which carries the complete data for the object after modification (not just the data that shall be modified). The object to be modified is determined by the guid attribute within the <user> tag. In the absence of this, it is determined by the cn (aka Long Name) attribute. Thus, to change the long name of an object, you need to specify its guid, otherwise the cn is sufficient.

In fact, the modify command is functional identical to a del / add cycle. The only difference is that the object is not really removed in between, so that the guid stays the same and any action related to the removal of an object (such as the deregistration of endpoints registered on the object) does not happen.

The only fool-proof method of changing an objects attribute thus is to do a show / modify cycle. When the pwd attribute is given as 8 stars ('pwd="********"), then it is not modified/set. Any other value is interpreted as clear text password. From firmware version 10 upwards, the show command will additionally report the password in encrypted form. If pwdx is sent back to the PBX during a modify command and the pwd attribute has the value ********, then the decrypted value of pwdx is set as the new password. If pwd is not ********, its value is used as the new password (clear text).

If you want to modify a User Object and keep the current sessions in the PBX you should not send the sessions tag. If you send the sessions tag, the session data in the PBX will be changed.

Please note that for a modify to succeed, the object does not need to exist. In fact, modify on a non-existing object will create it.

del

An object can be deleted using the del command. You must specify the cn attribute to delete an object, the guid will not do.

<del><user cn="supernew PBX User Four"/></del>

will delete the user with long name "supernew PBX User Four".

add-attrib / del-attrib

Some of the PBX object attributes can be accessed separately. This is true for all (usually multi-valued) attributes that live in a separate pbx= value on the FLASHDIR level. To understand this, have a look at an object and its representations on the XML and FLASHDIR level. Let us assume we have an object with cn PBX User Four. The show command yields

<show time="18613">
    <user 
        cn="PBX User Four" 
        guid="4126ec4ee909d3119db10090330600e8" 
        e164="140" 
        h323="user-4" 
        pwd="********" 
        fake="123" 
        cfnr="99" 
        busy-out="4711" 
        loc="Sindelfingen" 
        node="root" 
        filter="normal" 
        cd-filter="normal" 
        type="ep">
        <cd 
        type="cfb">
        <ep 
            e164="0900123"/>
        </cd>
        <cd 
            type="cfnr">
            <ep e164="0900321"/>
        </cd>
        <grp 
            name="soap"/>
        <grp 
            name="test"/>
    </user>
</show> 

On the FLASHDIR level (as seen in Config show), the object looks like this:

mod cmd FLASHDIR0 add-item 101 
    (cn=PBX User Four)
    (guid;bin=4126EC4EE909D3119DB10090330600E8)
    (h323=user-4)
    (e164=140)
    (loc=Sindelfingen)
    (node=root)
    (pbx=<user filter="normal" cd-filter="normal" fake="123" cfnr="99" busy-in="65535" busy-out="4711" pwd="ff8523566a0b5b820f785a6ed1eb24e5"/>)
    (pbx=<grp name="soap"/>)
    (pbx=<grp name="test"/>)
    (pbx=<cd type="cfb"><ep e164="0900123"/></cd>)
    (pbx=<cd type="cfnr"><ep e164="0900321"/></cd>)
    (usn=35)

Any information that is stored in a single (pbx=<... value can be deleted using del-attrib or added using add-attrib. To delete e.g. the CFB to 09000123, you can use

<del-attrib>
    <user 
        cn="new PBX User Four">
        <cd type="cfb">
            <ep e164="0900123"/>
        </cd>
    </user>
</del-attrib>

To delete such an attribute, it is important that you specify the complete attribute xml syntax as subtag to the <user> tag. In the previous example, this is

        <cd type="cfb">
            <ep e164="0900123"/>
        </cd>

Removing all Devices from User Object

to be able to delete all Devices/HW-IDs from an Object, an additional attribute no-dev must be supplied. Otherwise the PBX will add a device with Hardware-ID set to the Name of the Object.

Example modify request:

<?xml version="1.0"?>
<modify>
  <user cn="User 6"
        guid="819a174e73365901b90b009033400215"
        e164="16"
        h323="user6"
        pwd="********"
        pwdx="529c49b24c3e40c67d3f24f214b843cdd77fe777d7dab77f"
        loc="hq"
        node="root"
        no-dev="true"/>
</modify>


Determination of the cn

When the cn of an object is not known, it can be determined by virtue of the SOAP FindUser function.

Setting and Retrieving Passwords

Passwords cannot be retrieved in clear. They can be set and retrieved in encrypted format though, see modify above. See Related articles below for a discussion of password encryption in the PBX.

Uncovering xml commands with V5 PBXs

On more recent V5 (and later) PBX platforms, you can uncover valid syntax by turning on the configuration changes logging (Administration) in the log interface and then performing the action you want to mimic with your SOAP program in the user interface. The xml commands will show up as syslog entries.

Related Articles

Personal tools