Difference between revisions of "Broadsoft DMS"

Revision as of 07:42, 8 May 2018

Introduction

The Device Management System (DMS) is part of the Broadworks solution. It is an HTTPS server that delivers xml files for the OpenScape Desk Phone CP devices. The format and content is described in this document.

The xml file containing configuration and file deployment instructions is requested via a generic GET request. The server address and path can be configured on the phone. The file name is hardcoded and cannot be changed. It always is <MAC-address-of-device>_config.xml

The MAC address of the device is also send as header in the format: "macaddress: 0a1b2c3d4d5f"

The OpenScape Desk Phone CP devices support HTTP digest authentication, if username and password are properly configured

Set DMS address via DHCP

When an IP phone is booting, it first obtains an IP address via DHCP. The DHCP server can provide the DMS address to the phone via Option 43 or Option 66. The DMS address is mutually exclusive with a possibly provided DLS address. A phone can either connect to a DLS or DMS server.

Option 43

DHCP vendor specific option 43 can specify a voice VLAN ID and URL of a Broadsoft DMS server. IP phones will recognize vendor specific options only, if vendor string (here: "Siemens") matches correctly. All values are given in hexadecimal numbering format. Here is a detailed description of all DHCP option 43 bytes:

Tag Len Content (Example)
01  07  5369656d656e73
02  04  00000065
03  1d  68747470733a2f2f39332E3132322E3131342E39363a3434332f646d73
ff

There are three Tags, each with an explicit length value. List if tags is delimited by a ending ff

• Tag 01 specifies the vendor (here: Siemens)
  • Tag: 01; Length: 07; Value: Siemens
• Tag 02 specifies VLAN ID of Voice VLAN (here: 101)
  • Tag: 02; Length: 04; Value: 65 (Hex)
• Tag 03 specifies IP address of Broadsoft DMS (here: 93.122.114.96:443/dms)
  • Tag: 03; Length: 1d; Value: https://93.122.114.96:443/dms (Hex)
• End of record
  • End: ff (Hex)

Providing a VLAN ID is optional and only mentioned for completeness. You can find details for configuration of a VLAN ID here: http://wiki.unify.com/wiki/VLAN_ID_Discovery_over_DHCP

Option 66

The DHCP server needs to be configured to provide the DMS server URL via Option 66. Here is a detailed description of the Option 66 bytes

Option Len Content (Example)
42     1d  68747470733a2f2f39332e3132322e3131342e39363a3434332f646d73

Compared to Option 43, Option 66 does not have specific tags. It only has a length and content field. The above example provides the following URL in the content field

• DHCP option field: 42(Hex); Length: 1d; Content: https://93.122.114.96:443/dms (Hex)

Set DMS address via menu

You can also set the URL to your DMS via the local phone menu (in case it cannot be provided via DHCP). A DHCP configured address cannot be overwritten manually. The DMS address is mutually exclusive with a possibly configured DLS address. A phone can either connect to a DLS or DMS server.

Web based management

Open the web based management in a web browser window and login to the admin area of your Desk Phone CP device. Go to Network -> Update Service and provide the required URL, username and password.

Local phone menu

Press the main menu key and select Settings -> Administrator settings. Provide the admin password and afterwards select Network -> Update Service -> DMS -> Show details. Configure the required URL, username and password.

In case the provided username and password are incorrect or missing, the phone will automatically prompt the user for a new username and password.

update check interval

The update check interval defines when the device will contact the DMS server to check for updates. It's value needs to be given in seconds. On every download of the XML file, the phone generates a hash of the file and compares the new hash value with the hash from previous XML file download. The new XML file will only be parsed and applied if the hash has changed (the file has changed)

manual triggered check

The OpenScape Desk Phone CP can be triggered by the SIP server to check the configuration file. This can be done via SIP NOTIFY with Event type "check-sync". See Event header below.

 Event: check-sync

With the same NOTIFY message, the CP devices can be triggered to perform a reboot. Please see the Event header below.

 Event: check-sync;reboot=yes

Please find a SIPp scenario file, which simulates the above behavior, here: File:DMS check-sync reboot.xml

Content of config.xml file

The content of the XML file provided by the DMS server has the following schema. It can have one Action=WriteItems and one Action=SoftwareDeployment. It can have multiple sections for Action=FileDeployment.

 <?xml version="1.0" encoding="utf-8"?>
 <Message>
   <Action>WriteItems</Action>
   <ItemList>
     <Item name="ITEMNAME">VALUE</Item>
   </ItemList>
   <Action>SoftwareDeployment</Action>
   <ItemList>
     <Item name="ITEMNAME">VALUE</Item>
   </ItemList>
   <Action>FileDeployment</Action>
   <ItemList>
     <Item name="ITEMNAME">VALUE</Item>
   </ItemList>
 </Message>

