Plantronics + Polycom. Now together as Poly Logo

Server-based DND using FAC/NOTIFY?

SOLVED
Advisor

Server-based DND using FAC/NOTIFY?

I noticed in the UCS 3.3.1 release notes that there are some new configuration parameters for controlling server-based DND and call forwarding using feature codes.  I'm running an Asterisk/FreePBX system in which I'm using a somewhat goofy macro that dials *76 to trigger the server DND, plus the local DND function for the phone, and this workflow can cause the two to get out of sync sometimes.

 

There seems to be a lack of documentation on the new configuration parameters (such as "reg.x.serverFeatureControl.activateCodeSequence.dnd") and how they can be used to do server-based DND.  Can these config parameters be used with something like an Asterisk/FreePBX system, and if so, how?

Message 1 of 30
1 ACCEPTED SOLUTION

Accepted Solutions
Advisor

Re: Server-based DND using FAC/NOTIFY?

After much time with this and working with some people at Polycom who were helpful enough to get me the information necessary to complete this puzzle, here is the WORKING solution for getting Server-side DND working with Asterisk and FreePBX. You need to jump through a few hoops, but otherwise this has been a solid setup with our phone system.

 

First off, the requirements, which are kinda specific:

1. Polycom UCS release 3.3.1revF or 3.3.2*

2. Ability to edit chan_sip.c and sip.h in the Asterisk source, and recompile (re-running 'make') it to get a new chan_sip.so. If you have installed your Asterisk server by building it from the source, this is actually not as daunting as it may sound, especially if you can muddle around existing code. Note that I don't really know C, and I did this just fine.

 

* Note about the Polycom UCS version:  This is known to work in 3.3.1revF and 3.3.2.  I do not know about 3.3.3, but you can try it, let me know, and I can update this accordingly. This will NOT WORK with UCS 4.0.0 and UCS 4.0.1!!!  The SIP messages it sends to Asterisk on the new version are incomplete and do not work.  Additionally, some of the configuration parameters for this have conspicuously disappeared from the administration guide in the new version of the software, and the current word is that this feature was never intended to be published in the manual. This is possibly due to the original stink I made about this issue, here. As I know there are many of us interested in this feature, I encourage you to lobby a complaint with Polycom here or as a feature request to encourage them to reinstate this as a documented and supported feature. Strength in numbers, people. Your participation would be appreciated.

 

OK, onto the setup....

 

1) Asterisk dialplan configuration

The assumption is that you already have a dialplan configured to have feature codes that enable and disable DND on the server. The stock dialplan configuration with FreePBX will suffice, though you can edit it to be quicker if you'd like by removing the part where Asterisk waits and speaks back to you.  On my system, these feature codes to turn on and off DND are *78 and *79, respectively. These are the defaults for FreePBX.

 

2) Polycom phone configuration

There are a few parameters that you will need to add to each line registration for which you wish to have server-side DND features on. As I run a home office, I have two line reigstrations on my phone.  So the configuration I have below is set up separately on each line registration/extension:

 

reg.x.serverFeatureControl.signalingMethod="inviteFACSubscribePresence"
reg.x.serverFeatureControl.activateCodeSequence.dnd="*78"
reg.x.serverFeatureControl.deActivateCodeSequence.dnd="*79"
reg.x.serverFeatureControl.dnd="1"
reg.x.serverFeatureControl.subscribeToUri="sip:[EXT]@your.sipserver.addr"

 

... where "x" is the line registration (1, 2, 3, etc), "*78" and "*79" are the feature codes that the phone needs to dial, "[EXT]" is the extension number for your line, and "your.sipserver.addr" is the address of your Asterisk server that the phone registers on.  Example:  reg.1.serverFeatureControl.subscribeToUri="sip:101@my.sipserver.com"

 

Note that these all-important parameters for FAC/NOTIFY are no longer documented!  It is a travesty.  Word is that this was implemented for one large customer of theirs. I am hoping that one day Polycom realizes that the Asterisk community is another large customer of theirs. :-)

 

Lastly, ensure that your phone configuration executes the default behavior on the DND button.  If you have it hardcoded to run a softkey/macro/feature code, remove those settings.

 

3) Editing the Asterisk source

