Polycom EFK (Enhanced Feature Keys) Basics

by ScanSource Communications Tech Support on February 1, 2012 · 1 comment

in ScanSource Communications,Total Coverage Tech Connect

Note:  Polycom provides EFK as an as-is feature and therefore does not support it.  It is the position of ScanSource Communications to provide best-effort support for EFK. However, we cannot guarantee resolution for any issue regarding EFK.

Note: This document covers basic EFK configuration techniques only.

Note:  Detailed information regarding the tags and their attributes used in this document may be found in the UCS admin guide for your respective version of firmware, which is located on the Polycom Support site.

What is EFK?

Enhanced Feature Keys, or EFK, use macros within an XML configuration file to change or modify the softkeys on Polycom VOIP phones. Please note that these keys do not include line keys, as these are reserved for line registrations, speed dials, and Busy Lamp Field (BLF).

Configuration Files

At this time, EFK can only be configured in a configuration file. Because the use of EFK may be specific to the phone or user, we typically recommend that it be used in a per-phone configuration file like <phone’s MAC address>-reg.cfg.

However, it is possible for a group of phones to require the same EFK configurations. If this is the case, it may be useful to create a separate configuration file and configure each phone in the group to download this file using the <phone’s MAC address>.cfg file. This prevents one from having to enter the same configuration in multiple files, thus making it easier to implement changes to the EFK for the group in the future.

Enabling EFK

In order to use EFK, it must first be enabled. This is accomplished with the use of the <feature.enhancedFeatureKeys /> tag.

Example Code:

<feature>

<feature.enhancedFeatureKeys feature.enhancedFeatureKeys.enabled="1"></feature.enhancedFeatureKeys>

</feature>

Adding/Modifying Softkeys

In order to use EFK, softkeys will need to be added, removed, and/or modified. This is done through the use of the <softkey /> tag.

Adding softkeys

Softkeys are added and configured as attributes within the <softkey /> tag. Each softkey attribute will have an index number to distinguish it from other attributes, which are associated with other softkeys. The index number is highlighted in the example below.
softkey.1.label="example"
The most basic softkey configuration consists of the following attributes:

  • Label – This is the text that appears on the actual softkey on the phone.
    softkey.1.label="example"
  • Action – This is used to call on a macro defined within the <efklist /> tag. The macro name invoked must be preceded with an “!”
    softkey.1.action="!example"
  • Insert – This is used to set the position of the softkey on the phone.  By default, each softkey is positioned to the right of previous softkey(s). The “insert” attribute would overwrite this behavior.  In the example below, softkey index 1 is being placed in the third position, from the left, on the phone.
    softkey.1.insert="3"
  • Use – This attribute(s) is used to define in what state a softkey is made available to the user.  This state could be idle, active call, or a number of other different states. The following example makes the softkey available on the idle, or home, screen of the phone.
    softkey.1.use.idle="1"
  • Enable – This attribute actually makes the softkey available for use. Important: If this is not set, the softkey will not be displayed on the phone.\
    softkey.1.enable="1"

Softkey attributes:

Attribute

Description Permitted Values Default Value

softkey.x.action

The action or function for
custom soft key x. This value uses the same macro action string syntax as an
Enhanced Feature Key.

macro action
string, 256 characters
Null

softkey.x.enable

If 0, the soft key x is
disabled. If 1, the soft key is enabled.

0 or 1

0

softkey.x.insert

The position on the phone
screen for soft key x.

Note: If softkey.x.precedeis configured, this value is ignored. If the insert
location is greater than the number of soft keys, the key will be positioned
last, after the other soft keys.

0 to 10 0

softkey.x.label

The text displayed on the
soft key label. If Null, the label is determined as follows:

• If the soft key performs an
Enhanced Feature Key macro action, the label of the macro will be used.

• If the soft key calls a
speed dial, the label of the speed dial contact will be used.

• If the soft key performs
chained actions, the label of the first action is
used.

• If the soft key label is
Null and none of the preceding criteria are matched, the label will be blank.

String Null

softkey.x.precede

If 0, soft key x is
positioned in the first empty space from the left. If 1, the soft key is
displayed before (to the left of) the first default soft key.

0 or 1 0

softkey.x.use.active

Display in the active call
state

0 or 1 0

softkey.x.use.alerting

Display in the alerting state

0 or 1 0

softkey.x.use.dialtone

Display in the dial tone
state

0 or 1 0

softkey.x.use.hold