Please see the chapters below for details

Action: WriteItems

This chapter is about WriteItems. WriteItems is used to send configuration items to the phone.

Generic Items

This section describes the items that can be configured on a CP device via a config.xml file.

Password related Items

Network related Items

System related Items

Feature related Items

QoS related items

Broadsoft Xtended Service Interface

The following section describes the settings for accessing the Broadsoft Xtended Service Interface (XSI)

 <Item name="bw-xsi-addr">https://xsp.iop1.broadworks.net</Item>
 <Item name="bw-xsi-sipauthentication">false</Item>
 <Item name="bw-xsi-username">username@broadworks.net</Item>
 <Item name="bw-xsi-password">123456</Item>
 <Item name="bw-ccl-enable">true</Item>
 <Item name="bw-cgdirectory-enable">true</Item>
 <Item name="bw-cgdirectory-name">Group Directory</Item>
 <Item name="bw-cedirectory-enable">true</Item>
 <Item name="bw-cedirectory-name">Enterprise Directory</Item>
 <Item name="bw-cgcdirectory-enable">true</Item>
 <Item name="bw-cgcdirectory-name">Group Common Directory</Item>
 <Item name="bw-cecdirectory-enable">true</Item>
 <Item name="bw-cecdirectory-name">Enterprise Common Directory</Item>
 <Item name="bw-cpdirectory-enable">true</Item>
 <Item name="bw-cpdirectory-name">Personal Directory</Item>

Broadsoft Device Management System

The following section describes the settings for accessing the Broadsoft Device Management System (DMS)

 <Item name="bw-dms-addr">https://xsp.iop1.broadworks.net/DMS/</Item>
 <Item name="bw-dms-username">username</Item>
 <Item name="bw-dms-password">password</Item>
 <Item name="bw-dms-contact-interval">300</Item>
 <Item name="bw-dms-sync-during-working-hours">true</Item>
 <Item name="memory-monitor-working-hour-start">6</Item>
 <Item name="memory-monitor-working-hour-end">22</Item>

BLF resource list subscription

The following section describes the settings for Broadsoft BLF resource list subscription settings. Please keep in mind that for every resource in the resource list, a seperate BLF key is required.

 <Item name="blf-resource-uri">user-a1</Item>
 <Item name="blf-code">*97</Item>

Date&Time Settings

The following section describes the settings for Date&Time on the phone

 <Item name="sntp-addr">0.pool.ntp.org</Item>
 <Item name="sntp-tz-offset">60</Item>
 <Item name="daylight-save">true</Item>
 <Item name="daylight-save-minutes">60</Item>
 <Item name="auto-daylight-save">true</Item>
 <Item name="daylight-save-zone-id">9</Item>

A list of possible values for Enumeration "daylight-save-zone-id"

• 0=Not set
• 1=Australia 2007 (ACT, South Australia, Tasmania, Victoria)
• 2=Australia 2007 (New South Wales)
• 3=Australia (Western Australia)
• 4=Australia 2008+ (ACT, New South Wales, South Australia, Tasmania, Victora)
• 5=Brazil
• 6=Canada
• 7=Canada (Newfoundland)
• 8=Europe (Portugal, United Kingdom)
• 9=Europe (Rest)
• 10=Europe (Finland)
• 11=Mexico
• 12=United States
• 13=New Zealand
• 14=New Zealand (Chatham)

Audio Codec Settings

Audio codecs require a special handling inside the config.xml file as they need to be send as a complete group. Example file below:

 <Item name="codec-type" index="1">0</Item>
 <Item name="codec-type" index="2">1</Item>
 <Item name="codec-type" index="3">2</Item>
 <Item name="codec-allowed" index="1">true</Item>
 <Item name="codec-allowed" index="2">true</Item>
 <Item name="codec-allowed" index="3">true</Item>
 <Item name="codec-packet-size" index="1">2</Item>
 <Item name="codec-packet-size" index="2">2</Item>
 <Item name="codec-packet-size" index="3">2</Item>
 <Item name="codec-rank" index="1">2</Item>
 <Item name="codec-rank" index="2">1</Item>
 <Item name="codec-rank" index="3">3</Item>
 <Item name="audio-silence-suppression">false</Item>

FPK programming

In order to program a free programmable key (FPK) via DMS, you need to take the phone type into account. The phone type defines the amount of keys you can program.

