Howto:Using the SOAP Admin Function

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.

Applies To

This information applies to

• all innovaphone PBX platforms, V5 and V6

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 n a Box. Please not that the usual restrictions apply for updating entries, namely, entries shall not modified when LDAP replication is active on the box. Instead, connect to the LDAP masters SOAP interface and do the modifications.

Usage

The xml argument to Admin() is an xml string, that has a single top-level element, which is interpreted as command. 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"/></show>

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.

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.

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 object 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 sufficiant.

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. Please note that the password is not stored in clear on the box, so it is not possible to retrieve it.

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 single (pbx=<... value can be delete 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 atribute xml syntax as subtag to the <user> tag. In the previous example, this is

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