Display in the hold state

0 or 1 0

softkey.x.use.idle

Display in the idle state

0 or 1 0

softkey.x.use.proceeding

Display in the proceeding
state

0 or 1 0

softkey.x.use.setup

Display in the proceeding
state

0 or 1 0

Example Code:

<softkey
softkey.1.label="example1" softkey.1.action="!example1" softkey.1.insert="3" softkey.1.use.idle="1" softkey.1.enable="1"
softkey.2.label="example2" softkey.2.action="!example2" softkey.2.insert="4" softkey.2.use.idle="1" softkey.2.enable="1"
softkey.3.label="example3" softkey.3.action="!example3" softkey.3.insert="5" softkey.3.use.active="1" softkey.3.enable="1" />

Removing Softkeys

It may become necessary to remove factory softkeys in order to make room for custom ones. The softkey.feature.x attribute may be used within the <softkey /> tag to remove factory softkeys. In the example, this attribute is used to remove the “Forward” softkey.

softkey.feature.forward=”0”

Other softkey.feature attributes:

Attribute

Description Permitted Values Default Value

softkey.feature.basicCallManagement.redundant

Control the display of the Hold, Transfer, and Conference soft keys. If set to 0 and the phone
has hard keys mapped for Hold, Transfer, and Conference functions
(all must be mapped), none of the soft keys are displayed. If set to 1, all
of these soft keys are displayed.

0 or 1 1

softkey.feature.buddies

If 0, the Buddies soft
key is not displayed.

0 or 1 1

softkey.feature.callers

If 0, the Callers soft
key is only displayed on the SoundPoint IP
321/331/335 phones. If 1, the soft key is displayed on all phones. Note: Model-specific
parameters are defined for the SoundPoint IP
321/331/335 phones, with default value 1.

0 or 1 0

softkey.feature.directories

If 0, the Dir soft key is only displayed on the SoundPoint IP
321/331/335 phones. If 1, the soft key is displayed on all phones. Note: Model-specific
parameters are defined for the SoundPoint IP
321/331/335 phones with the default value 1.

0 or 1 0

softkey.feature.endcall

If 0, the End Call soft
key is not displayed. If 1, the soft key is displayed.

0 or 1 1

softkey.feature.forward

If 0, the Forward soft
key is not displayed. If 1, the soft key is displayed. Note: For the SoundPoint IP 321/331/335 phones, you must create the
soft key using the Enhanced Feature Key feature to display it.

0 or 1 1

softkey.feature.join

Join two individual calls to
form a conference. If 0, the Join soft key is not displayed. If 1, the
soft key is displayed.

0 or 1 1

softkey.feature.mystatus

If 0, the MyStatus soft key is not displayed.

0 or 1 1

softkey.feature.newcall

If 0, the New Call soft
key is not displayed when there is an alternative way to place a call. If 1,
the New Call soft key is displayed.

0 or 1 1

softkey.feature.split

Split up a conference into
individual calls. If 0, the Split soft key is not displayed. If 1, the
soft key is displayed.

0 or 1 1

Defining EFK Macros

EFK macros are what tell the phone what action to perform when a softkey is pressed.  These macros can be written within the efklist attribute of the <efk /> tag. Each efklist attribute will have its own index number to distinguish itself from other efklist attributes in the configuration.

The macro will need to be given a name so that it can be referenced in the softkey.x.action attribute.  This is accomplished using the efk.efklist.x.mname attribute. In the example below, the name of “example” is given to a macro with an index number of “1.”

efk.efklist.1.mname="example"

In order for softkeys to be able to invoke a macro, that macro must be enabled. This is accomplished using the efk.efklist.1.status attribute. In the example below, the macro with an index number of “1” is enabled.

efk.efklist.1.status=”1”

Writing an EFK Macro String

The macro string itself is the value of the efk.efklist.x.string attribute.  A macro consists of one or more action keywords with a “$” on either side

Macro Actions:

Action

Description

$L<label>$

This is the label for the
entire operation. The value can be any string including the null string (in
this case, no label displays). This label will be used if no other operation
label collection method worked (up to the point where this field is introduced).
Make this the first entry in the action string to be sure this label is used;
otherwise another label may be used and this one ignored.

$C<command>$

This is the command. It can
appear anywhere in the action string. Supported commands (or shortcuts)
include:

hangup (hu)

hold (h)

waitconnect (wc)

pause <number of seconds> (p <num sec>) where
the maximum value is 10

$T<type>$