• 60 keys on CP600 (with 4 Key modules attached, 4 times 12 keys on the key modules, and the permanent favorites menu)
• 48 keys on CP400 (with 2 Key modules attached. 16 keys on the base device, 2 times 16 keys on the key modules)
• 4 keys on CP200/CP205 (all on the base device)
  • CP200/CP205 have a special functionality to directly access the second level functionality on the 4 free programmable keys.

First you need the key index where the functionality will be put on. The values below are valid for Desk Phone CP models running V1 R2 (or newer) software

Remember the index number of the FPK, where you want to configure a function. We will use index "1" in the following examples.

Shared call appearance

 <Item name="function-key-def" index="1">31</Item>
 <Item name="key-label-unicode" index="1">Bob Smith</Item>
 <Item name="line-primary" index="1">true</Item>
 <Item name="line-shared-type" index="1">0</Item>
 <Item name="line-sip-uri" index="1">2405551111_1</Item>
 <Item name="line-sip-user-id" index="1">bobsmith</Item>
 <Item name="line-sip-pwd" index="1">bobs</Item>
 <Item name="line-sip-realm" index="1">realm</Item>
 <Item name="line-ring" index="1">true</Item>
 <Item name="line-ring-delay" index="1">0</Item>

Multiple Call Arrangement

The configuration is similar to the Shared Call Appearance configuration. You need one line configured as primary line.

 <Item name="function-key-def" index="1">31</Item>
 <Item name="key-label-unicode" index="1">Line 1</Item>
 <Item name="line-primary" index="1">true</Item>
 <Item name="line-shared-type" index="1">0</Item>
 <Item name="line-sip-uri" index="1">2405551111</Item>
 <Item name="line-sip-user-id" index="1">bobsmith</Item>
 <Item name="line-sip-pwd" index="1">bobs</Item>
 <Item name="line-sip-realm" index="1">realm</Item>
 <Item name="line-ring" index="1">true</Item>
 <Item name="line-ring-delay" index="1">0</Item>

You can have up to 5 secondary lines with the same E164 number configured. Digest authentication is required on the primary line only.

 <Item name="function-key-def" index="2">31</Item>
 <Item name="key-label-unicode" index="2">Line 2</Item>
 <Item name="line-primary" index="2">false</Item>
 <Item name="line-sip-uri" index="2">2405551111</Item>
 <Item name="line-ring" index="2">true</Item>
 <Item name="line-ring-delay" index="2">0</Item>

 <Item name="function-key-def" index="3">31</Item>
 <Item name="key-label-unicode" index="3">Line 3</Item>
 <Item name="line-primary" index="3">false</Item>
 <Item name="line-sip-uri" index="3">2405551111</Item>
 <Item name="line-ring" index="3">true</Item>
 <Item name="line-ring-delay" index="3">0</Item>

Multiuser

The configuration is similar to the Shared Call Appearance configuration. You need one line configured as primary line. The primary line will use the existing main configuration for XSI connection.

 <Item name="function-key-def" index="1">31</Item>
 <Item name="key-label-unicode" index="1">Line 1</Item>
 <Item name="line-primary" index="1">true</Item>
 <Item name="line-shared-type" index="1">0</Item>
 <Item name="line-sip-uri" index="1">2405551111</Item>
 <Item name="line-sip-user-id" index="1">bobsmith</Item>
 <Item name="line-sip-pwd" index="1">bobs</Item>
 <Item name="line-sip-realm" index="1">realm</Item>
 <Item name="line-ring" index="1">true</Item>
 <Item name="line-ring-delay" index="1">0</Item>

Additional line keys for separate users are configured in a similar way, except they must have the line share type set to private and (of cause) must not be a primary line

 <Item name="function-key-def" index="2">31</Item>
 <Item name="key-label-unicode" index="2">Line 2</Item>
 <Item name="line-primary" index="2">false</Item>
 <Item name="line-shared-type" index="2">1</Item>
 <Item name="line-sip-uri" index="2">2405552222</Item>
 <Item name="line-sip-user-id" index="2">markdoe</Item>
 <Item name="line-sip-pwd" index="2">markd</Item>
 <Item name="line-sip-realm" index="2">realm</Item>
 <Item name="line-ring" index="2">true</Item>
 <Item name="line-ring-delay" index="2">0</Item>

Every separate line can have its own XSI username by adding the following item to the configuration

 <Item name="line-xsi-username" index="2">markdoe@company.com</Item>

Busy Lamp Field (BLF)

 <Item name="function-key-def" index="1">59</Item>
 <Item name="key-label-unicode" index="1">Bob Smith</Item>
 <Item name="blf-audible" index="1">true</Item>
 <Item name="blf-popup" index="1">true</Item>
 <Item name="stimulus-led-control-uri" index="1">user-a2</Item>