The final piece is editing Asterisk to send the right XML syntax back to the Polycom so that it knows to toggle its DND status. Admittedly, this is the trickiest part, and unfortunately while I can muddle around in code, as a web developer I'm not personally savvy enough to produce you official "patch" files that you run against your source. What I can tell you, however, is what I've changed.  I was making these edits using Asterisk 1.8.2.1.  This will probably work similarly with other Asterisk versions, though these may be small changes in what/where you need to edit things.  To the best of your ability, carry on with the following edits, and please, create backup copies of the two files you will edit, just in case you make a mistake.

 

3a) First file to edit, channels/sip/includes/sip.h:

 

Find the line that begins "enum subscriptiontype {" and add "POLYCOM_FAC" as one of its values.  The entire block should appear as follows:

 

enum subscriptiontype {
	NONE = 0,
	XPIDF_XML,
	DIALOG_INFO_XML,
	CPIM_PIDF_XML,
	PIDF_XML,
	POLYCOM_FAC,
	MWI_NOTIFICATION,
	CALL_COMPLETION,
};

 

3b) Final file to edit, channels/chan_sip.c

 

First, find the line that begins "static const struct cfsubscription_types {".  We will be adding a definition for POLYCOM_FAC to this block.  The entire block should result in the following:

 

static const struct cfsubscription_types {
	enum subscriptiontype type;
	const char * const event;
	const char * const mediatype;
	const char * const text;
} subscription_types[] = {
	{ NONE,		   "-",        "unknown",	             "unknown" },
	/* RFC 4235: SIP Dialog event package */
	{ DIALOG_INFO_XML, "dialog",   "application/dialog-info+xml", "dialog-info+xml" },
	{ CPIM_PIDF_XML,   "presence", "application/cpim-pidf+xml",   "cpim-pidf+xml" },  /* RFC 3863 */
	{ PIDF_XML,        "presence", "application/pidf+xml",        "pidf+xml" },       /* RFC 3863 */
	{ XPIDF_XML,       "presence", "application/xpidf+xml",       "xpidf+xml" },       /* Pre-RFC 3863 with MS additions */
	{ POLYCOM_FAC,       "as-feature-event", "application/x-as-feature-event+xml",       "x-as-feature-event+xml" },       /* Proprietary Polycom feature-key synchronization */
	{ MWI_NOTIFICATION,	"message-summary", "application/simple-message-summary", "mwi" } /* RFC 3842: Mailbox notification */
};

 

Second, and this is the biggest part, find the static method "static void state_notify_build_xml" in the file.  Scroll down to the case statements where it is building the XML for presence, and we will be inserting a case POLYCOM_FAC: to this area. Note: I added this as a new case before "case PIDF_XML", but it doesn't matter exactly where, just so long as you get the syntax right.

 

case POLYCOM_FAC:
	ast_str_append(tmp, 0,
		"<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?>\n"
		"<DoNotDisturbEvent xmlns=\"http://www.ecma-international.org/standards/ecma-323/csta/ed3\">\n");
	ast_str_append(tmp, 0, "<device>%s</device>\n", exten);
	ast_str_append(tmp, 0, "<doNotDisturbOn>%s</doNotDisturbOn>", (local_state ==  NOTIFY_OPEN) ? "false" : (local_state == NOTIFY_INUSE) ? "false" : "true");
	ast_str_append(tmp, 0, "</DoNotDisturbEvent>\n");
	break;

 

Third, go further down in the file and find the static method "static int transmit_state_notify", go to its case statement, and add a new case for POLYCOM_FAC.  Note: this essentially is the same as what the other cases do, so I suppose you could just as easily add a "case POLYCOM_FAC" to one of the other cases like XPIDF_XML and it would work just as well. In any case, here's the full case statement for POLYCOM_FAC:

 

case POLYCOM_FAC: /* Polycom Feature Key Synchonization */
	add_header(&req, "Event", subscriptiontype->event);
	state_notify_build_xml(state, full, p->exten, p->context, &tmp, p, p->subscribed, mfrom, mto);
	add_header(&req, "Content-Type", subscriptiontype->mediatype);
	p->dialogver++;
	break;

 

Last, but certainly not least, we are changing one important line in the Asterisk source that hardcodes all presence requests received by a Polycom.

 

Find this code:

 

/* Older versions of Polycom firmware will claim pidf+xml, but really
* they only support xpidf+xml. */
if (pidf_xml && strstr(p->useragent, "Polycom")) {
	subscribed = XPIDF_XML;

 

... and change it to ...

 

/* Older versions of Polycom firmware will claim pidf+xml, but really
* they only support xpidf+xml. */
if (pidf_xml && strstr(p->useragent, "Polycom")) {
	subscribed = POLYCOM_FAC;

 

(we are swapping out "XPIDF_XML" for "POLYCOM_FAC")

 

4) Finishing up

Once you are done with the edits, go to the main directory for your Asterisk source and re-run "make".  If you previously compiled Asterisk from its source, it should be smart and only need to build the changed files based on what you edited.  The new compiled file that you will be concerned with is "chan_sip.so".  Once compliation is done, backup/replace the existing shared object in the "modules" directory with this new one (mine is located in /usr/lib/asterisk/modules/).

 

Afterwards, bounce your Asterisk server, reboot your phones, and try this out.  If you have multiple line registrations, hitting "Do Not Disturb" on your phones will bring up a menu to choose which line you wish to DND, with "Set All" and "Clear All" being options.  For each line listed in the menu "Disabled" means that DND is off, and "Enabled" means that DND is on.  For myself, I tend to use "Set All" and "Clear All" to toggle my DND status.  If you have a single line registration, I imagine there would be no menu that appears, and pressing the button will simply toggle the status.  By the way, even though this is dialing a feature code, it'll do this separately from any call that you might currently be in, so this feature will work even if you are currently in a call!

 

5) How you know it's working

Before I got the proper XML schema from Polycom, one thing I noticed when trying to set this up is that I could press the button to enable DND and the phone would dial the feature codes for each line and set the DND, and the main display of the phone will show "Do Not Disturb", but because the phone wasn't receiving XML status back from the server to tell it that it was in DND, the "X" icons would never flash for each line, and consequently I could never again press the DND button to disable the DND.....the only way out was to pick each line and dial the feature code to turn it off.  (My boss joked that I had created DED....Don't Ever Disturb.)  So you will know that this is working once you toggle it and see the "X" icons toggle on and off for each line registration...that is the key to this.

 

Note in the above Asterisk source edits that I included the XML schema that the Polycom needs from the server.  This is from a private document I received from Polycom that I cannot share, but for your interest, and for other call servers, the schema for DND status is basically as follows:

 

<?xml version="1.0" encoding="ISO-8859-1"?>
<DoNotDisturbEvent xmlns="http://www.ecma-international.org/standards/ecma-323/csta/ed3">
  <device>[EXTNUM]</device>
  <doNotDisturbOn>[true/false]</doNotDisturbOn>
</DoNotDisturbEvent>

 

... where [EXTNUM] is the extension number and [true/false] indicates whether or not DND is on.

 

If you have a FreePBX installation running with Fop2 (the updated version of the flash operator panel) and everything is configured correctly, you can also see the DND status as it exists on the server-side when you toggle DND on the Polycom phone.

 

I apologize in advance that this isn't a "run this installer/patch" type of solution, but I hope that this knowledge at least gives you the information necessary to implement this with your Polycom phones and your Asterisk server (or another call server).  I believe this covers everything, but let me know if you have any problems, and the symptoms, and I'll go back to double-check if I missed a step.  Know that you edit the Asterisk source at your own risk, although once you get used to it, this is by no means rocket science.

 

Happy server-side DND-ing with Polycom and Asterisk!

View solution in original post

Message 18 of 30
29 REPLIES 29
Valued Contributor

Re: Server-based DND using FAC/NOTIFY?

Hi portalmedia,

To my knowledge, previous support for server-based DND did not encompass star code dial strings.

 

Some PBX's like Asterisk utilize star codes instead of signaling via SIP messages to initialize and control server-based features.

 

reg.x.serverFeatureControl.deActivateCodeSequence.dnd is a string value that will be the sequence of digits to activate DND status on the server when dialed. This is usually a star code.

 

Try testing with this added to your configuration file:

reg.x.serverFeatureControl.deActivateCodeSequence.dnd="*76"

 (voIpProt.SIP.serverFeatureControl.dnd will need to be enabled as well)

 

If your Asterisk server has support for other star codes to control the various 'statuses' for DND (enable/disable for 'always, busy, noanswer', etc), you would want to utilize the other reg.x.serverFeatureControl parameters listed in the Release Notes.

 

Message 2 of 30
Advisor

Re: Server-based DND using FAC/NOTIFY?

Hi James, thanks for the response.

 

I tried your suggestion, but it doesn't seem to be doing anything.  I know I'm using version 3.3.1.

 

I put for each of my line registrations:

reg.1.serverFeatureControl.activateCodeSequence.dnd="*78"

reg.1.serverFeatureControl.deActivateCodeSequence.dnd="*79"

reg.2.serverFeatureControl.activateCodeSequence.dnd="*78"

reg.2.serverFeatureControl.deActivateCodeSequence.dnd="*79"

 

Then also:

voIpProt.SIP.serverFeatureControl.dnd="1"

 

I also tried setting reg.1.serverFeatureControl.dnd="1" and reg.2.serverFeatureControl.dnd="1" as well. Checking the logs on Asterisk, the phone doesn't seem to be sending the feature codes to it when I press the DND button.  Local DND is showing on the phone, but that's it.

 