The embedded action type.
Multiple actions can be defined. Supported action types include:

invite

dtmf

refer

Note: Polycom recommends that you always define this field. If it is not defined, the
supplied digits will be dialed using INVITE (if no active call) or DTMF (if
an active call). The use of refer method is call server dependent and may
require the addition of star codes.

$M<macro>$

The embedded macro. The
<macro> string must begin with a letter. If the macro name is not
defined, the execution of the action string fails.

$P<prompt num>N<num digits>$

The user input prompt string.

$S<speed dial
index>$

The speed dial index. Only
digits are valid. The action is found in the
contact field
of the local directory entry pointed to by the index.

$F<internal
function>$

An internal function.

The $C<command>$ and $T<type>$ are the most commonly used actions.  The $T<type>$ requires input in order to be executed correctly. It is important to remember that the action string is executed in the order that it is written and input is collected before any action is taken. For example, in order to send a call to a number/extension using the $Tinvite$ action, the number/extension itself must be input before the action. In the example below, a SIP INVITE will be sent to 800-555-1212, the phone will pause for two seconds, and then send “1111” as DTMF tones.

Interactive Macros

In some cases, input from the user is required for a macro to work properly. In order to pause the macro and prompt the user for input, the “efkprompt” attribute will have to be defined. There are four efkprompt attributes that need to be defined.

Attribute Description Default Value
efk.efkprompt.x.label The prompt
text that is presented to the user on the user prompt screen. If Null, no prompt
displays. Note: If the label does not fit on the screen, the label will be
shortened and ‘…’ will be appended.
Null
efk.efkprompt.x.status If 0, key x
is disabled. If 1, the key is enabled. This parameter must
have a value
, it cannot be Null. Note: If a
macro attempts to use a prompt that is disabled or invalid, the macro
execution will fail.
0
efk.efkprompt.x.type The type of
characters entered by the user. If set to numeric, the characters are
interpreted as numbers. If set to text, the characters are interpreted as
letters. If Null, numeric is used. If this parameter has an invalid value,
this prompt, and all parameters depending on this prompt, are invalid. Note:
A mix of numeric and text is not supported.
text
efk.efkprompt.x.userfeedback The user
input feedback method. If set to visible, the text
is visible. If set to masked, the text displays as asterisk characters (*),
this can be used to mask password fields. If Null, visible is used. If this
parameter has an invalid value, this prompt, and all parameters depending on
this prompt, are invalid.
visible

For our example, we want a macro that will transfer an active call directly to the voicemail box of a specific extension.  Most commonly this is accomplished by appending an extra digit to the front of the extension that would signal the PBX to send the call to voicemail instead of ringing the phone. In this example, we assume the PBX requires a “*” to be dialed before the extension number in order to transfer the call directly to the voicemail box.

First we need an EFK prompt defined for us to use in this Macro.

Example Code:

Once we have our EFK prompt defined, we can call on it in a macro using the prompt function.

<softkey softkey.feature.forward="0" softkey.1.label="Confbdg" softkey.1.action="!Confbdg" softkey.1.insert="3" softkey.1.use.idle="1" softkey.1.enable="1" softkey.2.label="Xfer2VM" softkey.2.action="!Xfer2VM" softkey.2.insert="4" softkey.2.use.active="1" softkey.2.enable="1" />
<efk efk.efklist.1.mname="Confbdg" efk.efklist.1.status="1" efk.efklist.1.label="Confbdg" efk.efklist.1.action.string="8005551212$Tinvite$$Cpause2$1111$Tdtmf$" efk.efklist.2.mname="Xfer2VM" efk.efklist.2.status="1" efk.efklist.2.label="Xfer2VM" efk.efklist.2.action.string="*$P1N5$$Trefer$" efk.efkprompt.1.status="1" efk.efkprompt.1.label="Extension" efk.efkprompt.1.type="numeric" />

This post was written by

You want to give your customers the best in voice and video conferencing equipment, and with ScanSource Communications, you’ll get it. With over 50 years of combined industry expertise, our Total Coverage offerings and knowledgebase can help you solve almost any communications question you can imagine. Plus, you will find articles from our savvy technical services team about key industry topics along with product support tips and tricks. You'll get it, because we get it. Contact Info: techsupport@scansourcecommunications.com 877-847-7000 x4095

Learn more about this topic at scansourcecommunications.com >

{ 1 comment… read it below or add one }

Leave a Comment

Previous post:

Next post: