Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: update for expansion info

...

Code Block
xml
xml
borderStylesolid
titleBLF Item Example
<config>
    <smart_blf>
        <blf_items>
            <blf_item location="side" index="0" node="" paging="1" contact_id="101">
                <behaviors>
                    <behavior phone_state="idle" target_status="on_the_phone" press_action="call_vm" press_function="dial" />
                    <behavior phone_state="idle" target_status="idle" press_action="regular_dial" press_function="dial" />
                    <behavior phone_state="idle" target_status="idle" long_press_action="anintercom" long_press_function="dial" />
                </behaviors>
                <indicators>
                    <indicator target_status="idle" ring="0" ringtone_id="Digium" led_color="green" led_state="on" line_label_fgcolor="#BDBDBD" line_label_bgcolor="#212121" />
                    <indicator target_status="ringing" ring="1" ringtone_id="Techno" led_color="red" led_state="fast" line_label_fgcolor="#FFFFFF" line_label_bgcolor="#308030" />
                </indicators>
            </blf_item>
        </blf_items>
    </smart_blf>
</config>

...

Option

Values

Description

location

main, side, expansion

Defines the display panel for the BLF Item. D40, D45, D60, D62, D65, and D65 D80 phones display only on main. D50 and D70 phones can display on main or side. Accounts on the main screen take precedence over BLF item locations. D65 phones with an attached expansion module can display on the expansion location.

index

integer

Sets the position key for the BLF Item, top-down, beginning with 0. For D65 and D70 phones, assigning more than one BLF item to the same index number will cause subsequent assignments to appear on additional pages in the correct index slot. BLF items located on the main screen must begin in location 1 because the first slot, 0, is occupied by the phone's primary line.

nodeinteger, 0-5When laying out BLF Items onto a specific expansion module, the node parameter can be used to place an item onto a specific node, rather than following normal paging rules.

paging

Boolean, 0, 1

Defaults to 1. If disabled, the item will remain static across all pages. The paging element is not used for expansion modules.

contact_id

string

Maps this item to a Contact as derived from the "id" field of a contact from the loaded contacts XML file

app_idstringThe identifier should be either one of the phone's default applications (contacts, voicemail, parking, status, queues) or should be the identifier of a user-loaded custom application. Used instead of contact_id to dedicate this item to loading an application into the foreground.
blankBoolean, 0,1Defaults to 0. If present, blanks out the item so that an empty BLF is loaded into the slot. Note that blank type keys do not have any contact_id or additional attributes associated with them.

...

Option

Values

Description

target_status

unknown, idle, on_hold, ringing, on_the_phone

Defines the status of the watched device that must be matched for this indicator to be in effect. If undefined, all target_states will be matched.

ring

Boolean

If true, causes the local phone to ring when the behavior is met

ringtone_id

Alarm, Chimes, Digium, GuitarStrum, Jingle, Office2, Office, RotaryPhone, SteelDrum, Techno, Theme, Tweedle, Twinkle, Vibe, or one of ids from a custom-loaded ringtone

Specifies the ringtone to be played when the indicator is in effect. If unspecified, the phone's default ringtone will be used

led_color

amber, green, red

Specifies the color to be applied to the line key LED if the indicator is in effect.

led_state

off, on, slow, fast

Specifies the LED blink state of the line key LED if the indicator is in effect.

line_label_fgcolorHex color value, defaults to #BDBDBDSpecifies a hex color value for the color of the label text when this indicator is active. The default color value for text in rapid dial keys is #BDBDBD. Firmware 2.6.0 and greater, D6x phones only.
line_label_bgcolorHex color value, defaults to #212121Specifies a hex color value for the color of the label background when this indicator is active. The default color value for the label background is #212121. Firmware 2.6.0 and greater, D6x phones only.

Behavior Considerations

When creating behaviors, the following points should be taken into consideration.

...

To affect this, our Digium phone needs a contact that is configured with two actions: one, called called 103 to  to dial the contact normally, and another called pickup that  that dials using a prefix.  The contact configuration thus looks like:

...

Here, note that we've created the actions 103 and pickupcall.  For  For 103, only 103 is dialed.  For  For pickupcall, phone will dial the ** prefix first, and then 103.

...

Here, notice that we have defined two behaviors.  Because behaviors are processed top-down, we first define a behavior with press_action of of 103 and  and press_function of of dial.  This will cause the phone for all phone_states and all target_states (the implied behavior when not explicitly defining them) to call the the 103 action action.  

Next, we define a behavior where the target_status is ringing, we've set the press_action to pickupcall (which is the identifier of the pickup action that we created for the Contact), and the press_function is set to dial.  Because we defined a pickup_action within the contact itself, and because we have a ringing target_status behavior, this will cause the D80 model phone to display a pickup activity card in its activity stream, beginning with firmware 1.8.0.

Thus, when Mark Spencer's phone is ringing, based on a subscription NOTIFY from Asterisk, and someone presses this Rapid Dial key, the phone will dial dial **103 into  into Asterisk, which will in turn call the Pickup() application.  And, when Mark Spencer's phone isn't ringing, and someone presses this Rapid Dial key, the phone will dial 103 into  into Asterisk, which will call the Dial() application and ring the phone normally.

...

Here, we've defined an extern pattern match on 1XX - all 3-digit dialed patterns beginning with 1 followed by two more digits 0-9.  In the case that it's matched, Asterisk will first perform a GotoIf() depending on the presence of an X-Digium-Call-Feature matching matching feature_intercom.  Where feature_intercom is matched, the dialplan jumps to the the intercomcall label  label where a Dial is performed using a pre-dial handler to utilize the PJSIP_HEADER dislplan function that will add an Alert-Info header to the outgoing SIP INVITE before performing the Dial.  Otherwise, when feature_intercom is not matched, the dialplan jumps to the notintercomcall label  label and performs a regular Dial() without adding any special headers.

...

Thus, when Mark Spencer's phone is idle, based on a subscription NOTIFY from Asterisk, and someone performs a long press on this Rapid Dial key, the phone will dial 103 with a special X-Digium-Call-Feature header of of feature_intercom into  into Asterisk, which will get handled by the dialplan to prepend an Alert-Info to the outgoing INVITE to Mark's phone.  And, when Mark Spencer's phone isn't idle, and someone presses this Rapid Dial key, the phone will dial 103 into Asterisk, which will call the Dial() application and ring the phone normally.

...

Here, we've defined an extern pattern match on 1XX - all 3-digit dialed patterns beginning with 1 followed by two more digits 0-9.  In the case that it's matched, Asterisk will first perform a GotoIf() depending on the presence of an X-Digium-Call-Feature matching feature_intercom.  Where feature_intercom is matched, the dialplan jumps to the intercomcall label where a pre-dial handler calls the PJSIP_HEADER dial plan function to add an Alert-Info header to the outgoing SIP INVITE before performing the Dial.  Otherwise, when feature_intercom is not matched, the dialplan jumps to the notintercomcall label.  The notintercomcall label  label performs another GotoIf check.  If the feature_monitor header  header is present, then the dialplan jumps to to monitorcall to  to a ChanSpy() application to monitor the call.  If the feature_monitor header  header is not present, the dialplan jumps to donotmonitorcall to  to a normal Dial().

To affect this, our Digium phone needs a contact that is configured with three actions: one, called 103 to dial the contact normally, another called myintercom that dials with a special header, and a third called called mymonitor also  also with a special header.  The contact configuration thus looks like:

...

Here, note that we've created the actions 103 and myintercom and  and mymonitor.  For 103, only 103 is dialed.  For myintercom, phone will also dial 103, but a header will be appended to the outgoing INVITE from the phone to Asterisk.  An,d for mymonitor, the phone will also dial 103, but a different header will be appended to the outgoing INVITE.

...

Thus, when Mark Spencer's phone is idle, based on a subscription NOTIFY from Asterisk, and someone performs a long press on this Rapid Dial key, the phone will dial 103 with a special X-Digium-Call-Feature header of feature_intercom into Asterisk, which will get handled by the dialplan to prepend an Alert-Info to the outgoing INVITE to Mark's phone.  When Mark's on the phone, the header of of feature_monitor will  will be sent, and ChanSpy will be called to listen to Mark's conversation.  Otherwise, when someone presses this Rapid Dial key, the phone will dial 103 into Asterisk, which will call the Dial() application and ring the phone normally.

...

Here, we've setup the main parking extension as as 700, we've setup 20 lots, numbered numbered 701-720, and we've set the in-call feature sequence that parks calls as as #72.

Tip

Wondering why you can't re-park a previously parked call? Or, wondering why you can't do DTMF-based transfers of previously parked calls? Take a look at the parkedcalltransfers and parkedcallreparking (and other) options in features.conf. They're disabled by default, so, to enable that capability, they'll need to be enabled.

...

Next, we need to make sure our Dialplan is constructed to include the parkedcalls context  context like so:

Code Block
titleCall Parking Dialplan Example
collapsetrue
[testing]
include => parkedcalls
include => featuremap
 
exten => _1XX,1,NoOp()
same => n,Dial(PJSIP/${EXTEN},,kK)

Here, our sample context testing includes  includes the necessary components, automatically generated by features.conf.  And, our Dial() application includes the k and  and K flags, which lets the called and calling parties park the other caller by dialing the proper DTMF sequence.

...

Here, note that we've created the actions parkme and showparking.  For parkme, #72 is dialed.  For showparking, the phone will load the parking built built-in phone application.

Next, we need to configure the behavior of a Rapid Dial key to affect the actions.  Configuration for this resembles:

...

Here, notice that we have defined two behaviors.  First, we define a behavior that acts when our phone is in the the connected state state.  In that state, when the rapid dial key is pressed, the parkme action  action is called with the press_function of send_dtmf, which sends in-call DTMF back to Asterisk.

Next, we define a behavior that acts when our phone is in the idle state state.  In this state, when the rapid dial key is pressed, the showparking action  action is called, with the press_function show_app, which loads an application into the foreground.

...

