XMPP API

Inhaltsverzeichnis

  1. XMPP Configuration
  2. API Design
  3. Module “archive”
  4. Module “base”
  5. Module “event”
  6. Module “journal”
  7. Module “location”
  8. Module “mobile”
  9. Module “monitor”
  10. Module “phone”
  11. Module “phonebook”
  12. Module “queue”
  13. Module “redirect”
  14. Module “xmppuser”

XMPP Configuration

Configuring the XMPP Server

You can use the XMPP Service immediately after setting up your server.

Should you operate multiple networked systems, it is advisable to plan and make the necessary configurations of Domains before the roll out of the clients. Each satellite branch must implements its own XMPP domain. You can use the corresponding hostnames, the location or the already established terms for the satellite as domain names.

In order to modify the following Settings, call up the System Settings and navigate to the area of sys.xmpp. After you have made the modifications, they will need to be applied: to do this, use the menu option Apply > Restart XMPP Server - manual apply.

Change XMPP Domains

Setting: Setting: sys.xmpp.domain

The Standard name of the XMPP Domain directly after the installation is pascom.

If the XMPP Service has already been put into productive operation, it can encounter registration problems as a result of retrospective alterations!

Should you operate multiple networked systems, it is advisable to plan and make the necessary configurations of Domains before the roll out of the clients. Each satellite branch must implements its own XMPP domain. You can use the corresponding hostnames, the location or the already established terms for the satellite as domain names.

This is not necessary on a cloudstack installation, each pascom instance forms a xmpp domain whereas the domain name equals to the instances name

Name of the XMPP Administrator

Setting: sys.xmpp.adminuser

Some advanced configuration can be done within the xmpp servers web-ui console.

You can reach the Web User Interface via

http://<pascom>:9090

By default, you may use the username ‘admin’ and the admin credentials to log into this console. Change the setting sys.xmpp.adminuser to some another username if you need to split up the responsibilities.

Java Runtime Options

Setting: sys.xmpp.java_options

With these options it is possible to alter the start options of the XMPP server, in particular the Maximum Heap Space Heap Space (-Xmx). A modification of the standard values is seldom useful (only with v. large Systems).

External IP

Setting: sys.xmpp.externalip

Use this field in order to specify an external IP or hostname for the XMPP server, this setting is to be changed, if necessary, when the system is operated behind a NAT gateway.

Further Settings

The deployed XMPP server can be modified in many further areas. Just as with pascom there is also a large range of internal settings.

You can make these alterations either through using the XMPP Server Web User Interface or directly roll them out from the pascom UI. All System Settings contained under sys.xmpp.properties will be automatically passed on to the XMPP server upon application (applying)

In order to define any of the settings “xmpp.server.session.timeout” you should create a system setting in pascom sys.xmpp.properties.xmpp.server.session.timeout with the desired value.

Administration

By default all users with a password are XMPP Protocol enabled.

Defining of Contact lists

Using the feature of the so-called shared Roster Groups the administrator can centrally define the entries in the contact lists of the client. In order to define a shared Roster, you only have to create a Role with the Role Type xmpp.group and assign the affected user(s).

Any alterations to a shared Roster will be immediately distributed to all registered clients upon the applying of the telephony.

XMPP Supervisor Authorisation

The XMPP Sub system is designed in a way that an authorised user can only subscribe to data and execute commands that will affect them or a team membership.

Therefore, a user cannot, for example, end the call of another user etc. With System Coupling, Information Screens or Switchboards, this is however an often requested feature. Therefore, you can grant individual accounts high privilege levels through assigning the Role Type xmpp.supervisor.

Further Information regarding Roles can found in the Howto Role Management

API Design

Concept

User

Enabled Users, and respective Queues are made available as a User automatically within the XMPP Server. The authentication is achieved therefore using the password of the user that is stored with the pascom. Queues are automatically managed, and one cannot register themselves on the XMPP Server, rather one can interact with it.

Telephone Presence

A core feature of the XMPP Protocols is that it allows multiple simultaneous connections from the same user. To this end, the user address (JabberID, JID for short) will be supplemented with a so-called resource. All Desktop Clients as well as many Libraries can be automatically provided with the resource identifier.

A JID consists of:

username@domain/ressource

If the identity registration name is “olsen” and the XMPP Domain is “mobydick”, then the base JIC would be olsen@mobydick and the full JID of the Client could be olsen@mobydick/c3kd82.

We use this principal in order to automatically build an internal connection with the Ressource name “phone” (olsen@mobydick/phone) for every known user. This internal connection reproduces in real time the direct status of the Asterisk Registration as well as the Telephone status on the XMPP Network and automatically distributes all changes on to authorized users (see below).

Through using this particular integration alone, every authorized person with a standard XMPP client can see the statues (free/busy) of other participants.

Command API

Every pascom Command and Event (so-called XMPP Command API) are packed into a XML element of the type cmd and with the attribute module.

Commands as XMPP IQ Stanzas

XMPP provides a variety of message types or Stanzas in XMPP Jargon, with specific features. For our interface we chose the so-called Info/Query, IQ for short. The RFC3920 explains in point 9.2.3 the underlying semantics.

In short, a IQ packet always ensures an answer in the form of either IQ Results or IQ Errors, somewhat similar to HTTP protocols. In principle, the answers arrive asynchronously, but there is a timeout after which has elapsed an Error Packet will be sent.

A complete XMPP IQ Packet with a Dial Command will look somewhat like the following:

<iq id="Uy13U-10" type="get">
  <cmd xmlns='http://www.pascom.net/mobydick' module='base'>
    <Dial target='mpasquay@entwicklung' />
  </cmd>
</iq>

In this way, the individual XML Elements originate from the following layers:

  • “iq” : is generated from the XMPP Stack from the User Library
  • “id”: Unique Packet Identifier. Normally this is also generated from the user library, later incoming responses will have the same ID
  • “cmd” : this is where the actual content begins.
  • “Dial” : The command to be executed.

As the IQ is directed to the server, there is no need to enter a “to” Address.

Events as XMPP Messages

Events will not be sent from the server in IQ Format, rather as simple XMPP Messages. Your system, therefore does not have to answer an incoming event. This process is somewhat comparable to a UDP packet. The server sends it, but the client does not confirm its receipt.

In the scenario of ChannelEvents, this could be displayed as follows:

<message to="tweber@mobydick/a4f8d33" from="pbx.mobydick">
    <cmd xmlns="http://www.pascom.net/mobydick" module="base">
        <ChannelEvent>
            <eventType>busy</eventType>
            <eventId>SIP/abDlFfq8x2726ee-00000559</eventId>
            <eventDetails>mailbox</eventDetails>
            <outbound>true</outbound>
            <internal>true</internal>
            <sourceName>Thomas Weber</sourceName>
            <sourceNumber>1234</sourceNumber>
            <sourceCallerIdName>Thomas Weber</sourceCallerIdName>
            <targetName>Mailbox</targetName>
            <targetCallerIdName/>
            <targetNumber>*100</targetNumber>
            <busySince>1385735733276</busySince>
            <refChannel/>
            <device>Snom 0004132726ee [my snom]</device>
            <fromName/>
            <fromNumber/>
        </ChannelEvent>
    </cmd>
</message>

Modules