Broadsoft Call Center

 <Item name="function-key-def" index="1">43</Item>
 <Item name="key-label-unicode" index="1">Agent Logon</Item>
 <Item name="xsi-call-center-name" index="1">my_call_center</Item>
 <Item name="xsi-call-center-related-line" index="1">7</Item>

Selected dialling

 <Item name="function-key-def" index="1">1</Item>
 <Item name="key-label-unicode" index="1">Selected Dial</Item>
 <Item name="select-dial" index="1">12345</Item>

Forwarding

 <Item name="function-key-def" index="1">6</Item>
 <Item name="key-label-unicode" index="1">Forward unconditional</Item>
 <Item name="forwarding-type" index="1">0</Item>
 <Item name="forwarding-dest" index="1">123456</Item>

Send URL

Please see http://wiki.unify.com/wiki/Send_URL for details about this functionality

 <Item name="function-key-def" index="1">63</Item>
 <Item name="key-label-unicode" index="1">Send URL</Item>
 <Item name="send-url-address" index="1">some-address-or-ip.com</Item>
 <Item name="send-url-protocol" index="1">0</Item>
 <Item name="send-url-port" index="1">443</Item>
 <Item name="send-url-path" index="1">/some/path/on/server</Item>
 <Item name="send-url-query" index="1">paramA=1&paramB=2&paramC=3</Item>
 <Item name="send-url-method" index="1">1</Item>
 <Item name="send-url-user-id" index="1">username</Item>
 <Item name="send-url-passwd" index="1">password</Item>
 <Item name="send-url-push-support" index="1">true</Item>
 <Item name="send-url-symbolic-name" index="1">SymbolicName</Item>

Repertory Dial

Repertory Dial key is similar to a selected dial key, with the following special functionality

• $Q -> Release (WBM symbol=<)
• $R -> Consult (WBM symbol=~)
• $S -> Okay (WBM symbol=>)
• $T -> Pause (WBM symbol=-)

 <Item name="function-key-def" index="1">30</Item>
 <Item name="key-label-unicode" index="1">Repertory Dial</Item>
 <Item name="repertory-dial" index="1">55555$S$T1234#</Item>

Generic FPKs

 <Item name="function-key-def" index="1">nn</Item>
 <Item name="key-label-unicode" index="1">Key label text</Item>

Below you can find a list of possible values for item "function-key-def" and the corresponding functionality

Feature access settings

The phone allows to restrict access to specifc features for the user. This section will show the relevant Items to configure if you want the user to not have access to a specific functionality.

 <Item name="agent-feature-enabled">false</Item>
 <Item name="enable-bluetooth-interface">false</Item>
 <Item name="enable-WBM">false</Item>
 <Item name="pb-lookups-allowed">false</Item>
 <Item name="refuse-call">false</Item>
 <Item name="callback-busy-allow">false</Item>
 <Item name="allow-user-access-to-diagnostic-data">false</Item>
 <Item name="feature-availability" index="1">false</Item>
 <Item name="feature-availability" index="2">false</Item>
 <Item name="feature-availability" index="11">false</Item>
 <Item name="feature-availability" index="23">false</Item>
 <Item name="feature-availability" index="24">false</Item>
 <Item name="feature-availability" index="27">false</Item>
 <Item name="feature-availability" index="28">false</Item>
 <Item name="feature-availability" index="29">false</Item>
 <Item name="feature-availability" index="31">false</Item>
 <Item name="feature-availability" index="32">false</Item>
 <Item name="feature-availability" index="34">false</Item>
 <Item name="feature-availability" index="36">false</Item>

Locked config menu settings