I also see these in the release notes, with no mention of how to use them (so I haven't tried them).  Not sure if they are a piece of the puzzle, or not:

reg.x.serverFeatureControl.signalingMethod

reg.x.serverFeatureControl.subscribeToUri

 

Ideas?

Message 3 of 30
Advisor

Re: Server-based DND using FAC/NOTIFY?

OK, I feel like I am actually very, very close on this.  After spending way too much time on this, I figured out how to get the phone to enable DND using the feature code, and subscribe to get presence notifications. What the phone does not seem to do, is listen to the SIP NOTIFY that it is receiving from Asterisk, so I don't think it knows it's in DND, and consequently it will not issue the feature code to clear the server-side DND status (because I'm assuming it thinks it's not in DND).  With the SIP NOTIFY, I did go so far as to figure out that part of it was formatting, and after actually editing chan_sip.c and recompiling Asterisk, it is sending the presence message and the phone is responding "200 OK" to it, but I still don't think it's listening to the notification.

And so the question to Polycom..... Can you give me an example of a working SIP NOTIFY that the phone will listen to for enabling its DND status?  Below is an example of what Asterisk is trying to send it now (I replaced revealing items in the SIP URI, put in some spaces where emoticons were appearing):

<?xml version="1.0" encoding="ISO-8859-1"?>
<presence xmlns="urn: ietf: params: xml: ns: pidf"
xmlns: pp="urn: ietf: params: xml: ns: pidf: person"
xmlns: es="urn: ietf: params: xml: ns: pidf: rpid: status: rpid-status"
xmlns: ep="urn: ietf: params: xml: ns: pidf: rpid: rpid-person" entity="sip:myext@my.sip.server">
  <pp: person>
    <status>
      <ep:activities>
        <ep:busy/>
      </ep:activities>
    </status>
  </pp: person>
  <note>On the phone</note>
  <tuple id="myext">
    <contact priority="1">sip:my ext@my.sip.server</contact>
    <status>
      <basic>closed</basic>
    </status>
  </tuple>
</presence>

 Please, please help. I am so close, I think......so very, very close.

Message 4 of 30
Advisor

Re: Server-based DND using FAC/NOTIFY?

Seems like this topic has generated a bit of interest. The release notes refer to an ID # 55059, which doesn't seem to be posted as a technical document online that I can see.  I'm eager to finally get this working and then share the whole solution for the benefit of us Polycom &  Asterisk/FreePBX users. Again, all I need to know is the acceptable format of the pidf+xml (or xpidf+xml, with a pidf+xml header?) SIP NOTIFY that'll tell the Polycom that it's supposed to be in DND.  It's frustrating that there's no documentation on this yet, and I gotta believe we can get this working somehow.

 

I just bought another SoundPoint IP 650 yesterday for our company, and was hoping to be able to consult on this and recommend these phones to other clients of mine who are considering going VoIP. As such, I'm very grateful for the creation of this new support community and I'm hoping that we can come up with good solutions for some of the remaining nagging issues that Polycoms and Asterisk-based systems have with some of these features.

 

Are there any Polycom engineers, developers....who can give the answer to this?

Message 5 of 30
Polycom Employee & Community Manager

Re: Server-based DND using FAC/NOTIFY?

Hello Portalmedia,

 

my colleague James suggested the serverFeatureControl.activateCodeSequencedeActivateCodeSequence configuration Parameters.

 

I have looked through the UCS 3.3.0 Admin Guide and the UCS 3.3.1 Rev F template files and none of these Parameters seem to be mentioned yet for this Software Version.

 

We have some upcoming releases that include the Functionality to use Feature Access Code to set the Feature and a SIP NOTIFY message to inform the phone of the feature state but as far as I am aware this is not yet documented in the current Software (UCS 3.3.1).

 

Looking at the Polycom Spectralink 8400 Admin Guide at http://support.polycom.com/global/documents/support/setup_maintenance/products/voice/UC_Software_4_0...

 

I can see these Parameters and their values documented (PLEASE BE AWARE THAT THIS SOFTWARE HAS NOT YET BEEN RELEASED FOR YOUR HARDWARE!) and it mentions in addition reg.x.serverFeatureControl.signalingMethod.

 

The default setting for this is subscribeAsFeatureEvent and another value can be inviteFACSubscribePresence.

 

There is also a reg.x.serverFeatureControl.subscribeToUri with an interpretation of  "The URL to subscribe to when  sending the server-controlled feature requests".

 

Please be aware that these features are not yet documented in the UCS 3.3.1 Release and have most likely been added for Interop Partners so Polycom Support may be unable to provide any further assistance until the Documentation has been updated and the feature is officially released to the public.

 

Best Regards

 

Steffen Baier

----------------
The title Polycom Employee & Community Manager is a community setting and does not reflect my role. I am just a simple volunteer in the community like everybody else. My official "day" Job is 3rd Level support at Poly but I am unable to provide official support via the community.

----------------

Notice: This community forum is not an official Poly support resource, thus responses from Poly employees, partners, and customers alike are best-effort in attempts to share learned knowledge. If you need immediate and/or official assistance please open a service ticket through your proper support channels.
Please also ensure you always check the VoIP , Video Endpoint , Skype for Business , PSTN or RPM FAQ's
Message 6 of 30
Advisor

Re: Server-based DND using FAC/NOTIFY?

Thank you, Steffen, for your response, and the link to the 4.0 guide.  The parameters are indeed mentioned in the release notes for UCS 3.3.1F (but not documented as they are in the 4.0 guide).  So I was hoping that the functionality would work on some level.

 

That said, though, I'm sorry to say that I am, at least, that far along in getting this set up. After beefing up the phone logging, I was able to find the "inviteFACSubscribePresence" value because the logs told me it was a valid value. Also, I think I figured out for myself that I also needed to use the subscribeToUri (I'm using "sip:extnum@my.asterisk.server.addr", with a hint specified for the same extnum on Asterisk's end, like how hints work for BLF presence).

 

Ergo, I can hit DND, it'll send the feature code to put the phones in DND, and I can see Asterisk send the SIP NOTIFY with the presence information back to the phone, and the phone replies with a "200 OK" to that, but then doesn't do anything to recognize that it's in DND. It doesn't seem to be interpreting the notify.  Because of that, I can only bring the phone out of DND on the server-side by manually dialing the feature codes for each line registration.  Because the Polycom doesn't know it's in DND, it doesn't let me clear DND status because it thinks its still off....so it won't dial the deactivation feature code.  My boss jokes that we've created a DED...."Don't Ever Disturb".  It only goes one way, and can't be turned off.

 

Now, getting into detail about the the subscribe/notify that Asterisk is sending but the Polycom is not apparently interpreting.....

 

For BLF presence, the Polycoms want, and use, the xpidf+xml format that Asterisk delivers to it....and it does this quite well, for on-the-phone and DND indications.  When the Polycoms subscribe to this presence, it notifies Asterisk correctly that it accepts xpidf+xml as a format, so that's what Asterisk sends it.  And that part of the whole presence thing works great.

 

For the DND subscription, though, the Polycom tells Asterisk that it only accepts pidf+xml.  Curiously, the current programming of chan_sip.c says that, in effect, Polycoms only "really" listen to xpidf+xml, even if they say they want pidf+xml, so they hardcoded it to always send xpidf no matter what the Polycom asks for.  If I left Asterisk the way it was written, the Polycom responds "415 Media Type Not Supported" when it receives the SIP NOTIFY of DND status from Asterisk.  I suppose that makes sense, as the Polycom did in fact only state in the subscribe that it wanted pidf+xml.  OK, so I edited chan_sip.c and recompiled it, so that Asterisk would send the Polycom what it asked for....pidf+xml.  Asterisk sends the notify for DND, the Polycom responds "200 OK" to it, but does nothing.  I scour the Internet for the various options in formatting a pidf presence indication (because apparently Asterisk, Cisco phones, and others, all have slightly different schema. As this is not documented for Polycoms, not even in the document you gave me the link to, I don't know for sure what the Polycom is really looking for in the notify).

 

Given that the Polycoms do respond to BLF presence notifications in xpidf format correctly, I also tried hacking chan_sip.c in Asterisk to send the same xpidf message that it does for BLF, but to avoid the 415 error, I told the SIP header that the Content-type is pidf+xml as the phone asked for.  So then it was sending a SIP NOTIFY with a Content-type of pidf+xml, but the contents of the message is the same xpidf format that the Polycom gets, and acts on correctly for, BLF notifications.  The phone responds "200 OK" to the message again, but still, it does nothing.  I've cranked up all of the logging possible on the phone, but it isn't giving me any intel as to what it's looking for, so it can recognize from the notify that it's in DND.  I've now tried several variants of pidf and xpidf presence messages, to no avail.  I don't know if this is actually a bug in 3.3.1F that is going to be addressed in 4.0 (I don't suppose that's in public beta for the newer SoundPoint phones, is it?).  Or if this is just a case where the Polycom is looking for a very specific schema that Asterisk is not sending to it.....in which case if I knew that schema, I could edit chan_sip.c so that Asterisk sends the right thing to the Polycom....and then beseech the Asterisk community to make those changes on their end, so non-Asterisk hackers can also enjoy the feature.

 

That is basically the full extent of where I am with this. The main problem is that this has turned into a vendetta. For such a seemingly trivial thing, you have no idea the sense of accomplishment I will feel if there is a resolution to this that can be shared in some way.

Message 7 of 30
Polycom Employee & Community Manager

Re: Server-based DND using FAC/NOTIFY?

Hello Portalmedia,

 

at this moment in time, we from Support do not hold any public information on formatting the SIP Notify response for a working DND example.

 

I can only advise you to make yourself familiar with the Polycom ARENA Program at http://www.polycom.com/partners/interoperability/polycom_arena/voip_interoperability_partner_program...

 

Above is designed for VoIP Interoperability Platforms and enables manufacturers of SIP-based call control platforms to interact with Polycom.

 

Best Regards

 

Steffen Baier

 

Polycom Global Services

----------------
The title Polycom Employee & Community Manager is a community setting and does not reflect my role. I am just a simple volunteer in the community like everybody else. My official "day" Job is 3rd Level support at Poly but I am unable to provide official support via the community.

----------------

Notice: This community forum is not an official Poly support resource, thus responses from Poly employees, partners, and customers alike are best-effort in attempts to share learned knowledge. If you need immediate and/or official assistance please open a service ticket through your proper support channels.
Please also ensure you always check the VoIP , Video Endpoint , Skype for Business , PSTN or RPM FAQ's
Message 8 of 30
Advisor

Re: Server-based DND using FAC/NOTIFY?

OK, very well. Having said that, if Polycom intends to tout the added feature of FAC/Notify for DND/CFWD in their software releases, then as a member of the Polycom Community, I can only advise that Polycom generate and release some public information on the formatting of the SIP Notify messages so that we can actually use this new feature. Otherwise, why even mention its existence?

Message 9 of 30
Advisor

Re: Server-based DND using FAC/NOTIFY?

I completely agree with you, proper documentation helps maintain and grow the community ecosystem around Polycom products.

Message 10 of 30