Next, we define behaviors for the phone states where we want the blindxfer action  action to be called.  The states we've chosen are incoming (for when a call rings us), connected (for when we're on a call and not doing anything else), incoming/transfer (for when a call is ringing us and we've pressed the Transfer hard key), and hold/transfer (for when we're on a call and we've pressed the Transfer hard key, which puts the caller on hold).

...

Here, we've setup DTMF sequence to invoke blind transfer as as #1.

Next, we need to make sure our Dialplan is constructed to include the feature map context like so:

...

In this example, in light of the previous example, we'll only configure one action, called called blindfeaturetransfer to  to perform the parking of the caller.  In this case, we'll use the #1 feature  feature code as the dialing prefix and the target extension as the dialed number.  The contact configuration thus looks like:

...

Here, note that we've created the action action blindfeaturetransfer.  When the action is called, the phone will dial dial #1 followed by  followed by 103.

Next, we need to configure the behavior of a Rapid Dial key to affect the actions.  Configuration for this resembles:

...

Here, we define a behavior that acts when our phone is in any state.  It is probably prudent to narrow this down though to a more limited set of states.  Nevertheless, for this example, when the rapid dial key is pressed, the blindfeaturetransfer action  action is called with the press_function of of send_dtmf, which sends in-call DTMF back to Asterisk.

...

Here, note that we've created the actions 103 and personisbusy.  For the first, 103 is  is dialed.  For the second, an application called personbusyapp is  is referenced.

Next, we need to configure the behavior of a Rapid Dial key to affect the actions.  Configuration for this resembles:

...

Thus, whenever we press the key and the target isn't on the phone, we will dial 103.  And, whenever the target is on the telephone, we will load the application personbusyapp into  into the foreground.

Tip
titleLoad an App without defining a Contact

If, instead of creating a contact that loads an application as part of action-defined behavior, you just want to dedicate a key to loading an application, a BLF Item can be constructed like:

Code Block
titleLoad an app with not contact reference
languagehtml/xml
<config>
<smart_blf>
        <blf_items>
            <blf_item location="side" index="1" paging="1" app_id="parking"/>
        </blf_items>
    </smart_blf>
</config>

Note the use of the app_id parameter instead o the contact_id parameter. For this type of key, no presence subscription is made, nor are other actions possible. Rather, it's a quick way to drop an application onto a Rapid Dial key.

...

By default, Digium phones, for an active subscription, blink fast green when a party is ringing, slow red when a party is on hold, and show solid green when a party is on a call.  Smart BLF provides customization of the LED states based upon the device state of the subscribed party.  You can configure red instead of green, amber instead of red, off instead of amber, etc., and you can manipulate the blinking rate.  Control over the LED state is managed by indicators that  that can be configured along with the configuration of each blf_item.  Let's look at a small example:

...

For this example, notice the indicator element element.  It defines a target_status, an led_color and an led_state.  The target_status is set to ringing, the led_color is set to amber and  and the led_state is set to fast.      Thus, when the target of this blf_item, that's contact_id 103, is in the ringing status status, the LED indicator for this rapid dial key will fast-blink amber.  Normally, without this definition, as noted above, the default behavior when a target is ringing is to blink fast green.

...

For this example, we've built slightly upon the first.  Now, we define ring="1" and  and we set ringtone_id to Digium.  Thus  Thus, when the watched party is ringing, our phone will playback the Digium ringtone.  ringtone_id is derived from the ids of the various ringtones loaded onto the phone - factory defaults or custom-added.

...

Here, we've defined an extern pattern match on 1XX - all 3-digit dialed patterns beginning with 1 followed by two more digits 0-9.  In the case that it's matched, Asterisk will first perform a GotoIf() depending on the presence of an X-Digium-Call-Feature matching feature_send_to_vm or  or of a Diversion header with a redirection reason of of send_to_vm.  Where the voicemail checks are matched, the dialplan jumps to the vm label where the Voicemail() application is called.  Otherwise, when the voicemail checks are not not matched, the dialplan jumps to the notvm label and performs a regular Dial().

...

Next, we define a behavior where the target_status is on_the_phone, we've set the press_action to to sendtovm (which is the identifier of the voicemail action that we created for the contact), the press_function to to dial, the long_press_action also to sendtovm, and the long_press_function to transfer.

...

For firmwares prior to 1.4, contacts were populated onto BLF keys as ordered top-down from a group_name as  as specified by the the blf_contact_group configuration  configuration parameter.  This meant that explicit positioning of contacts onto a key or multiple keys on multiple pages wasn't possible.  Now, with Smart BLF, contacts may be mapped to an exact key on an exact page.  Mapping is accomplished using the locationindex, and paging blf blf_item parameters.  Take the following example:

...

For this example, the contact will be located on the side panel panel.  This means it's compatible with D50 and D70 phones, but not the D40, as the D40 only has a main location location.  Now, on the side panel, the contact is located at index slot 1.  The index begins at 0, so this item, because its index is is 1 will appear on the second rapid dial key from the top.  Further, paging is enabled.  When paging is enabled, a contact is mapped to a particular page.  Pages are only relevant to the D70 phone, which supports up to 10 pages.  Since this contact is mapped to a particular page, and because it is the first item on index 1, it will appear only on the first page of contacts.

...

  • The first item is mapped to the main screen  main screen on index 3, so it will appear on the 4th line key on D50 and D70 phones (but wouldn'tappear on a D40 phone which only has a single index slot available to it).  
  • The second item is mapped to the the side screen  screen on index index 0 and paging is disabled.  So, it will appear on the first page screen in the first rapid dial key. 
  • The third item is mapped to the side screen screen, also on index 0 and  and paging is disabled.  Because it is the second item to be mapped to index 0, and because blf items are processed top-down, this item will appear on the second page screen only, but not on the first.
  • The fourth item is mapped to the side screen  screen on index 9 and paging is disabled.  So, it will appear on both the first and second pages on the 10th rapid dial key.