The phone allows to lock specifc features for the user. This section will show the relevant Items to configure if you want specific menus to be locked.

 <Item name="locked-config-menus" index="1">true</Item>
 <Item name="locked-config-menus" index="2">true</Item>
 <Item name="locked-config-menus" index="3">true</Item>
 <Item name="locked-config-menus" index="4">true</Item>
 <Item name="locked-config-menus" index="5">true</Item>
 <Item name="locked-config-menus" index="8">true</Item>
 <Item name="locked-config-menus" index="9">true</Item>
 <Item name="locked-config-menus" index="10">true</Item>
 <Item name="locked-config-menus" index="11">true</Item>
 <Item name="locked-config-menus" index="14">true</Item>
 <Item name="locked-config-menus" index="15">true</Item>
 <Item name="locked-config-menus" index="16">true</Item>
 <Item name="locked-config-menus" index="17">true</Item>
 <Item name="locked-config-menus" index="18">true</Item>
 <Item name="locked-config-menus" index="19">true</Item>
 <Item name="locked-config-menus" index="21">true</Item>
 <Item name="locked-config-menus" index="23">true</Item>
 <Item name="locked-config-menus" index="32">true</Item>
 <Item name="locked-config-menus" index="33">true</Item>
 <Item name="locked-config-menus" index="35">true</Item>
 <Item name="locked-config-menus" index="38">true</Item>
 <Item name="locked-config-menus" index="43">true</Item>
 <Item name="locked-config-menus" index="44">true</Item>
 <Item name="locked-config-menus" index="48">true</Item>
 <Item name="locked-config-menus" index="49">true</Item>
 <Item name="locked-config-menus" index="52">true</Item>
 <Item name="locked-config-menus" index="53">true</Item>
 <Item name="locked-config-menus" index="56">true</Item>
 <Item name="locked-config-menus" index="60">true</Item>
 <Item name="locked-config-menus" index="61">true</Item>
 <Item name="locked-config-menus" index="62">true</Item>
 <Item name="locked-config-menus" index="63">true</Item>
 <Item name="locked-config-menus" index="64">true</Item>
 <Item name="locked-config-menus" index="66">true</Item>
 <Item name="locked-config-menus" index="68">true</Item>
 <Item name="locked-config-menus" index="70">true</Item>
 <Item name="locked-config-menus" index="71">true</Item>
 <Item name="locked-config-menus" index="72">true</Item>
 <Item name="locked-config-menus" index="73">true</Item>
 <Item name="locked-config-menus" index="77">true</Item>
 <Item name="locked-config-menus" index="78">true</Item>
 <Item name="locked-config-menus" index="79">true</Item>
 <Item name="locked-config-menus" index="80">true</Item>
 <Item name="locked-config-menus" index="81">true</Item>
 <Item name="locked-config-menus" index="82">true</Item>
 <Item name="locked-config-menus" index="83">true</Item>
 <Item name="locked-config-menus" index="84">true</Item>
 <Item name="locked-config-menus" index="85">true</Item>
 <Item name="locked-config-menus" index="86">true</Item>
 <Item name="locked-config-menus" index="87">true</Item>
 <Item name="locked-config-menus" index="88">true</Item>

User settings

The following section is all about user settings, which the user can change on their own, but still allow to be remotely configured via DMS

 <Item name="country-iso">DE</Item>
 <Item name="language-iso">de</Item>
 <Item name="date-format">0</Item>
 <Item name="time-format">0</Item>
 <Item name="pixelsaver-timeout-xt">15</Item>
 <Item name="screensaver-enabled">true</Item>
 <Item name="inactivity-screen-type">0</Item>
 <Item name="inactivity-timeout">1</Item>
 <Item name="screensaver-image-timeout">10</Item>
 <Item name="landing-screen">2</Item>
 <Item name="key-click-volume">0</Item>
 <Item name="click-keys">0</Item>
 <Item name="busy-when-dialling-enabled">true</Item>
 <Item name="call-waiting-enabled">true</Item>
 <Item name="call-dnd-enabled">true</Item>
 <Item name="auto-answer">false</Item>
 <Item name="beep-on-auto-answer">false</Item>
 <Item name="beep-on-auto-reconnect">false</Item>  

Ringer settings

The following section is all about ringer settings.

Pattern ringers

This section describes the configuration of the integrated pattern ringtones

 <Item name="ringer-audio-file"></Item>
 <Item name="ringer-tone-sequence"></Item>
 <Item name="ringer-melody"></Item>

Action: SoftwareDeployment

This chapter is about SoftwareDeployment. It is used to provide a new software image file to the OpenScape Desk Phone CP devices. The following items are required, so the phone can verify the software image file and proceed with the update.

 <Item name="file-name">OS_HI_SIP_V1_R1.7.0.img</Item>
 <Item name="file-type">APP</Item>
 <Item name="file-sw-version">1.1.7.0000</Item>
 <Item name="file-sw-type">SIP</Item>

The update procedure "in a nutshell":

• The phone will periodically check the DMS server for changes to the XML file
• When the XML file has changed, the SoftwareDeployment action will be parsed
• If file-sw-version differs from the version currently installed, the file at "file-name" will be downloaded and installed

Action: FileDeployment

This chapter is about FileDeployment. It is used to provide Ringtones or Screensaver files for the phone to download. The following items are required.

 <Item name="file-https-base-url">https://1.2.3.4/file.type</Item>
 <Item name="file-type">RINGTONE</Item>