HowTo - Extension Monitoring - Asterisk Presence

Asterisk offers a basic presence feature called device state, thanks to the XmlSubTags feature snom phones can take advantage of this feature.

Index:

A snom phone can subscribe to an extention and then parse the NOTIFY sent by Asterisk, this is pretty the same mechanism used in BLF & Pick-Up feature. A phone can receive presence-related NOTIFY subscribing to the PBX against an extension for the presence Event.

Applying some parsing rules to the received NOTIFY a snom phone can associate these states to a monitored extension:

• Offline (monitored extension is unregistered)
• Away (monitored extension is registered and inactive)
• Busy (monitored extension is on the phone)
• Ringing (monitored extension is ringing)
• Holding (monitored extension is holding a call)
• Registered (monitored extension is registered and active)

Unlike the BLF feature using the presence Asterisk doesn't includes caller and callee information in NOTIFY message for Ringing and Busy states.

Example

In this example we describe how to configure a function key monitoring another extension following these requirements:

• when monitored extension is Offline the led must be solid orange
• when monitored extension is Away the led must be off
• when monitored extension is Busy the led must be solid red
• when monitored extension is Ringing the led must be blinking red
• when monitored extension is Holding the led must be blinking orange
• when monitored extension is Registered the led must be solid green

• when the key is pressed during the Ringing state the phone must dial out the extension preceeded by the pickup code (*8)
• when the key is pressed during the Registered state the phone must dial out the extension number

Configure Asterisk

You need to enable the allowsubscribe in your sip.conf and to setup hints for monitored extension in your extensions.conf, take a look on folllowing dialplan that add hints for all 15X extensions:

; route internal calls
exten => _15[0-9],1,Dial(SIP/${EXTEN},30)
; internal hints for all 15X Extensions
exten => _15[0-9],hint,SIP/${EXTEN}

Configuring LED behavior

First of all we need to configure the phone LEDs behavior associating the LED colors.

According with the previous defined rules we need to modify led_on and led_blink_fast settings adding our previously defined states:

led_on=ON BUSY IN_A_CALL CALLING IN_A_MEETING URGENT_INTERRUPTIONS_ONLY DND UNAVAILABLE ACTIVE INACTIVE BE_RIGHT_BACK AWAY SEIZED CONNECTED ON_HOLD OFFHOOK RINGBACK I-Am-Ready AVAILABLE I-Am-Busy PhoneHasCall PhoneHasMissedCalls CurrentIdentityHasVoiceMessages PhoneHasVoiceMessages Away Offline Busy Registered
led_blink_fast=RINGING PICKUP PhoneHasCallInStateRinging Ringing Holding 

Now we can configure the LED colors:

led_red=BUSY IN_A_CALL CALLING IN_A_MEETING URGENT_INTERRUPTIONS_ONLY HOLDING DND I-Am-Busy Busy Ringing
led_green=AVAILABLE  I-Am-Ready I-Am-Almost-Ready Registered
led_orange=Offline Holding

Apply the XML definition

Configure a function key as an Xml Definition applying the well modified XML Definition in the Number field. Be careful to modify the valiables defined in <initialization> tag (subscr_ext, subscr_proxy, pickup_code.

The XML definition

<general type="AsteriskPresenceField"/>
<!--
 Initialization:
 Here we define some variables used in the XML
 subscr_ext: this the extension of the SUBSCRIBE target
 subscr_proxy: this is the domain part of the SIP uri to SUBSCRIBE
 pickup_code: the pickup code to add in front of the extension in order to pickup the call
 subscr_uri: will be created sip:$(subscr_ext)@$(subscr_proxy) this is the SUBSCRIBE URI
-->
<initialization>
  <state value="initial"/>
  <!-- PLEASE EDIT THE "value" ATTRIBUTE WITH THE RIGHT EXTENSION -->
  <variable name="subscr_ext" value="153"/>

  <!-- PLEASE EDIT THE "value" ATTRIBUTE WITH THE RIGHT PROXY IP ADDR -->
  <variable name="subscr_proxy" value="172.16.18.40"/>

  <!-- PLEASE EDIT THE "value" ATTRIBUTE WITH THE RIGHT PICKU CODE -->
  <variable name="pickup_code" value="*8"/>

  <!-- DO NOT EDIT -->
  <variable name="subscr_uri" value="sip:$(subscr_ext)@$(subscr_proxy)"/>
</initialization>

<!-- Define the kind of SUBSCRIBE -->
<subscription type="presence" to="<$(subscr_uri)>" for="$(subscr_uri)"/>

<!-- Verify the validity of the NOTIFY -->
<NotifyParsingRules type="applies">
  <level1 translates_to='OK'>/presence/tuple/contact[.="$(subscr_uri)"]</level1>
</NotifyParsingRules>

<!-- set the monitored extension state -->
<NotifyParsingRules type="state">
  <!-- if <ep:away/> tag is present se the status to "Away" -->
  <level1 translates_to="Away">/presence/pp:person/status/ep:activities/ep:away</level1>
  <!-- when the status is closed set it "Offline" -->
  <level1-1 translates_to="Offline">/presence/tuple/status/basic[.="closed"]</level1-1>
  <!-- if <ep:busy/> tag is present se the status to "Busy" -->
  <level2 translates_to="Busy">/presence/pp:person/status/ep:activities/ep:busy</level2>
  <!-- if <note> content is "Ringing" set the status to "Ringing" -->
  <level2-1 translates_to="Ringing">/presence/note[.="Ringing"]</level2-1>
  <!-- if <note> content is "On Hold" set the status to "Holding" (the phone is holding another call) -->
  <level2-2 translates_to="Holding">/presence/note[.="On hold"]</level2-2>
  <!-- if status is open set it as "Registered" -->
  <level3 translates_to="Registered">/presence/tuple/status/basic[.="open"]</level3>
</NotifyParsingRules>

<action>
  <!-- Dial the pickup code only in Ringing (dial is for backward compatibility) -->
  <dial target="$(pickup_code)$(subscr_ext)" when="on press" states="Ringing"/>
  <invite target="$(pickup_code)$(subscr_ext)" when="on press" states="Ringing"/>
  <!-- Dial the extension when Registered -->
  <dial target="$(subscr_ext)" when="on press" states="Registered"/>
  <invite target="$(subscr_ext)" when="on press" states="Registered"/>
  <!-- Nothing in all others status -->
</action>

Troubleshooting

• Verify the subscriptions: After the function key is applied the phone must sends out a SIP SUBSCRIBE with an Event: presence header, when the SUBSCRIBE is accepted must be listed in the Subscriptions/Outgoing Subscriptions phone WUI page.
• Verify the NOTIFY: when the monitored extension change status your phone must receive a SIP NOTIFY containing an Event: presence, an Content-Type: application/pidf+xml and an XML body
• Verify the XML parsing: configuring a phone log_level>=8 when the phone receive a NOTIFY you must see some log messages like "NotifyParsingRule returns match-translation which is 'OK'"

Further reading

• XML Definitions

• Page:
  Asterisk How-to
• Page:
  Basic Information - Asterisk PBX
• Page:
  How to configure Asterisk to trigger intercom at call receiving side
• Page:
  HowTo - Extension Monitoring - Asterisk Presence