topic AXL: Update Device Profile Line Appearance in Management

AXL: Update Device Profile Line Appearance

jeremy11 — Fri, 03 Feb 2017 15:21:25 GMT

I'm attempting to update the line appearance for a device profile's line via AXL. Whenever I submit the query, all the line data reverts back to default data and/or clears all information... For instance, the display, ascii display, line text label, ascii line text label, external phone number mask, max # of calls, and busy trigger all switch back to a blank value. Could someone look over this request and explain why this may be happening? I'm not an expert in AXL and I have looked at other threads but haven't found a solution that works for me... Here is my AXL request with numbers and credentials redacted...

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.cisco.com/AXL/API/9.1">

<soapenv:Header/>

<soapenv:Body>

<ns:updatePhone sequence="?">

<name>DeviceProfileName</name>

<lines>

<label>LabelText</label>

<asciiLabel>LabelText</asciiLabel>

<display>DisplayText</display>

<consecutiveRingSetting>Use System Default</consecutiveRingSetting>

<displayAscii>DisplayText</displayAscii>

<mwlPolicy>Use System Policy</mwlPolicy>

<callerNumber>false</callerNumber>

<redirectedNumber>false</redirectedNumber>

</callInfoDisplay>

<recordingFlag>Call Recording Disabled</recordingFlag>

<audibleMwi>Default</audibleMwi>

<partitionUsage>General</partitionUsage>

</lineIdentifier>

</lines>

</ns:updatePhone>

</soapenv:Body>

</soapenv:Envelope>

Re: AXL: Update Device Profile Line Appearance

dstaudt — Fri, 03 Feb 2017 23:18:10 GMT

When using <updatePhone> with the <lines> collection, during the operation CUCM first removes all line appearances from the device, then re-creates line appearances as specified in the new <lines>.

It's important to make the distinction that the fields you are referring to - such as <display> - belong to the 'line appearance' on that particular device, rather than to the line itself (which may appear on multiple devices as a shared line.) If you look at the phone and then click on the line in CUCM admin, the sections ending with " on Device {MyDevice}" pertain to the line appearance (vs. the base line.)

If you use <updatePhone> with <lines><lineIdentifier>, then CUCM first removes all the previous line appearances (including any line-appearance-specific info like the display text), then re-adds the new line as a new line appearance. The problem of course is that <lineIdentifier> does not permit definition of all the line-appearance specific fields (like <display>), and so those are all going to be blank. Note, you example request includes a bunch of fields (like <display>) that aren't actually part of the schema for <lineIdentifier>: https://developer.cisco.com/media/axl-schema-11-5/Files/AXLSoap_UpdatePhoneReq.html#Link5371)

To accomplish your goal, you will want to use <updatePhone><lines><line>, which does allow you to specify all the line-appearance-specific data in the request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.cisco.com/AXL/API/10.5">
  <soapenv:Header/>
  <soapenv:Body>
      <ns:updatePhone>
        <name>CSFDSTAUDT</name>
        <lines>
            <line>
                <index>1</index>
                <dirn>
                    <pattern>1001</pattern>
                    <routePartitionName/>
                </dirn>
                <display>testDisplay</display>
            </line>
        </lines>
      </ns:updatePhone>
  </soapenv:Body>
</soapenv:Envelope>

Re: AXL: Update Device Profile Line Appearance

jeremy11 — Wed, 08 Feb 2017 16:04:02 GMT

Thank you so much for your very clear and precise answer. Much appreciated!

Re: AXL: Update Device Profile Line Appearance

derek.fraser — Mon, 30 Mar 2020 13:29:40 GMT

Thanks for the tips jeremy and dstaut! When utilizing the updateDeviceProfile schema element I'm able to update line specific elements like e164Mask but am seeing the AXL API remove all other lines on the profile. For example if a User Device Profile has Line1:1001, Line2:1002 and Line3:1003 the below request updates the external phone mask for 1001, but then removes 1002 and 1003.

<soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
  <soap-env:Body>
    <ns0:updateDeviceProfile xmlns:ns0="http://www.cisco.com/AXL/API/11.5">
      <name>UDP-1001</name>
      <lines>
        <line>
          <index>1</index>
          <dirn>
            <pattern>1001</pattern>
            <routePartitionName>Internal-PT</routePartitionName>
          </dirn>
          <e164Mask>8885551001</e164Mask>
        </line>
      </lines>
    </ns0:updateDeviceProfile>
  </soap-env:Body>
</soap-env:Envelope>

dstaut pointed out that CUCM will first remove all previous line appearances, then re-adds the new line as a new line appearance. Am I not understanding the updateDeviceProfile or updatePhone API correctly? I thought updateDeviceProfile would update whereas addDeviceProfile would overwrite? Is there a way to update a unique element? The use case being updating the external phone mask on UDP's that could potentially have more than one line?

Re: AXL: Update Device Profile Line Appearance

dstaudt — Wed, 08 Apr 2020 12:32:14 GMT

addDeviceProfile|Phone can only be used if the device does not yet exist (add a new device). updateDeviceProfile|Phone are used to update an existing device/phone. Using one of updateDeviceProfile|Phone, the <lines> collection will be replaced with whatever you submit - typically this means for an update you will want to retrieve the existing settings via getDeviceProfile|Phone so you can submit the complete list to update.

Many AXL update requests work the same way, though a select number also include <addXXX> and <removeXXX> elements which can be used instead of the <XXX> collection. I.e. with updateUserGroup you can specify individual members to add/remove using <addMembers> and/or <removeMembers>, or simply replace the entire list via <members>. Unfortunately, updateDeviceProfile|Phone <lines> does not support this pattern.

Re: AXL: Update Device Profile Line Appearance

derek.fraser — Thu, 09 Apr 2020 15:34:26 GMT

thanks for the info dstaudt, very much appreciated. I've adjusted to your recommendation and use the getDeviceProfile first and iterate through the lines for the dirn/pattern e164Mask to update, then feed the entire lines collection back via the updateDeviceProfile. Is this the recommended approach for updating a single parameter on a line like e164Mask/maxNumCalls/busyTrigger? The schema references the nillable fields and in my testing using updateDeviceProfile with just name and lines does not modify any other existing parameters, I guess my question is how would I know which fields the API removes/re-adds over leaving as-is? Or is the general best practice for any updates first do a get and send every element back in the update?

Re: AXL: Update Device Profile Line Appearance

dstaudt — Thu, 09 Apr 2020 17:08:19 GMT

In general you should find that omitting an element will keep the value as-is, providing a nil element will attempt to make it null/empty/default. So in your case, you can probably just provide the <lines> collection specifying just the line/dirn identifier (as you mention) and provide only the elements you want changed on the target device(s).