The Attribute module plays an important role, which with the above example has the value base. The Command API is in various function areas divided into the so-called modules. On both the side of the client as well as the server side, it is useful to use the notion of Modules for the grouping of functions.

As far as it is possible, one should try to match these designations with the Modules already existing in the Commander Web User Interface. The REST API also uses the Module division as a construct of the URI.

From here onwards, commands will always be denoted in the format MODULE.CMDNAME. The 2 commands above are therefore called base.Dial and base.ChannelEvent respectively

Login Process

Immediately after the XMPP Login, the Command API expects a packet called xmppuser.ClientInfo.

It contains Environment information as well as a list of the subscribed to events. As an answer to this command the XMPP server then sends the xmppuser.UserInfo in reply. With the data contained therein then knows the complete state of the pascom Users, including the actual locations, available devices, Telephone and Fax Numbers etc.

For the exact Syntax of both Stanzas, please refer to the following Reference Sections.

Event Subscriptions

It goes without saying that you want to be able to react to typical events, such as an incoming call. As pascom produces a large number of events, it is wise to consider a performance application, to help you with which events you will actually use. The flood of information can cause problems, in particular for xmpp.supervisor authorized accounts. In order to receive these events, you now have to subscribe to them.

Static Subscription

Here you need to use the above named xmppuser.ClientInfo at login time to subscribe to events which you require for the complete running time of your Application.

Dynamic Subscription

Sometimes you will only need more data for a short period of time, because the user has opened their Application, e.g. a particular screen. In this case, simple expand the subscription dynamically via the event.AddSubscription. As soon as the user then closes the mask again, they will unsubscribe from the surplus events through the event.RemoveSubscription.

Subscription Filter

Depending on applications uses, you should now only be interested in very specific concrete events. In order to communicate your intentions the the system, you can use the so-called Subscription Filter. Using these filters allows you to map, for example to following scenarios:

  • specify a single event on a module
  • all events on a module (Wildcard)
  • as above but with additional comparisons of a particular attribute: e.g. only events in a particular queue or all queue events but only for a particular agent, etc.
  • if xmpp.supervisor rights are provided: as above but extended to the so-called Scope. Only shows events for the authenticated user or for all users.

Module “archive”

Abstract

Query the server based chat archive. All chat conversations are stored in the pascom Database. You can easily find archived messages with archive.* commands.

Commands

archive.FindDates

The use case is: you want to search for a certain term but you are only interested in the amount of conversations and the dates where the term was sent over the xmpp network.

You’ll get a archive.Dates response.

Example

<iq id="4Wefy-54" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="archive">
   <FindDates limit="100">
    <participant>mmeyer@mobydick</participant>
    <query>Project X</query>
  </FindDates>
</cmd>
</iq>

Usage

  • you can limit the result set to N entries by setting the “limit” attribute. Defaults to 100 if omitted.
  • the participant element is optional and can contain the bare JID of the 2nd user who participated in the conversations to be searched.
  • the query element is mandatory and must contain at least 3 characters.

archive.FindEntries

Use archive.FindEntries to retrieve the real chat entries and not a list of dates. You’ll receive a archive.EntryList response.

Example

<iq id="4Wefy-55" type="get">
 <cmd xmlns="http://www.pascom.net/mobydick" module="archive">
  <FindEntries limit="10">
    <fromdate>2013-10-01 01:00:00</fromdate>
    <todate>2013-12-01 01:00:00</todate>
    <participant/>
    <query>Project X</query>
  </FindEntries>
 </cmd>
</iq>

Usage

  • you can limit the result set to N entries by setting the “limit” attribute. Defaults to 100 if omitted.
  • fromdate is mandatory and contains the first timestamp for your search. You can set it as “1970-01-01 01:00:00” should you want to search without a time boundary.
  • todate is optional and can contain a second timestamp to set a time boundary for the query.
  • the participant element is optional and can contain the bare JID of the 2nd user who participated in the conversations to be searched.
  • the query element is mandatory and must contain at least 3 characters.

Responses

archive.Dates

Contains a list of archive.date entries, which in turn contains exactly one archive.ArchiveEntry for the first occurence of the given search term within the searched date criteria.

Example

<iq id="4Wefy-54" to="tweber@mobydick/mdfxclient_tw-macbook.in.pascom.net" type="result">
  <cmd xmlns="http://www.pascom.net/mobydick" module="archive">
  <Dates>
    <Date date="2013-10-21">
      <ArchiveEntry timestamp="2013-10-21 13:10:37" from="mmeyer@mobydick" to="tweber@mobydick" conversationid="1756">
        <body>We need to talk about Project X</body>
      </ArchiveEntry>
    </Date>
    <Date date="2013-10-23">
      <ArchiveEntry timestamp="2013-10-23 13:38:16" from="mmeyer@mobydick" to="tweber@mobydick" conversationid="2022">
        <body>Customer has a new idea about Project X</body>
      </ArchiveEntry>
    </Date>
    <Date date="2013-11-10">
      <ArchiveEntry timestamp="2013-11-10 08:55:09" from="tweber@mobydick" to="mmeyer@mobydick" conversationid="2065">
        <body>Did you implement the Project X changes?</body>
      </ArchiveEntry>
    </Date>
    <Date date="2013-11-12">
      <ArchiveEntry timestamp="2013-11-12 13:26:53" from="tweber@mobydick" to="mmeyer@mobydick" conversationid="2253">
        <body>Looks like we can finish Project X in Time!</body>
      </ArchiveEntry>
    </Date>
  </Dates>
</cmd>
</iq>

archive.ArchiveEntryList

Contains a list of archive.ArchiveEntry elements which mention the given search term.

Example

<iq id="4Wefy-55" to="tweber@mobydick/mdfxclient_tw-macbook.in.pascom.net" type="result">
  <cmd xmlns="http://www.pascom.net/mobydick" module="archive">
   <ArchiveEntryList>
      <ArchiveEntry timestamp="2013-10-21 13:10:37" from="mmeyer@mobydick" to="tweber@mobydick" conversationid="1756">
        <body>We need to talk about Project X</body>
      </ArchiveEntry>
      ..
      ..
      ..
    </ArchiveEntryList>
</cmd>
</iq>

Events

This Module does not send any events.

Module “base”

Abstracts

Basic telephony features and generic commands. Place phone calls, transfer or pickup a call.

Commands

base.Dial

Use this command if you would like to phone somebody. As a response, you will receive either of: base.success or base.failure

Example

<iq id="8Wefy-61" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="base">
   <Dial target='08955555555' prefix='auto'/>
  </cmd>
</iq>

Usage

  • prefix can be either a number or the special value ‘auto’. Auto will figure out if you need any additional prefixes/zero’s to reach the given target.
  • instead of target and prefix you can also use the attribute viasetting.
  • It can contain the full path of a pascom system setting and functions as an indirection: i.e. it will dial the number which is stored in this setting.example: viasetting=“sys.asterisk.dialplan.global.voicebox.own.value” will dial “*100” to reach the personal voicemail box of the authenticated user.
  • optionally you can add a device attribute to explicitly use a specific phone if the user has more then one assigned. Otherwise the first available phone with the “dial” capability will place the call.

base.DialFrom

A xmpp.supervisor user can place a phone call on behalf of another user. As a response, they will receive either of: base.success or base.failure

Example

<iq id="8Wefy-62" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="base">
   <DialFrom identity='mmeyer' target='08955555555' prefix='auto'/>
  </cmd>
</iq>

Usage

  • identity is mandatory and must contain a valid pascom username
  • see base.Dial for further details.

base.Hangup

Each user has the permission to end their phone calls. A supervisor can additionally hangup arbitrary channels from within the total system. As a response, they will receive either of: base.success or base.failure.

Example

<iq id="8Wefy-63" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="base">
   <Hangup channel='SIP/xlite1-00000004'/>
  </cmd>
</iq>

Usage

  • the channel id is optional for non-supervisor users. You’ll hangup the most recent call if this attribute is omitted.
  • If you have multiple concurrent calls (one is put on hold for example): use the channel id from a previously received base.ChannelEvent
  • alternatively you can send a phone.Hangup if the call is active on a device with hangup capability.

base.Transfer

Each user has the permission to transfer an active phone call to another target. A supervisor can additionally transfer arbitrary channels in the whole system. As a response, they will receive either of: base.success or base.failure.

Example

<iq id="8Wefy-64" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="base">
   <Transfer channel="SIP/xlite1-00000118" target="320" prefix="auto"/>
  </cmd>
</iq>

Usage

  • the channel id is mandatory, use the channel id from a previously received base.ChannelEvent
  • target and prefix are similar to a base.Dial command

base.Pickup

If your user receives a notification about a pickup possibility, they can send this command to fetch the ringing channel from another user. As a response, they will receive either of: base.success or base.failure.

Example

<iq id="8Wefy-65" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="base">
   <Pickup target='320' device='SIP xlite1 [Development]'/>
  </cmd>
</iq>

Usage

  • target is mandatory and contains the internal phone number of the user you want to pick a call from
  • device is optional and can contain the device which will perform the pickup, see base.Dial for more details

Responses

base.Success

If there is no command specific response available, you’ll receive a friendly base.Success with some optional text. It’s the Command API equivalent to a HTTP “200 OK”.

Example

<iq id="8Wefy-65" to="tweber@mobydick/mdfxclient_tw-macbook.in.pascom.net" type="result">
  <cmd xmlns="http://www.pascom.net/mobydick" module="base">
    <Success>
      <message>Ok</message>
    </Success>
  </cmd>
</iq>

base.Failure

Whenever something goes wrong on the application layer you will get this response.

Example

<iq id="8Wefy-64" to="tweber@mobydick/mdfxclient_tw-macbook.in.pascom.net" type="result">
  <cmd xmlns="http://www.pascom.net/mobydick" module="base">
    <Failure>
      <message>Transfer not successfull</message>
    </Failure>
  </cmd>
</iq>

Events

base.ChannelEvent

Each change in the state of one of your phone calls triggers a base.ChannelEvent. It’s one of the most fundamental events in the pascom system.

A normal user only gets the base.ChannelEvents which directly affect the authenticated user. A supervisor can, however, subscribe to all ChannelEvent’s but still limit the amount with filters.

Example

<message to="tweber@mobydick/mdfxclient_tw-macbook.swe.local" from="pbx.mobydick">
 <cmd xmlns="http://www.pascom.net/mobydick" module="base">
  <ChannelEvent>
    <eventType>ringing</eventType>
    <eventId>SIP/xlite1-0000011c</eventId>
    <eventDetails/>
    <outbound>false</outbound>
    <internal>true</internal>
    <sourceName>Thomas Mattausch</sourceName>
    <sourceNumber>370</sourceNumber>
    <sourceCallerIdName/>
    <targetName>Thomas Weber</targetName>
    <targetCallerIdName/>
    <targetNumber>340</targetNumber>
    <busySince>0</busySince>
    <refChannel/>
    <device>SIP xlite1 [Entwicklung1]</device>
    <fromName/>
    <fromNumber/>
    <LabelList>
          <Label >
                <id>MDC_LABEL-1</id>
                <displayName>VIP</displayName>
                <type>generic</type>
                <value>1</value>
                <visible>true</visible>
          </Label>
     </LabelList>
  </ChannelEvent>
</cmd>
</message>

Some notes

  • eventType: the state of the given call:
    • ringing = a new caller is knocking on your users’ door, or rather their earpiece or phone
    • busy = the user is phoning with the calling party
    • hold = the user holds this call
    • unhold = hold flag has been removed
    • transfer = this call is being transferred to somebody else
    • rename = the callerid changed for some reason. Can be a new name or a new number.
    • redirect = the call is redirected to somebody else
    • hangup = the call ends
  • eventId: tells you about the id of the asterisk channel which triggered this xmpp event. Use it in subsequent calls like base.transfer
  • device: holds the name of the phone device which was/is affected by this event. You can use this information in subsequent calls to various base.* or phone.* commands.

base.PickupEvent

Subscribe to base.PickupEvent if your authenticated user is eligible to pickup a call from another user and your application can display a hint in this situation.

Example

<message to="tweber@mobydick/mdfxclient_tw-macbook.swe.local" from="pbx.mobydick">
 <cmd xmlns="http://www.pascom.net/mobydick" module="base">
   <PickupEvent>
    <eventType>ringing</eventType>
    <eventId>tmattausch</eventId>
    <target>370</target>
    <sourceName>Mathias Pasquay</sourceName>
    <sourceNumber>320</sourceNumber>
  </PickupEvent>
</cmd>
</message>

Some notes

  • eventType: the state of the pickup possibility:
    • ringing = you can pickup from now on
    • gone = you can not pickup the call anymore, someone else took the call or caller hung up themselves
  • eventId/target: contains the username and the internal phone number of your fellow pickup group member. Remember the eventId in case you want to send a base.Pickup command.
  • sourceName/sourceNumber: tells you about the person who is calling the target

Module “event”

Abstract

Manage Command-API Event Subscriptions. Does your application need realtime data from the telephony system? Just add some subscriptions and the xmppserver keeps your data model up to date.

Commands

event.AddSubscription

Subscribe to more events. Each AddSubscription command contains one or more Subscription sub elements. The Subscription itself has a flexible syntax to express various filters.

Complex Example

<iq id="bWxfy-4" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="event">
    <AddSubscription>
      <Subscription module="base" type="*" scope="user"/>
      <Subscription module="journal" type="*"/>
      <Subscription module="base" type="ChannelEvent" scope="supervisor"/>
      <Subscription module="queue" type="*">
        <AttributeFilter name="queue" equals="Support"/>
      </Subscription>
    </AddSubscription>
  </cmd>
</iq>

Here we add 4 Subscriptions:

  1. all events from the module “base” which affect the authenticated user.
  2. all events from the module “journal” which affect the authenticated user. The attribute scope=“user” can be omitted as it is the default value.
  3. all base.ChannelEvent events for all users. You will only get the events if the authenticated user has been assigned the xmpp.supervisor role type.
  4. all events for the queue “Support” but only if the authenticated user is a member of this team or has been assigned the xmpp.supervisor role type.

Usage

You can call event.AddSubscription independently at any time or you can embed it in the xmppuser.ClientInfo command. Its possible to send multiple AddSubscription commands for the same command or to have overlapping filters. The system will still ensure that you’ll receive each event only once.

Expect a response type of either event.SubscriptionList or base.Failure

event.RemoveSubscription

Imagine you are writing a queue monitor to visualize the current load of one team (and only 1 Team). To limit your applications load, you would of course only subscribe to the queue’s events for the period of time that your application is actually open. If the user opens the queue monitor window you would send out a event.AddSubscription and if the window is then later closed you would in turn call the event.RemoveSubscription.

Example

<iq id="bWxfy-9" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="event">
    <RemoveSubscription>
      <Subscription module="queue" type="*">
        <AttributeFilter name="queue" equals="Support"/>
      </Subscription>
    </RemoveSubscription>
  </cmd>
</iq>

Usage

event.RemoveSubscription can be called at any time and yields either a event.SubscriptionList or base.Failure response.

Responses

event.SubscriptionList

Whenever you change the subscriptions of your xmpp session you’ll get a event.SubscriptionList as a response. It’s also embedded in the initial ClientInfo/UserInfo handshake. It contains the effective list of subscriptions at any given time and follows the AddSubscription/RemoveSubscription syntax.

Example

<iq id="bWxfy-4" to="tweber@mobydick/mdfxclient_tw-macbook.in.pascom.net" type="result">
  <cmd xmlns="http://www.pascom.net/mobydick" module="event">
    <SubscriptionList>
      <Subscription module="base" type="*" scope="user"/>
      <Subscription module="journal" type="*" scope="user"/>
      <Subscription module="base" type="ChannelEvent" scope="supervisor"/>
      <Subscription module="queue" type="*" scope="user">
        <AttributeFilter name="queue" equals="Support"/>
      </Subscription>
    </SubscriptionList>
  </cmd>
</iq>

Events

This Module does not send any events.

Module “journal”

Abstract

Get data about recent phone calls. You can ask the xmppserver for a list of recent phone calls or you can subscribe to the journal.JournalEvent to get changes automatically.

Commands

journal.FindOwn

Just call journal.FindOwn to retrieve the authenticated users’ list of recent phone calls.

Example

Usage

You can call journal.FindOwn at any time and it will be answered by a journal.JournalList packet. The limit Attribute is optional and will default to the value 100 if omitted.

journal.FindByIdentity

If your application is authenticated with xmpp.supervisor permissions you can additionally request the journal for every other user:

In the above scenario, you will be provided with the journal from user “jdoe”.

Responses

journal.JournalList

Example

<iq id="bWjfy-18" to="tweber@mobydick/mdfxclient_tw-macbook.in.pascom.net" type="result">
  <cmd xmlns="http://www.pascom.net/mobydick" module="journal">
  <JournalList>
    <JournalEntry eventId="771" eventType="create" userId="6" userName="tweber">
      <id>771</id>
      <timestamp>1386080714363</timestamp>
      <inbound>true</inbound>
      <internal>true</internal>
      <duration>0</duration>
      <connected>0</connected>
      <deviceId>0</deviceId>
      <deviceName/>
      <locationId>0</locationId>
      <locationName/>
      <name>Thomas Mattausch</name>
      <number>370</number>
      <prefix/>
      <result>redirect</result>
      <resultDetails>from</resultDetails>
      <via/>
      <viaDetails/>
      <extension>340</extension>
      <recordId>1386080714363-21_1386080714363-28</recordId>
    </JournalEntry>
    ...
    ...
 </JournalList>
</iq>

Notes

  • recordId: will not be empty if at least one recording was triggered in this call. See Module “monitor” for Details.

Events

journal.JournalEntry

If you subscribe to the journal.JournalEntry event, you’ll be notified whenever the user finishes a phone call.

Module “location”

Abstract

Switch to another location. Roaming. Hot desking.

Commands

location.Find

Asks pascom for possible locations of the authenticated user. You’ll receive a location.LocationList as response.

Example

<iq id="9JeHy-73" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="location">
   <Find/>
  </cmd>
</iq>

location.RelocateUser

Switch from one location to another. The direct response is a base.Success accompanied by a either location.SetLocation event or base.Failure.

Example

<iq id="9JeHy-74" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="location">
   <RelocateUser location="Backoffice"/>
  </cmd>
</iq>

Usage

  • location is mandatory and must contain a valid pascom location name, use location.Find to search possible target locations.

location.LogoutUser

Tells pascom that the currently authenticated user is signing off from their current location. The direct response is a base.Success accompanied by either a location.SetLocation event or base.Failure.

Example

<iq id="9JeHy-74" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="location">
   <LogoutUser/>
  </cmd>
</iq>

Responses

location.LocationList

A location.LocationList response contains a number of Location elements.

Example

<iq id="9JeHy-73" to="tweber@mobydick/mdfxclient_tw-macbook.in.pascom.net" type="result">
  <cmd xmlns="http://www.pascom.net/mobydick" module="base">
   <LocationList>
    <Location name="Support" isstatic="false" username="tmattausch"/>
    <Location name="Sales" isstatic="false" username="mpasquay"/>
    <Location name="Backoffice" isstatic="false" username=""/>
    <Location name="Development" isstatic="false" username="tweber"/>
  </LocationList>  
  </cmd>
</iq>

Usage

  • If sent as a response to location.Find, it’ll contain no device specific details, instead a stripped down version is used.
  • username: who is currently using this location. If you decide to perform a location.RelocateUser on the username, you’ll kick this user out of this location.

Events

location.SetLocation

You can subscribe to this event if your application needs to now if the authenticated user is switching to another location.

Example

<message to="tweber@mobydick/mdfxclient_tw-macbook.swe.local" from="pbx.mobydick">
 <cmd xmlns="http://www.pascom.net/mobydick" module="base">
   <SetLocation eventType="login" eventId="">
    <LocationList>
      <Location name="Thomas Weber" isstatic="true" username=""/>
      <Location name="Entwicklung2" isstatic="false" username="">
        <DeviceEntry delayinternal="0" timeoutinternal="20" delayexternal="0" timeoutexternal="20" delayqueue="0" timeoutqueue="20">
          <Phonedevice name="Snom 000413411c47 [Entwicklung2]" type="Snom Phone">
            <capabilities>
              <conference/>
              <dial/>
              <factory_reset/>
              <firmware_update/>
              <hangup/>
              <hold/>
              <transfer/>
              <offhook/>
              <reboot/>
            </capabilities>
          </Phonedevice>
        </DeviceEntry>
      </Location>
    </LocationList>
  </SetLocation>
</cmd>
</message>

Some notes

  • SetLocation contains one or two Location elements.
  • The first one (isstatic=true) is always included and denotes the users fixed set of devices. It should contain a personal DECT handset or a mobile phone which are not typically bound to a physical location/desktop.
  • the second Location element is optional and contains the currently used flexible location
    • within the Location elements you see a set of DeviceEntry containers holding the effective timing parameters for each device.
    • a Phonedevice finally shows a assigned hard- or softphone with its name and supported capabilities

Module “mobile”

Abstract

Use the pascom mobile gateway for you own apps.

Commands

mobile.PrepareDial

Send a mobile.PrepareDial to the mobile hub gateway in order to predefine a internal or external target number which will be called when you call the gateway number.

The response is a mobile.ReadyToDial acknowledgement or a base.Failure.

Example

<iq id="7Eefr-85" type="get">
 <cmd xmlns="http://www.pascom.net/mobydick" module="mobile">
  <PrepareDial device="Sales Cellphone" target="0895555555" prefix="auto"/>
 </cmd>
</iq>

Usage

  • device is mandatory and chooses the to-be-used phone. It must have the “fully integrated mobilephone” device type.
  • all other attributes are similar to the base.Dial syntax
  • this command does not place a call. The workflow is:
    1. send a mobile.PrepareDial command
    2. get back the responsible gateways number
    3. use GSM or another technology and dial the number of the gateway (could be a different device, must not be xmpp enabled!)
    4. you’ll now be connected to the prepared target

Responses

mobile.ReadyToDial

Send a mobile.PrepareDial to the mobile hub gateway in order to predefine a internal or external target number which will be called when you call the number of the gateway.

The response is a mobile.ReadyToDial acknowledgement or a base.Failure.

Example

<iq id="7Eefr-85" type="result">
 <cmd xmlns="http://www.pascom.net/mobydick" module="mobile">
  <ReadyToDial gateway="089444444444"/>
 </cmd>
</iq>

Events

This Module does not send any events.

Module “monitor”

Abstract

Control call recording and access recordings.

Commands

monitor.Start

Start a recording of a busy channel. It will only succeed if the ruleset allows the access from the authenticated user to the given channel.

Example

<iq id="bWjfh-33" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="monitor">
    <Start channel="SIP/xlite1-00000003"/>
  </cmd>
</iq>

Usage

You can call monitor.Start if you received a monitor.RecordEvent informing you about the channel and your permissions. The Command is answered either by base.Success or base.Failure and followed by one or more incoming monitor.RecordEvent packages. It might happen that the channel and user combination matches multiple recording rules which will mean that you start more then one recording at the same time.

monitor.Stop

Stop a recording. You can only stop manually started recordings owned by the authenticated user.

Example

<iq id="bWjfh-34" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="monitor">
    <Stop channel="SIP/xlite1-00000003"/>
  </cmd>
</iq>

Usage

You can call monitor.Stop if you have received a monitor.RecordEvent informing you about the channel, the active recording and your permissions. The Command is answered either by base.Success or base.Failure and followed by one or more incoming monitor.RecordEvent packages.

monitor.FindRecord

Request recording related data for one specific call. You can find the necessary recordId by using a journal.JournalEntry or a previously received monitor.RecordEvent.

Example

<iq id="bWjfh-37" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="monitor">
     <FindRecord recordId="1392385689-178_1392385689-187"/>
  </cmd>
</iq>

Usage

You can call monitor.FindRecord at any time. Expect a monitor.RecordEntry or a base.Failure as a response.

monitor.InitTransfer

Request a recorded audio file from the server.

Example

<iq id="zQSwg-82" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="monitor">
  <InitTransfer recordId="1392385689-178_1392385689-187" ruleId="1" file="1" format="wav" description="monitor_1392385689-178_1392385689-187_1_1_wav@player"/>
</cmd>
</iq>

Usage

Each audio file can be addressed by the following attributes:

  • recordId: the unique id of the call
  • ruleId: the rule which permitted/triggered the recoding
  • file: section number starting with 1 for the first recording within this call.
  • format: only “wav” is possible at this time
  • description: the server will use this string as the description of the incoming file transfer. You can relate the request and the asynchronously started transfer by using this attribute.

The Command is answered either by base.Success or base.Failure and followed by an incoming file transfer request.

Responses

monitor.RecordEntry

A monitor.RecordEntry contains all the information concerning one specific recorded phone call. It includes the whole journal.JournalEntry as well as a list of monitor.Record Elements with details about the audio files.

Example

<iq id="zQSwg-111" to="tweber@mobydick/mdclient_tw-macbook.local" type="result">
  <cmd xmlns="http://www.pascom.net/mobydick" module="monitor">
  <RecordEntry id="1392385689-178_1392385689-187">
    <JournalEntry eventId="1496" eventType="create" userId="6" userName="tweber">
      <id>1496</id>
      <timestamp>1392385691386</timestamp>
      <inbound>false</inbound>
      <internal>true</internal>
      <duration>28</duration>
      <connected>26</connected>
      <deviceId>11</deviceId>
      <deviceName>Snom 0004132726ee [Thomas Weber]</deviceName>
      <locationId>9</locationId>
      <locationName>Thomas Weber</locationName>
      <name>Mathias Pasquay</name>
      <number>826</number>
      <prefix/>
      <result>hangup</result>
      <resultDetails/>
      <via/>
      <viaDetails/>
      <extension>822</extension>
      <recordId>1392385689-178_1392385689-187</recordId>
    </JournalEntry>
    <Record duration="10" ruleId="1" file="1" state="n" type="manual">
      <AudioFile format="wav" size="145004"/>
    </Record>
    <Record duration="13" ruleId="1" file="2" state="n" type="manual">
      <AudioFile format="wav" size="165004"/>
    </Record>
  </RecordEntry>
</cmd>
</iq>

Events

monitor.RecordEvent

The monitor.RecordEvent provides information both about the possibility to record and also for tracking the state of an ongoing recording.

Example

<message to="tweber@mobydick/mdclient_tw-macbook.swe.local" from="pbx.mobydick">
  <cmd xmlns="http://www.pascom.net/mobydick" module="monitor">
  <RecordEvent eventType="stop" eventId="1392965320-21_1392965320-28" ruleId="1" permission="allow" identity="" file="">
    <headchannel>SIP/xlite2-00000007</headchannel>
    <tailchannel>SIP/xlite1-00000008</tailchannel>
  </RecordEvent>
</cmd>
</message>

Details

  • eventType: start or stop, informs you of whether the recording is currently active
  • eventId: use this as recordId to access the files later (see monitor.FindRecording)
  • ruleId: the rule which permitted/triggered the recoding
  • permission: auto = the system is recording automatically, you have no control over it, allow = the authenticated user can start or stop the recording, or deny = another user has control over this recording
  • identity: who owns the recording?
  • file: section number starting with 1 for the first recording within this call.
  • headchannel: Channel-ID of the calling channel. Use this to relate monitor.RecordEvent with base.ChannelEvent
  • tailchannel: Channel-ID of the called channel. Use this to relate monitor.RecordEvent with base.ChannelEvent

Module “phone”

Abstract

Control a supported phone device remotely. You can remotely control several features on supported phones without the having the burden of manufacturer/model low level access.

Commands

phone.Hangup

Send a hangup/decline/cancel keypress to the given phone. Answered by a base.Success or base.Failure response.

Example

<iq id="7Eefr-85" type="get">
 <cmd xmlns="http://www.pascom.net/mobydick" module="phone">
  <Hangup device="Snom 000413260a1b [Sales]"/>
 </cmd>
</iq>

phone.Hold

Send a hold keypress to the given phone. Answered by a base.Success or base.Failure response. On most phones this can also unhold a call. You need to track the base.ChannelEvent state if you want to implement a hold/unhold logic.

Example

<iq id="7Eefr-86" type="get">
 <cmd xmlns="http://www.pascom.net/mobydick" module="phone">
  <Hold device="Snom 000413260a1b [Sales]"/>
 </cmd>
</iq>

phone.Offhook

Send a offhook/accept keypress to the given phone. Answered by a base.Success or base.Failure response. Typically this is bound to some “accept incoming call” buttons in the client application and most useful if the user has a headset.

Example

<iq id="7Eefr-87" type="get">
 <cmd xmlns="http://www.pascom.net/mobydick" module="phone">
  <Offhook device="Snom 000413260a1b [Sales]"/>
 </cmd>
</iq>

phone.Transfer

Send a transfer keypress to the given phone. Answered by a base.Success or base.Failure response. This can trigger an attended transfer in case there is a held channel and an active one. You need to track the base.ChannelEvent state if you want to implement a smart behaviour.

Example

<iq id="7Eefr-88" type="get">
 <cmd xmlns="http://www.pascom.net/mobydick" module="phone">
  <Transfer device="Snom 000413260a1b [Sales]"/>
 </cmd>
</iq>

phone.Conference

Send a conference keypress to the given phone. Answered by a base.Success or base.Failure response. This can trigger a 3-person-conference in case there is a held channel and a active one. You need to track the base.ChannelEvent state if you want to implement a smart behaviour.

Example

<iq id="7Eefr-89" type="get">
 <cmd xmlns="http://www.pascom.net/mobydick" module="phone">
  <Conference device="Snom 000413260a1b [Sales]"/>
 </cmd>
</iq>

Responses

This Module does not send any module specific responses.

Events

This Module does not send any events.

Module “phonebook”

Abstract

Access the pascom phonebook

Commands

phonebook.FindAll

If you really need it: phonebook.FindAll fetches the full pascom phonebook.

Example

<iq id="bWHfh-34" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="phonebook">
    <FindAll/>
  </cmd>
</iq>

Usage

You can call phonebook.FindAll at any time and it will be answered by a phonebook.PhonebookList packet.

phonebook.Find

Query all phonebook entries for a given substring. It will perform a substring match in all fields.

Example

<iq id="bWHfh-35" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="phonebook">
    <Find query="meyer"/>
  </cmd>
</iq>

Usage

You can call phonebook.Find at any time and it will be answered by a phonebook.PhonebookList packet.

Responses

phonebook.PhonebookList

Example

<iq id="bWHfh-35" to="tweber@mobydick/mdfxclient_tw-macbook.in.pascom.net" type="result">
  <cmd xmlns="http://www.pascom.net/mobydick" module="phonebook">
  <PhonebookList>
    <PhonebookEntry eventId="" eventType="">
      <type>011account</type>
      <id>Markus Meyer</id>
      <firstname>Markus</firstname>
      <surname>Meyer</surname>
      <phone>555</phone>
      <fax/>
      <mobile/>
      <homephone/>
      <email>markus.meyer@mobydick.local</email>
      <displayname>Markus Meyer</displayname>
      <organisation/>
      <LabelList>
          <Label >
                <id>MDC_LABEL-1</id>
                <displayName>VIP</displayName>
                <type>generic</type>
                <value>1</value>
                <visible>true</visible>
          </Label>
       </LabelList>
    </PhonebookEntry>
    ...
    ...
   </PhonebookList>
  </cmd>
</iq>

Events

This Module does not send any events.

Module “queue”

Abstract

Access queue states and manage your agent statuses.

Commands

queue.FindOwnState

Send a queue.FindOwnState to request the state of all the queues of which the authorised user is a member.

Example

<iq id="kJHfh-39" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="queue">
    <FindOwnState/>
  </cmd>
</iq>

Usage

You can call queue.FindOwnState at any time and you’ll get a queue.QueueMemberStates as a response. The response contains only the queue.QueueMemberState entries for the given agent, additional state information from other agents or waiting calls will be included. The initial state is also included in the xmppuser.ClientInfo/xmppuser.UserInfo handshake.

queue.FindQueueState

Query the full state of one queue.

<iq id="bWHfh-36" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="queue">
    <FindQueueState name="Support"/>
  </cmd>
</iq>

Usage

You can call queue.FindQueue at any time and you’ll get a full queue.QueueState Response. Only users with xmpp.supervisor permission can access all the queues, otherwise you can only get the state of the queues of which the authenticated user is a member.

queue.AgentLogin

Use this to log a dynamic agent into a queue.

<iq id="bWHfh-37" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="queue">
    <AgentLogin queue="Support" penalty=""/>
  </cmd>
</iq>

Usage

You can call queue.AgentLogin if the authenticated user is a dynamic agent in the given queue and if they are not already logged in. The response is either a base.Success or base.Failure packet. The penalty value is optional and can be omitted.

queue.AgentLogout

Use this command to sign out from a queue.

<iq id="bWHfh-38" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="queue">
    <AgentLogout queue="Support"/>
  </cmd>
</iq>

Usage

You can call queue.AgentLogout if the authenticated user is a dynamic agent in the given queue and if they are currently logged in. The response is either a base.Success or base.Failure packet.

queue.AgentPause

Set the agents state to pause.

<iq id="bWHfh-39" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="queue">
    <AgentPause queue="Support" reason="postprocessing"/>
  </cmd>
</iq>

Usage

You can call queue.AgentPause if the authenticated user is either a static queue member or if they are currently logged in to the given queue. The response is either a base.Success or base.Failure packet. The reason value is an arbitrary string which will end up in the queuelog, it can also be empty.

queue.AgentUnpause

Removes the agents pause state.

<iq id="bWHfh-39" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="queue">
    <AgentUnpause queue="Support" reason="postprocessing"/>
  </cmd>
</iq>

Usage

You can call queue.AgentUnpause if the authenticated user is currently paused in the given queue. The response is either a base.Success or base.Failure packet. The reason value is an arbitrary string which will end up in the queuelog, it can also be empty.

Responses

queue.QueueMemberStates

Is a list of membership states. Each queue.QueueMemberState element contains information about the state of one agent in one queue.

Example

<iq id="kJHfh-39" to="tweber@mobydick/mdfxclient_tw-macbook.in.pascom.net" type="result">
  <cmd xmlns="http://www.pascom.net/mobydick" module="queue">
  <QueueMemberStates eventType="" eventId="">
      <QueueMemberState agent="tweber" queue="Support" dynamic="true" loggedin="false" paused="false" eventType="" eventId="" pauseReason="">
        <PhonebookEntry eventId="" eventType="">
          <type></type>
          <id/>
          <firstname/>
          <surname/>
          <phone>340</phone>
          <fax/>
          <mobile/>
          <homephone/>
          <email/>
          <displayname>Thomas Weber</displayname>
          <organisation/>
        </PhonebookEntry>
      </QueueMemberState>
      ...
      ...
    </QueueMemberStates>
  </cmd>
</iq>

queue.QueueStates

Contains the complete state of one queue.

The overall structure is as follows:

  • QueueState (id and name of the queue)
    • QueueCallEntryList
    • QueueCallEntry (First waiting call)
    • QueueCallEntry (Second waiting call)
    • QueueMemberStates
    • QueueMemberState (State of agent 1)
    • QueueMemberState (State of agent 2)
    • ueuePauseReasonList
      • QueuePauseReason

Example

<iq id="kJHfh-36" to="tweber@mobydick/mdfxclient_tw-macbook.in.pascom.net" type="result">
  <cmd xmlns="http://www.pascom.net/mobydick" module="queue">
   <QueueState jid="q_1" name="support">
    <QueueCallEntryList>
      <QueueCallEntry>
        <position>1</position>
        <channel>SIP/xlite3-0000010d</channel>
        <uniqueId>1386314874.1225</uniqueId>
        <PhonebookEntry eventId="" eventType="">
          <type>undef</type>
          <id/>
          <firstname/>
          <surname/>
          <phone>370</phone>
          <fax/>
          <mobile/>
          <homephone/>
          <email/>
          <displayname>Thomas Mattausch</displayname>
          <organisation/>
        </PhonebookEntry>
      </QueueCallEntry>
    </QueueCallEntryList>
    <QueueMemberStates eventType="" eventId="">
      <QueueMemberState agent="tweber" queue="support" dynamic="true" loggedin="false" paused="false" eventType="" eventId="" pauseReason="">
        <PhonebookEntry eventId="" eventType="">
          <type>undef</type>
          <id/>
          <firstname/>
          <surname/>
          <phone>340</phone>
          <fax/>
          <mobile/>
          <homephone/>
          <email/>
          <displayname>Thomas Weber</displayname>
          <organisation/>
        </PhonebookEntry>
      </QueueMemberState>
      <QueueMemberState agent="mmeyer" queue="support" dynamic="true" loggedin="false" paused="false" eventType="" eventId="" pauseReason="">
        <PhonebookEntry eventId="" eventType="">
          <type>undef</type>
          <id/>
          <firstname/>
          <surname/>
          <phone>360</phone>
          <fax/>
          <mobile/>
          <homephone/>
          <email/>
          <displayname>Markus Meyer</displayname>
          <organisation/>
        </PhonebookEntry>
      </QueueMemberState>
      <QueueMemberState agent="mpasquay" queue="support" dynamic="false" loggedin="true" paused="false" eventType="" eventId="" pauseReason="">
        <PhonebookEntry eventId="" eventType="">
          <type>undef</type>
          <id/>
          <firstname/>
          <surname/>
          <phone>320</phone>
          <fax/>
          <mobile/>
          <homephone/>
          <email/>
          <displayname>Mathias Pasquay</displayname>
          <organisation/>
        </PhonebookEntry>
      </QueueMemberState>
    </QueueMemberStates>
    <QueuePauseReasonList>
      <QueuePauseReason code="10">
        <reason>Backoffice</reason>
      </QueuePauseReason>
      <QueuePauseReason code="20">
        <reason>Lunch</reason>
      </QueuePauseReason>
    </QueuePauseReasonList>
  </QueueState>
  </cmd>
</iq>

Notes

The QueueState can contain a list of “QueuePauseReason” Elements. It contains the pause reasons obtained from the web-ui including the dial code and the reason text. You can use it to present a “pause chooser” in your application.

If this list is empty, then the Pausing feature will be universally disabled!

Events

Depending on the permissions of the authenticated user you will notified and have access to more or less data/information. Normal users:

  • state changes for all agents of every queue of which the user is a member.
  • calls waiting within all of the queues of which the user is a member.

User has xmpp.supervisor permission:

  • state changes for every agent in every queue.
  • calls waiting with every queue

Of course you can limit the amount of data by using a subscription filter.

queue.QueueMemberState

The Event is fired:

  • if pause state changes
  • if login state changes

For free/busy information you can just use the universal presence information, you’ll not receive any additional events.

Example

<message to="tweber@mobydick/mdfxclient_tw-macbook.swe.local" from="pbx.mobydick">
  <cmd xmlns="http://www.pascom.net/mobydick" module="queue">
  <QueueMemberState agent="tweber" queue="support" dynamic="true" loggedin="true" paused="false" eventType="" eventId="" pauseReason="">
    <PhonebookEntry eventId="" eventType="">
      <type>undef</type>
      <id/>
      <firstname/>
      <surname/>
      <phone>340</phone>
      <fax/>
      <mobile/>
      <homephone/>
      <email/>
      <displayname>Thomas Weber</displayname>
      <organisation/>
    </PhonebookEntry>
  </QueueMemberState>
</cmd>
</message>

queue.QueueJoinEvent

This event informs your application about a new call waiting within one queue.

Example

<message to="tweber@mobydick/mdfxclient_tw-macbook.swe.local" from="pbx.mobydick">
  <cmd xmlns="http://www.pascom.net/mobydick" module="queue">
  <QueueJoinEvent jid="q_1" name="support">
    <QueueCallEntry>
      <position>1</position>
      <channel>SIP/xlite3-00000116</channel>
      <uniqueId>1386315777.1234</uniqueId>
      <PhonebookEntry eventId="" eventType="">
        <type>undef</type>
        <id/>
        <firstname/>
        <surname/>
        <phone>370</phone>
        <fax/>
        <mobile/>
        <homephone/>
        <email/>
        <displayname>Thomas Mattausch</displayname>
        <organisation/>
      </PhonebookEntry>
    </QueueCallEntry>
  </QueueJoinEvent>
</cmd>
</message>

queue.QueueLeaveEvent

Whenever a call which has been waiting reaches an agent you’ll get a queue.QueueLeaveEvent. It is also sent if the caller hangs up themselves.

Example

<message to="tweber@mobydick/mdfxclient_tw-macbook.swe.local" from="pbx.mobydick">
  <cmd xmlns="http://www.pascom.net/mobydick" module="queue">
  <QueueLeaveEvent jid="q_1" name="support">
    <QueueCallEntry>
      <position>1</position>
      <channel>SIP/xlite3-00000116</channel>
      <uniqueId>1386315777.1234</uniqueId>
      <PhonebookEntry eventId="" eventType="">
        <type>undef</type>
        <id/>
        <firstname/>
        <surname/>
        <phone>370</phone>
        <fax/>
        <mobile/>
        <homephone/>
        <email/>
        <displayname>Thomas Mattausch</displayname>
        <organisation/>
      </PhonebookEntry>
    </QueueCallEntry>
  </QueueLeaveEvent>
</cmd>
</message>

Module “redirect”

Abstract

Manage server based call deflection.

Commands

redirect.FindOwn

Just call redirect.FindOwn to retrieve the authenticated users’ deflection state. This command is rarely used because the initial deflection state is embedded within the xmppuser.UserInfo packet and you can additionally subscribe to redirect.RedirectEntry for state changes.

Example

<iq id="bWjfh-22" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="redirect">
    <FindOwn/>
  </cmd>
</iq>

Usage

You can call redirect.FindOwn at any time and it will be answered by a redirect.RedirectEntry packet.

Responses

redirect.RedirectEntry

Example

<iq id="bWjfy-18" to="tweber@mobydick/mdfxclient_tw-macbook.in.pascom.net" type="result">
  <cmd xmlns="http://www.pascom.net/mobydick" module="redirect">
    <RedirectEntry>
    <source>340</source>
    <target>333</target>
    <old>333</old>
   </RedirectEntry>
 </cmd>
</iq>

Events

journal.RedirectEntry

It’s also possible to subscribe to the RedirectEntry in order to be notified whenever the deflection state changes.

Module “xmppuser”

Abstract

Session Management, Customization.

Most likely you’ll need various data about the currently logged in Users to effectively integrate your application with pascom.

Our xmppserver expects to receive a xmppuser.ClientInfo Package directly after logging in your user. It will be answered by a xmppuser.UserInfo which contains a vast set of information.

Commands

xmppuser.ClientInfo

You can send various environment data within the ClientInfo. However, only the user element is currently used. It allows the facsimile subsystem to map between incoming print requests from a certain operating system specific username in combination with a machine name or ip to a established xmpp session in order to forward any facsimile requests. You can also send a list of subscription filters from within the ClientInfo if you want to receive events.

Example

<iq id="9WTfy-9" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="xmppuser">
      <ClientInfo>
        <os>Mac OS X 10.9</os>
        <osUser>tweber</osUser>
        <clientVersion/>
        <user/>
        <jid/>
        <clientIp/>
        <AddSubscription>
          <Subscription module="event" type="*" scope="user"/>
          <Subscription module="base" type="*" scope="user"/>
          <Subscription module="journal" type="*" scope="user"/>
        </AddSubscription>
      </ClientInfo>
  </cmd>
</iq>

xmppuser.FindCustomData

Sometimes customers ask us for very specific requirements and as a result a customization project is begun. In the majority of cases, we bundle some functionality for the web-UI, the phone system as well as the client into a so called “custom package” which is to be installed on a number of pascom appliances.

The commands to pass data between the various layers are standardized and therefore documented here.

FindCustomData is a empty Package which works as a trigger to ask the system for any project specific data. It will be answered by a xmppuser.CustomData response.

xmppuser.InvokeCustomAction

This is yet another generic command for client customizations. It’s purpose is to trigger remote actions within the custom package’s backend code.

Example

<iq id="9WTfy-9" type="get">
    <cmd xmlns="http://www.pascom.net/mobydick" module="xmppuser">
      <InvokeCustomAction action="project-specific-action-ids"/>
    </cmd>
</iq>

Responses

xmppuser.UserInfo

The _UserInfo_ contains the complete state of the authenticated xmpp user. Some of the data structures are dynamically created and you will need to subscribe to certain events in order to keep your client’s data model in sync with the server.

Some of the building blocks of the _UserInfo_ Package include:

  • Identity: a list of fields from the web-UIs “Configure User” section.
    • db_003use_name: contains the user’s pascom-Username. It can differ from the xmpp username because the xmpp protocol is not case sensitive!
    • db_003use_bez: The user’s full name.
    • db_009ext_extension: Internal phone number.
    • faxextension: It contains the user’s virtual facsimile number (if configured).
  • RoleList: the full set of roles including role types to check permissions, switch feature sets. Your client could enable more features if the user has the _xmpp.supervisor_ role type, for example.
  • LocationList: contains up to two device sets for statically and dynamically assigned devices
    • Location: name of the location. If _isstatic_ is _false:_ it tells you about the current roaming location.
    • DeviceEntry: current follow-me timings for a given device
      • Phonedevice: a configured hard- or softphone. The _capabilities_ set contains all the supported features for the given device.
  • Voicemailbox: current Voicemail box state including waiting messages counter.
  • RedirectEntry: current call deflection state. See Module “redirect”
  • QueueMemberStates: a complete set of the queue memberships and states for this user. You can find more information in the queue module section.
  • SubscriptionList: a list of subscription filters which are currently set for this user.

Example

    <iq id="9WTfy-9" to="tweber@mobydick/mdfxclient_tw-macbook.in.pascom.net" type="result">
      <cmd xmlns="http://www.pascom.net/mobydick" module="xmppuser">
      <UserInfo name="tweber">
        <Identity>
          <db_011acc_id>5</db_011acc_id>
          <db_009ext_id>9</db_009ext_id>
          <db_003use_id>6</db_003use_id>
          <faxextension/>
          <db_016voi_mailbox>340</db_016voi_mailbox>
          <db_003use_lastlogin/>
          <db_028pho_id/>
          <db_020fax_id/>
          <db_016voi_id>5</db_016voi_id>
          <db_003use_name>tweber</db_003use_name>
          <db_009ext_tmstmp>2013-12-03 14:58:29.705785</db_009ext_tmstmp>
          <db_011acc_tmstmp>2013-12-03 14:58:29.705785</db_011acc_tmstmp>
          <db_011acc_voiidwatch>5</db_011acc_voiidwatch>
          <db_003use_doc/>
          <db_003use_bez>Thomas Weber</db_003use_bez>
          <db_009ext_extension>340</db_009ext_extension>
          <db_003use_enabled>true</db_003use_enabled>
          <db_011acc_calleridnum/>
          <db_003use_tmstmp>2013-12-03 14:58:29.705785</db_003use_tmstmp>
        </Identity>
        <RoleList>
          <Role name="All Users">
            <RoletypeList>
              <Roletype name="xmpp.connect"/>
              <Roletype name="xmpp.group"/>
            </RoletypeList>
          </Role>
        </RoleList>
        <LocationList>
          <Location name="Thomas Weber" isstatic="true" username=""/>
          <Location name="Entwicklung2" isstatic="false" username="">
            <DeviceEntry delayinternal="0" timeoutinternal="20" delayexternal="0" timeoutexternal="20">
              <Phonedevice name="SIP xlite2 [Entwicklung2]" type="Generic SIP Phone">
                <capabilities>
                  <dial/>
                </capabilities>
              </Phonedevice>
            </DeviceEntry>
            <DeviceEntry delayinternal="0" timeoutinternal="20" delayexternal="0" timeoutexternal="20">
              <Phonedevice name="Snom 000413411c47 [Entwicklung2]" type="Snom Phone">
                <capabilities>
                  <conference/>
                  <dial/>
                  <factory_reset/>
                  <firmware_update/>
                  <hangup/>
                  <hold/>
                  <transfer/>
                  <offhook/>
                  <reboot/>
                </capabilities>
              </Phonedevice>
            </DeviceEntry>
          </Location>
        </LocationList>
        <Voicemailbox>
          <db_016voi_name>Thomas Weber</db_016voi_name>
          <inboxMessages>0</inboxMessages>
          <db_016voi_mailbox>340</db_016voi_mailbox>
          <db_016voi_tmstmp>2013-12-03 14:58:29.705785</db_016voi_tmstmp>
        </Voicemailbox>
        <RedirectEntry eventType="update" eventId="">
          <source>340</source>
          <target>333</target>
          <old>333</old>
        </RedirectEntry>
        <QueueMemberStates eventType="" eventId=""/>
        <SubscriptionList>
          <Subscription module="event" type="*" scope="user"/>
          <Subscription module="base" type="*" scope="user"/>
          <Subscription module="journal" type="*" scope="user"/>
        </SubscriptionList>
      </UserInfo>
    </cmd>
    </iq>

xmppuser.FindUserInfo

Requests the xmppuser.UserInfo Structure. A supervisor may use this command to load the details about other Users in the system. Non supervisor Users can only re-request their own data.

  • if jid is empty - sender full jid will be used
  • if jid contains only the username or a bare jid (without ressource string) - subscription will be omitted
  • if jid contains a full jid (including ressource string): includes subscriptions for this specific session

Example

<iq id="3dieE-3" type="get">
  <cmd xmlns="http://www.pascom.net/mobydick" module="xmppuser">
    <FindUserInfo jid="tweber"/>
  </cmd>
</iq>

xmppuser.CustomData

Contains arbitrary data for a specific customization project. We use it as a generic container for project specific client add-ons or payed 3rd party integrations.

Events

This Module does not send any events.