cisco-axl 1.0.1 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
 # Cisco AXL SOAP Library
 
-Simple library to pull AXL data Cisco CUCM via SOAP. The goal of this project is to make it easier for people to use AXL and to include all functionality of AXL!
+A Javascript library to pull AXL data Cisco CUCM via SOAP. The goal of this project is to make it easier for people to use AXL and to include all functionality of AXL. This library utilizes [strong-soap](https://www.npmjs.com/package/strong-soap) to read Cisco's WSDL file. As a result this library can use any function in the schema for the version that you specify.
 
 Administrative XML (AXL) information can be found at:
 [Administrative XML (AXL) Reference](https://developer.cisco.com/docs/axl/#!axl-developer-guide).
@@ -30,10 +30,10 @@ NODE_TLS_REJECT_UNAUTHORIZED=0
 
 ## Features
 
-* This library uses strong-soap to parse the AXL WSDL file. As a result any AXL function for your specified version is avaliable to use!
-* Supports the Promise API
-* Returns all results in JSON rather than XML
-* Automatically cleans up SQL queries to avoid injection
+- This library uses strong-soap to parse the AXL WSDL file. As a result any AXL function for your specified version is avaliable to use!
+- Supports the Promise API. Can chain procedures together or you could use Promise.all() to run multiple "get" operations at the same time.
+- Returns all results in JSON rather than XML. Function has options to remove all blank or empty fields from JSON results via optional clean parameter.
+- Support for [json-variables](https://codsen.com/os/json-variables). The executeOperation function will recognize the dataContainerIdentifierTails from json-variables and remove them from your call. This avoids any SOAP fault issues from having extra information in call. See examples folder for use case.
 
 ## Usage
 
@@ -42,37 +42,154 @@ const axlService = require("cisco-axl");
 
 let service = new axlService("10.10.20.1", "administrator", "ciscopsdt");
 
-var method = "addRoutePartition";
-var params = {
+var operation = "addRoutePartition";
+var tags = {
   routePartition: {
-    name: 'INTERNAL-PT',
-    description: 'Internal directory numbers',
-    timeScheduleIdName: '',
-    useOriginatingDeviceTimeZone: '',
-    timeZone: '',
-    partitionUsage: ''
-  }
+    name: "INTERNAL-PT",
+    description: "Internal directory numbers",
+    timeScheduleIdName: "",
+    useOriginatingDeviceTimeZone: "",
+    timeZone: "",
+    partitionUsage: "",
+  },
 };
 
 service
-.executeMethod(method, params)
-.then((results) => {
-    console.log(`Here are a list of all the partitions on our cluster:`);
-    results.routePartition.map((str) => {
-        console.log(str.name);
-    });
-})
-.catch((error) => {
+  .executeOperation(operation, tags)
+  .then((results) => {
+    console.log("addRoutePartition UUID", results);
+  })
+  .catch((error) => {
     console.log(error);
-});
+  });
 ```
 
+## Methods
+
+- new axlService(options: obj)
+- axlService.returnOperations(filter?: string)
+- axlService.getOperationTags(operation: string)
+- axlService.executeOperation(operation: string,tags: obj, opts?: obj)
+
+### new axlService(options)
+
+Service constructor for methods. Requires a JSON object consisting of hostname, username, password and version.
+
+```node
+let service = new axlService("10.10.20.1", "administrator", "ciscopsdt", "14.0");
+```
+
+### axlService.returnOperations(filter?) ⇒ Returns promise
+
+Method takes optional argument to filter results. No argument returns all operations. Returns results via Promise.
+
+| Method           | Argument | Type   | Obligatory | Description                         |
+| :--------------- | :------- | :----- | :--------- | :---------------------------------- |
+| returnOperations | filter   | string | No         | Provide a string to filter results. |
+
+### axlService.getOperationTags(operation) ⇒ Returns promise
+
+Method requires passing an AXL operation. Returns results via Promise.
+
+| Method           | Argument  | Type   | Obligatory | Description                                                              |
+| :--------------- | :-------- | :----- | :--------- | :----------------------------------------------------------------------- |
+| getOperationTags | operation | string | Yes        | Provide the name of the AXL operation you wish to retrieve the tags for. |
+
+### axlService.executeOperation(operation,tags,opts?) ⇒ Returns promise
+
+Method requires passing an AXL operation and JSON object of tags. Returns results via Promise.
+
+Current options include:
+| option | type | description |
+| :--------------------------- | :------ | :---------------------------------------------------------------------------------- |
+| clean | boolean | Default: **false**. Allows method to remove all tags that have no values from return data. |
+| dataContainerIdentifierTails | string | Default: **'\_data'**. executeOperation will automatically remove any tag with the defined string. This is used with json-variables library. |
+
+Example:
+
+```node
+var opts = {
+  clean: true,
+  dataContainerIdentifierTails: "_data",
+};
+```
+
+| Method           | Argument  | Type   | Obligatory | Description                                                |
+| :--------------- | :-------- | :----- | :--------- | :--------------------------------------------------------- |
+| executeOperation | operation | string | Yes        | Provide the name of the AXL operation you wish to execute. |
+| executeOperation | tags      | object | Yes        | Provide a JSON object of the tags for your operation.      |
+| executeOperation | opts      | object | No         | Provide a JSON object of options for your operation.       |
+
 ## Examples
 
-Check /test/tests.js for more examples.
+Check **examples** folder for different ways to use this library. Each folder should have a **README** to explain about each example.
+
+You can also run the **tests.js** against Cisco's DevNet sandbox so see how each various method works.
 
 ```javascript
 npm run test
 ```
 
-Note: Test are using Cisco's DevNet sandbox information. Find more information here: [Cisco DevNet](https://devnetsandbox.cisco.com/)
+Note: Test are using Cisco's DevNet sandbox information. Find more information here: [Cisco DevNet](https://devnetsandbox.cisco.com/).
+
+## json-variables support
+
+At a tactical level, json-variables program lets you take a plain object (JSON files contents) and add special markers in any value which you can then reference in a different path.
+
+This library will recoginize json-variables **\*\_data** keys in the tags and delete before executing the operation.
+
+Example:
+
+```node
+var lineTemplate = {
+  pattern: "%%_extension_%%",
+  routePartitionName: "",
+  alertingName: "%%_firstName_%% %%_lastName_%%",
+  asciiAlertingName: "%%_firstName_%% %%_lastName_%%",
+  description: "%%_firstName_%% %%_lastName_%%",
+  _data: {
+    extension: "1001",
+    firstName: "Tom",
+    lastName: "Smith",
+  },
+};
+
+const lineTags = jVar(lineTemplate);
+
+service
+  .executeOperation("updateLine", lineTags)
+  .then((results) => {
+    console.log(results);
+  })
+  .catch((error) => {
+    console.log(error);
+  });
+```
+
+Note: If you need to change the variables key you can so via options in both the json-variables and with executeOperations.
+
+Example:
+
+```node
+...
+const lineTags = jVar(lineTemplate,{ dataContainerIdentifierTails: "_variables"});
+
+service.executeOperation("updateLine", lineTags,{ dataContainerIdentifierTails: "_variables"})
+...
+```
+
+## Limitations
+
+Currently there is an issue with strong-soap regarding returning nillable values for element tags. These values show if a particular tags is optional or not. Once resolved a method will be added to return tags nillable status (true or false).
+
+## TODO
+
+- Add more promised based examples, particularly a Promise.All() example.
+- Add example for reading in CSV and performing a bulk exercise with variables.
+- Add example for saving SQL output to CSV or uploading to cloud (Airtable or SmartSheets).
+
+## Giving Back
+
+If you would like to support my work and the time I put in creating the code, you can click the image below to get me a coffee. I would really appreciate it (but is not required).
+
+[Buy Me a Coffee](https://www.buymeacoffee.com/automatebldrs)

package/examples/change_phone_model/changePhoneModel.js

@@ -0,0 +1,159 @@
+const axlService = require("../../index");
+
+/*
+Ever wanted to change a phone model, but keep the existing one in CUCM? This script will attempt to migrate a phone to the new model.
+It uses SQL queries to grab some of the product specific information for the new model.
+
+We will be using axl to "getPhone" information and then make changes before calling the "addPhone" operation.
+ - First we will use the "getPhone" operation to return some values for the phone we will be using to copy.
+ - Next we will be using a number of SQL query's to validate settings needed for the new phone model 
+ - Lastly we will be combining all this information so we can send them via AXL.
+
+Note: axlService is Promised based, so we using a nested promise. We wait for the first promise to be fufilled before calling the nested one.
+*/
+
+// Set up new AXL service
+let service = new axlService(
+  "10.10.20.1",
+  "administrator",
+  "ciscopsdt",
+  "14.0"
+);
+
+(async () => {
+  
+  // Variable needed for script
+
+  // What model are we going to convert our phone into?
+  // You can get a list of models in CUCM with the SQL query: 'SELECT name from typemodel'
+  var convertPhoneType = "Cisco 8865"; // Another example: Cisco Dual Mode for Android
+  var phoneNameCopyingFrom = "CSFUSER001";
+  var phoneNameCopyingTo = "SEP112233445566"; // Another example: BOTWORDENJ
+  var newPhoneDescription = "Test phone added via AXL";
+
+  // We're going to use the getPhone operation to retrieve the settings from the phone we want to copy. First we'll get the JSON arguments needed for our AXL call.
+  var operation = "getPhone";
+  var tags = await service.getOperationTags(operation);
+  // Print out our operation tags
+  console.log(tags);
+  // Update the name of phone that we want to copy
+  tags.name = phoneNameCopyingFrom;
+
+  // Execute the AXL call. We set the true flag to clean the output (removes any blank or undefined settings)
+  var returnPhoneTags = await service.executeOperation(operation, tags, true);
+
+  // Now we're going to add a new phone based on the settings. We will updating a few new settings based on the model we will be converting to.
+  operation = "addPhone";
+  returnPhoneTags.phone.name = phoneNameCopyingTo; // New phone name that we will be using
+  returnPhoneTags.phone.description = newPhoneDescription; // Add a description
+  returnPhoneTags.phone.product = convertPhoneType; // Model product and type
+  returnPhoneTags.phone.model = convertPhoneType;
+
+  // Next we'll be pulling some of the supported tags for our new phone type. 
+  // This may not be all the settings you have to change when converting to a new model, but are the most common that I've run into.
+
+  // Phone button templates are device and protocol specific. 
+  // Let's get a list of the templates configured on our cluster that we can use.
+
+  var phoneTemplateSQL = `SELECT model.name AS device, pt.name AS template, p.buttonnum, tf.name AS feature, dp.name AS protocol
+  FROM phonetemplate AS pt, phonebutton AS p, typemodel AS model, typefeature AS tf, typedeviceprotocol AS dp
+  WHERE pt.pkid = p.fkphonetemplate AND pt.tkmodel = model.enum AND pt.tkdeviceprotocol = dp.enum AND p.tkfeature = tf.enum
+  AND model.name='${convertPhoneType}'`;
+
+  operation = "executeSQLQuery";
+  tags = await service.getOperationTags(operation);
+  tags.sql = phoneTemplateSQL;
+  var phoneTemplate = await service.executeOperation(operation, tags);
+
+  // This is for SIP phones.
+  // Let's get a list of Security Profiles configured on our cluster that we can use.
+
+  var securityProfileNameSQL = `SELECT model.name AS device, sp.name AS PROFILE
+  FROM securityprofile sp
+  LEFT OUTER JOIN typemodel AS model ON sp.tkmodel = model.enum
+  WHERE (sp.tksecuritypolicy = 4 OR sp.tksecuritypolicy = 99) AND model.name = '${convertPhoneType}'
+  ORDER BY model.name`;
+
+  operation = "executeSQLQuery";
+  tags = await service.getOperationTags(operation);
+  tags.sql = securityProfileNameSQL;
+  var securityProfileName = await service.executeOperation(operation, tags);
+
+  //   DND Option can only be set to non-Zero on devices that support the DND feature (in
+  //   ProductSupportsFeature table). For those devices that support the feature, only the Ringer Off (0) is
+  //   valid, unless a parameter is present in the PSF record. If a parameter value of 1 exists in PSF table, only
+  //   Call Reject is valid. If the param value is (2), all options including Use Common Profile (2) are valid.
+  //   Dual mode and remote destination profile only support the Call Reject option.
+
+  var dndOptionSQL = `select model.name,dp.name as protocol,p.param from typemodel as model,
+  typedeviceprotocol as dp,ProductSupportsFeature as p where p.tkmodel=model.enum and p.
+  tkSupportsFeature=(select enum from typesupportsfeature where name='Do Not Disturb')
+  and p.tkdeviceprotocol=dp.enum and model.tkclass=(select enum from typeclass where name=
+  'Phone')and model.name='${convertPhoneType}' order by model.name`;
+
+  operation = "executeSQLQuery";
+  tags = await service.getOperationTags(operation);
+  tags.sql = dndOptionSQL;
+  var dndOption = await service.executeOperation(operation, tags);
+
+  // Maximum Number of Calls and Busy Trigger (Less than or equal to Max. Calls) values depend on model type.
+  // We'll use an SQL query to figure out what values we need for our model type.
+  // 200:4:2 (Max calls per device:default max calls per line:default busy trigger).
+
+  var maxBusySQL = `SELECT NAME,param
+  FROM typemodel AS model, productsupportsfeature AS p
+  WHERE p.tkmodel = model.enum
+  AND p.tksupportsfeature = (SELECT enum FROM typesupportsfeature WHERE NAME = 'Multiple Call Display')
+  AND model.tkclass = (SELECT enum FROM typeclass WHERE  NAME = 'Phone') AND name='${convertPhoneType}'`;
+
+  operation = "executeSQLQuery";
+  tags = await service.getOperationTags(operation);
+  tags.sql = maxBusySQL;
+  var maxBusy = await service.executeOperation(operation, tags);
+
+  // Let's update our JSON with the necessary values from above. Note some will return multiple values. You may need to loop thru and find the one you want.
+
+  returnPhoneTags.phone.phoneTemplateName.value = phoneTemplate.row[0].template;
+  returnPhoneTags.phone.securityProfileName.value = securityProfileName.row[0].profile;
+
+  // Does this phone support DND? If so does it have a param value of 1
+  if(dndOption){
+    if(dndOption.row[0].param === '1'){
+      returnPhoneTags.phone.dndOption = "Call Reject";
+    }else{
+      returnPhoneTags.phone.dndOption = "Ringer Off";
+    }
+  }else{
+    delete returnPhoneTags.phone.dndOption;
+  }
+
+  // Let's split up our values we got back from CUCM. We'll be setting each line to the default for Max Number of Calls and minus one for our Busy Trigger.
+  var maxBusyArr = maxBusy.row[0].param.split(':');
+
+  // Loop thru all lines configured and update as needed.
+
+  returnPhoneTags.phone.lines.line.map((object) => {
+    object.maxNumCalls = maxBusyArr[2];
+    object.busyTrigger = maxBusyArr[2] - 1;
+  });
+
+  // Confidential Access Mode	is returned from CUCM via AXL as undefined if not set on the phone we are copying. 
+  // We either need to set it to '' or delete it complete. Since we're not using this feature, let's delete it from our JSON.
+
+  delete returnPhoneTags.phone.confidentialAccess;
+
+  // Print out updated JSON before we execute addPhone on CUCM via AXL
+
+  console.log(returnPhoneTags);
+
+  // Let's add our new phone. If successful we should get back a UUID of our new phone.
+  operation = "addPhone";
+  await service
+    .executeOperation(operation, returnPhoneTags)
+    .then((results) => {
+      console.log("New UUID",results);
+    })
+    .catch((error) => {
+      console.log(error);
+    });
+})();

package/examples/copy_phone/copyPhone.js

@@ -0,0 +1,39 @@
+const axlService = require("../../index");
+
+/*
+Example of how to copy a phone. This is similar to the Super Copy function in CUCM. Just an example of how to do it via AXL.
+
+Note: axlService is Promised based, so we using a nested promise. We wait for the first promise to be fufilled before calling the nested one.
+*/
+
+// Set up new AXL service
+let service = new axlService(
+  "10.10.20.1",
+  "administrator",
+  "ciscopsdt",
+  "14.0"
+);
+
+(async () => {
+  var operation = "getPhone";
+  var tags = await service.getOperationTags(operation);
+  tags.name = "CSFUSER001";
+
+  var returnPhoneTags = await service.executeOperation(operation, tags, true);
+
+  operation = "addPhone";
+  returnPhoneTags.phone.name = "CSFWORDENJ";
+  returnPhoneTags.phone.description = "Test phone added via AXL";
+  // Confidential Access Mode	is returned from CUCM via AXL as undefined if not set on the phone we are copying. 
+  // We either need to set it to '' or delete it complete. Since we're not using this feature, let's delete it from our JSON.
+  delete returnPhoneTags.phone.confidentialAccess;
+
+  await service
+    .executeOperation(operation, returnPhoneTags)
+    .then((results) => {
+      console.log(results);
+    })
+    .catch((error) => {
+      console.log(error);
+    });
+})();

package/examples/copy_sip_trunk/README.md

@@ -0,0 +1,3 @@
+# Copy SIP Trunk
+
+Use **cisco-axl** to copy a SIP trunk. Cisco doesn't provide a way to super copy a SIP trunk and add a new one. This script will pull the values for an existing trunk and then allow you to make a few updates and reinsert the new trunk.

package/examples/copy_sip_trunk/copySipTrunk.js

@@ -0,0 +1,54 @@
+const axlService = require("../../index");
+
+/*
+Example of how to copy a SIP Trunk. Cisco doesn't have a Super Copy option for this, but we can do it via AXL. 
+The new SIP trunk will need to have a new IP address for the destination address. 
+
+Note: axlService is Promised based, so we using a nested promise. We wait for the first promise to be fufilled before calling the nested one.
+*/
+
+// Set up new AXL service
+let service = new axlService(
+  "10.10.20.1",
+  "administrator",
+  "ciscopsdt",
+  "14.0"
+);
+
+(async () => {
+  // First let's get the tags needed for finding a SIP Trunk
+  var operation = "getSipTrunk";
+  var tags = await service.getOperationTags(operation);
+
+  // Let's update the returned JSON with the name of the trunk we are trying to copy
+  tags.name = "SIPTrunktoCUP";
+
+  // Make a call to AXL to get the information for the trunk we are copying.
+  // Note: we will be sending the clean flag to executeOperation. This will remove any keys in our return json that is empty, undefined or null.
+  var options = {
+    clean: true
+  };
+
+  var returnTrunk = await service.executeOperation(operation, tags, options);
+
+  // Update the JSON with our new values
+  operation = "addSipTrunk";
+  returnTrunk.sipTrunk.name = "SIPTrunktoCUP2";
+  returnTrunk.sipTrunk.description = "NEW SIP Trunk";
+  returnTrunk.sipTrunk.destinations.destination[0].addressIpv4 = '10.10.20.18';
+  returnTrunk.sipTrunk.destinations.destination[0].port = '5060';
+
+  // Confidential Access Mode	is returned from CUCM via AXL as undefined if not set on the phone we are copying. 
+  // We either need to set it to '' or delete it complete. Since we're not using this feature, let's delete it from our JSON.
+  delete returnTrunk.sipTrunk.confidentialAccess;
+
+  await service
+    .executeOperation(operation, returnTrunk)
+    .then((results) => {
+      console.log("addSipTrunk UUID", results);
+    })
+    .catch((error) => {
+      console.log(error);
+    });
+})();
+

package/examples/getTagsForOperation.js

@@ -0,0 +1,15 @@
+const axlService = require("../index");
+
+// Set up new AXL service
+let service = new axlService(
+  "10.10.20.1",
+  "administrator",
+  "ciscopsdt",
+  "14.0"
+);
+
+(async () => {
+  var operation = "addSipTrunk";
+  var tags = await service.getOperationTags(operation);
+  console.log(tags);
+})();

package/examples/sql/README.md

@@ -0,0 +1,7 @@
+# SQL Queries
+
+Use **cisco-axl** to save SQL queries and execute whenever needed. sqlQuery.js will read in an ".sql" file and run the query for you. Just export the results to a csv or use in another operation.
+
+The **fs.readFileSync** package will allow a more readable format to be read in and still able executed with the **executeSQLQuery** operation. This makes it easy to store useful queries and script them to run.
+
+I've included examples of some useful queries.

package/examples/sql/cfa.sql

@@ -0,0 +1,14 @@
+SELECT
+LIMIT 10 dnorpattern,
+      cfhrdn,
+      cfhrintdn,
+      cfbdestination,
+      cfbintdestination,
+      cfnadestination,
+      cfnaintdestination,
+      cfurdestination,
+      cfurintdestination,
+      devicefailuredn,
+      pffdestination,
+      pffintdestination
+FROM numplan

package/examples/sql/mask.sql

@@ -0,0 +1,7 @@
+SELECT
+LIMIT 10 dnorpattern,
+      calledpartytransformationmask,
+      callingpartytransformationmask,
+      callingpartyprefixdigits,
+      prefixdigitsout
+FROM numplan

package/examples/sql/max_busy.sql

@@ -0,0 +1,14 @@
+SELECT NAME,
+       param
+FROM typemodel AS model,
+     productsupportsfeature AS p
+WHERE p.tkmodel = model.enum
+  AND p.tksupportsfeature =
+    (SELECT enum
+     FROM typesupportsfeature
+     WHERE NAME = 'Multiple Call Display')
+  AND model.tkclass =
+    (SELECT enum
+     FROM typeclass
+     WHERE NAME = 'Phone')
+  AND name='Cisco Dual Mode for Android'

package/examples/sql/sqlQuery.js

@@ -0,0 +1,39 @@
+const axlService = require("../../index");
+var fs = require('fs');
+var path = require('path');
+
+/*
+Example of how to send SQL queries to CUCM via AXL. We can store our queries in ".sql" files, then we can read them in before executing.
+
+Note: axlService is Promised based, so we using a nested promise. We wait for the first promise to be fufilled before calling the nested one.
+*/
+
+// Set up new AXL service
+let service = new axlService(
+  "10.10.20.1",
+  "administrator",
+  "ciscopsdt",
+  "14.0"
+);
+
+(async () => {
+  // First we'll get the params needed to call executeSQLQuery
+  var operation = "executeSQLQuery";
+  var tags = await service.getOperationTags(operation);
+  console.log(tags);
+
+  // Next we'll read in our SQL file and update tags with the query
+  let sql = fs.readFileSync(path.join(__dirname, 'mask.sql'), "utf8");
+  tags.sql = sql;
+  console.log(tags);
+
+  // Lastly let's execute the query on server
+  await service
+    .executeOperation(operation, tags)
+    .then((results) => {
+      console.log(results);
+    })
+    .catch((error) => {
+      console.log(error);
+    });
+})();

package/examples/sql/unassignedDn.sql

@@ -0,0 +1,25 @@
+SELECT np.dnorpattern             AS NUMBER, 
+       np.description             AS DESCRIPTION, 
+       cfd.cfavoicemailenabled AS CALL_FORWARD_ALL_VOICEMAIL_ENABLED, 
+       cfd.cfadestination      AS CALL_FORWARD_ALL_DESTINATION, 
+       cfbvoicemailenabled     AS BUSY_VOICEMAIL_ENABLED, 
+       cfbdestination          AS BUSY_EXTERNAL_DESTINTATION, 
+       cfbintvoicemailenabled  AS BUSY_INTERNAL_VOICEMAIL_ENABLED, 
+       cfbintdestination       AS BUSY_INTERNAL_DESTINATION, 
+       cfnavoicemailenabled    AS NOANSWER_VOICEMAIL_ENABLED, 
+       cfnadestination         AS NO_ANSWERD_ESTINATION, 
+       cfnaintvoicemailenabled AS NO_ANSWER_INTERNAL_VOICEMAIL_ENABLED, 
+       cfnaintdestination      AS NO_ANSWER_INTERNAL_DESTINATION,
+       rpt.name                AS PARTITION 
+FROM   numplan np 
+       INNER JOIN typepatternusage tpu 
+               ON np.tkpatternusage = tpu.enum 
+       LEFT OUTER JOIN callforwarddynamic AS cfd 
+                    ON cfd.fknumplan = np.pkid 
+       LEFT OUTER JOIN devicenumplanmap dnmp 
+                    ON dnmp.fknumplan = np.pkid
+       LEFT OUTER JOIN routepartition rpt
+                    ON rpt.pkid = np.fkroutepartition 
+WHERE  tpu.NAME = 'Device' 
+       AND dnmp.pkid IS NULL 
+ORDER  BY dnorpattern ASC

package/examples/templates/README.md

@@ -0,0 +1,11 @@
+# Templates
+
+Using json-variables you can use JSON files as templates along with variables to automate AXL operations.
+
+## Update Phone and Line
+
+Every wanted to change an exsiting phone from one user to another user? This script will help you do that as well as updating all the display, line text labels, etc for the new user.
+
+## Add Phone and Update Line
+
+This script will add a new phone and line. Once finished it will go back and update the line. AXL doesn't allow setting alertingName, asciiAlertingName and description while adding a line via the addPhone operation. This would be similar to using BAT to add phones.

package/examples/templates/add_phone_update_line/addPhoneUpdateLine.js

@@ -0,0 +1,49 @@
+const { jVar } = require("json-variables");
+const axlService = require("../../../index");
+
+/*
+This script using json-variables (https://codsen.com/os/json-variables) to add a new phone from a template. 
+The AXL "addPhone" operation will either add an existing line or add a new one.
+We will be using the "updateLine" to follow behind and update a few of the fields that "addPhone" does not include.
+
+Note: axlService is Promised based, so we using a nested promise. We wait for the "addPhone" promise to be fufilled before calling "updateLine".
+*/
+
+// Set up new AXL service (DevNet sandbox credentials: https://devnetsandbox.cisco.com/)
+let service = new axlService(
+  "10.10.20.1",
+  "administrator",
+  "ciscopsdt",
+  "14.0"
+);
+
+// Read in the JSON templates
+var phoneTemplate = require("./phoneTemplate.json");
+var lineTemplate = require("./lineTemplate.json");
+
+(async () => {
+  // Use json-variables to update our values from the template values
+  const phoneArg = jVar(phoneTemplate);
+  const lineArg = jVar(lineTemplate);
+
+  // Call the first operation: "addPhone" with the jVar updated json
+  service
+    .executeOperation("addPhone", phoneArg)
+    .then((results) => {
+      // Print out the UUID for the successful "addPhone" call
+      console.log("addPhone UUID", results);
+      // Call the second operation: "update" with the jVar updated json
+      service
+        .executeOperation("updateLine", lineArg)
+        .then((results) => {
+          // Print out the UUID for the successful "updateLine" call
+          console.log("updateLine UUID", results);
+        })
+        .catch((error) => {
+          console.log(error);
+        });
+    })
+    .catch((error) => {
+      console.log(error);
+    });
+})();

package/examples/templates/add_phone_update_line/lineTemplate.json

@@ -0,0 +1,12 @@
+{
+   "pattern": "%%_extension_%%",
+   "routePartitionName": "",
+   "alertingName": "%%_firstName_%% %%_lastName_%%",
+   "asciiAlertingName": "%%_firstName_%% %%_lastName_%%",
+   "description": "%%_firstName_%% %%_lastName_%%",
+   "_data": {
+     "extension": "2001",
+     "firstName": "Tom",
+     "lastName": "Smith"
+   }
+ }

package/examples/templates/add_phone_update_line/phoneTemplate.json

@@ -0,0 +1,151 @@
+{
+    "phone":{
+       "name":"%%_deviceName_%%",
+       "description":"%%_lastName_%%, %%_firstName_%% Extension %%_extension_%%",
+       "product":"Cisco Unified Client Services Framework",
+       "model":"Cisco Unified Client Services Framework",
+       "class":"Phone",
+       "protocol":"SIP",
+       "protocolSide":"User",
+       "devicePoolName":{
+          "value":"Default"
+       },
+       "commonPhoneConfigName":{
+          "value":"Standard Common Phone Profile"
+       },
+       "networkLocation":"Use System Default",
+       "locationName":{
+          "value":"Hub_None"
+       },
+       "loadInformation":{
+          "attributes":{
+             "special":"false"
+          }
+       },
+       "versionStamp":"",
+       "traceFlag":"false",
+       "mlppIndicationStatus":"Off",
+       "preemption":"Disabled",
+       "useTrustedRelayPoint":"Default",
+       "retryVideoCallAsAudio":"true",
+       "securityProfileName":{
+          "value":"Cisco Unified Client Services Framework - UDP"
+       },
+       "sipProfileName":{
+          "value":"Standard SIP Profile"
+       },
+       "useDevicePoolCgpnTransformCss":"true",
+       "sendGeoLocation":"false",
+       "lines":{
+          "line":[
+             {
+                "index":"1",
+                "label":"%%_lastName_%% - %%_extension_%%",
+                "display":"%%_lastName_%%, %%_firstName_%%",
+                "dirn":{
+                   "pattern":"%%_extension_%%"
+                },
+                "ringSetting":"Ring",
+                "consecutiveRingSetting":"Use System Default",
+                "mwlPolicy":"Use System Policy",
+                "displayAscii":"%%_lastName_%%, %%_firstName_%%",
+                "maxNumCalls":"3",
+                "busyTrigger":"2",
+                "callInfoDisplay":{
+                   "callerName":"true",
+                   "callerNumber":"false",
+                   "redirectedNumber":"false",
+                   "dialedNumber":"true"
+                },
+                "recordingFlag":"Call Recording Disabled",
+                "audibleMwi":"Default",
+                "partitionUsage":"General",
+                "associatedEndusers":{
+                   "enduser":[
+                      {
+                         "userId":"%%_userid_%%"
+                      }
+                   ]
+                },
+                "missedCallLogging":"true",
+                "recordingMediaSource":"Gateway Preferred"
+             }
+          ]
+       },
+       "numberOfButtons":"1",
+       "phoneTemplateName":{
+          "value":"Standard Client Services Framework"
+       },
+       "ringSettingIdleBlfAudibleAlert":"Default",
+       "ringSettingBusyBlfAudibleAlert":"Default",
+       "enableExtensionMobility":"false",
+       "currentProfileName":{
+          
+       },
+       "currentConfig":{
+          "phoneTemplateName":{
+             "value":"Standard Client Services Framework"
+          },
+          "mlppIndicationStatus":"Off",
+          "preemption":"Disabled",
+          "ignorePresentationIndicators":"false",
+          "singleButtonBarge":"Default",
+          "joinAcrossLines":"Off",
+          "callInfoPrivacyStatus":"Default",
+          "dndRingSetting":"Disable",
+          "dndOption":"Ringer Off",
+          "alwaysUsePrimeLine":"Default",
+          "alwaysUsePrimeLineForVoiceMessage":"Default",
+          "emccCallingSearchSpaceName":{
+             
+          }
+       },
+       "singleButtonBarge":"Default",
+       "joinAcrossLines":"Off",
+       "builtInBridgeStatus":"Default",
+       "callInfoPrivacyStatus":"Default",
+       "hlogStatus":"On",
+       "ignorePresentationIndicators":"false",
+       "packetCaptureMode":"None",
+       "packetCaptureDuration":"0",
+       "allowCtiControlFlag":"true",
+       "presenceGroupName":{
+          "value":"Standard Presence group"
+       },
+       "unattendedPort":"false",
+       "requireDtmfReception":"false",
+       "rfc2833Disabled":"false",
+       "certificateOperation":"No Pending Operation",
+       "certificateStatus":"None",
+       "deviceMobilityMode":"Default",
+       "remoteDevice":"false",
+       "dndOption":"Ringer Off",
+       "dndRingSetting":"Disable",
+       "dndStatus":"false",
+       "isActive":"true",
+       "isDualMode":"true",
+       "phoneSuite":"Default",
+       "phoneServiceDisplay":"Default",
+       "isProtected":"false",
+       "mtpRequired":"false",
+       "mtpPreferedCodec":"711ulaw",
+       "outboundCallRollover":"No Rollover",
+       "hotlineDevice":"false",
+       "alwaysUsePrimeLine":"Default",
+       "alwaysUsePrimeLineForVoiceMessage":"Default",
+       "deviceTrustMode":"Not Trusted",
+       "AllowPresentationSharingUsingBfcp":"false",
+       "allowiXApplicableMedia":"false",
+       "useDevicePoolCgpnIngressDN":"true",
+       "enableCallRoutingToRdWhenNoneIsActive":"f",
+       "enableActivationID":"false",
+       "allowMraMode":"false"
+    },
+    "phone_data":{
+       "firstName":"Tom",
+       "lastName":"Smith",
+       "extension":"2001",
+       "userid":"user01",
+       "deviceName": "CSFSMITHT"
+    }
+ }

package/examples/templates/update_phone_update_line/lineTemplate.json

@@ -0,0 +1,12 @@
+{
+   "pattern": "%%_extension_%%",
+   "routePartitionName": "",
+   "alertingName": "%%_firstName_%% %%_lastName_%%",
+   "asciiAlertingName": "%%_firstName_%% %%_lastName_%%",
+   "description": "%%_firstName_%% %%_lastName_%%",
+   "_data": {
+     "extension": "",
+     "firstName": "",
+     "lastName": ""
+   }
+ }

package/examples/templates/update_phone_update_line/phoneTemplate.json

@@ -0,0 +1,31 @@
+{
+   "name":"%%_deviceName_%%",
+   "description":"%%_lastName_%%, %%_firstName_%% Extension %%_extension_%%",
+   "ownerUserName": "%%_userid_%%",
+   "lines":{
+      "line":[
+         {
+            "index":"1",
+            "dirn":{
+               "pattern":"%%_extension_%%"
+            },
+            "label":"%%_lastName_%% - %%_extension_%%",
+            "display":"%%_lastName_%%, %%_firstName_%%",
+            "displayAscii":"%%_lastName_%%, %%_firstName_%%",
+            "associatedEndusers":{
+               "enduser":[
+                  {
+                     "userId":"%%_userid_%%"
+                  }
+               ]
+            }
+         }]
+   },
+   "_data": {
+      "deviceName":"",
+      "extension": "",
+      "firstName": "",
+      "lastName": "",
+      "userid":""
+    }
+}

package/examples/templates/update_phone_update_line/updatePhoneUpdateLine.js

@@ -0,0 +1,106 @@
+const { jVar } = require("json-variables");
+const axlService = require("../../../index");
+
+/*
+Every wanted to change an exsiting phone from one user to another user? This script will help you do that as well as updating all the display,
+line text labels, etc for the new user.
+
+This script using json-variables (https://codsen.com/os/json-variables) to update a phone from a template.
+
+We will be updating a phone from an existing user to a new user. This is a common MACD change for help desks.
+ - First we will use the "getUser" operation to return some values for the user we will be using to replace the existing user.
+ - Next we will take those values and update some of templates values.
+ - Next we will use jVar to merge those values for us so we can send them via AXL.
+
+Note: axlService is Promised based, so we using a nested promise. We wait for the first promise to be fufilled before calling the nested one.
+*/
+
+// Set up new AXL service (DevNet sandbox credentials: https://devnetsandbox.cisco.com/)
+let service = new axlService(
+  "10.10.20.1",
+  "administrator",
+  "ciscopsdt",
+  "14.0"
+);
+
+// Read in the JSON templates
+var phoneTemplate = require("./phoneTemplate.json");
+var lineTemplate = require("./lineTemplate.json");
+
+// Set up the tags for our "getUser" call. We are interested in getting the first and last name to use in our template later.
+
+var deviceToUpdate = {
+  deviceName: "CSFUSER005",
+  extension: "1005"
+};
+
+// User to update phone value to
+
+var getUserJSON = {
+  userid: "user03",
+  returnedTags: {
+    firstName: "",
+    lastName: "",
+  },
+};
+
+(async () => {
+  // Call getUser operation and store in the userInfo variable
+  var userInfo = await service
+    .executeOperation("getUser", getUserJSON)
+    .catch((error) => {
+      console.log(error);
+    });
+
+  // Let's update our variable data with the information that we got back from our AXL call
+  phoneTemplate._data.firstName = userInfo.user.firstName;
+  phoneTemplate._data.lastName = userInfo.user.lastName;
+  phoneTemplate._data.userid = getUserJSON.userid;
+  phoneTemplate._data.deviceName = deviceToUpdate.deviceName;
+  phoneTemplate._data.extension = deviceToUpdate.extension;
+  lineTemplate._data.firstName = userInfo.user.firstName;
+  lineTemplate._data.lastName = userInfo.user.lastName;
+  lineTemplate._data.extension = deviceToUpdate.extension;
+
+  // Use json-variables to update our values from the template values
+  const phoneTags = jVar(phoneTemplate);
+  const lineTags = jVar(lineTemplate);
+
+  // Call the first operation: "updatePhone" with the jVar updated json
+  service
+    .executeOperation("updatePhone", phoneTags)
+    .then((results) => {
+      // Print out the UUID for the successful "updatePhone" call
+      console.log("updatePhone UUID", results);
+      // Call the second operation: "updateLine" with the jVar updated json
+      service
+        .executeOperation("updateLine", lineTags)
+        .then((results) => {
+          // Print out the UUID for the successful "updateLine" call
+          console.log("updateLine UUID", results);
+          // Lastly let's update our user with the controlled device and set the primary ex
+          var updateUserJSON = {
+            userid: getUserJSON.userid,
+            associatedDevices: {
+              device: [deviceToUpdate.deviceName],
+            },
+            primaryExtension: { pattern: deviceToUpdate.extension, routePartitionName: '' }
+          };
+          service
+            .executeOperation("updateUser", updateUserJSON)
+            .then((results) => {
+              // Print out the UUID for the successful "updateUser" call
+              console.log("updateUser UUID", results);
+            })
+            .catch((error) => {
+              console.log(error);
+            });
+        })
+        .catch((error) => {
+          console.log(error);
+        });
+    })
+    .catch((error) => {
+      console.log(error);
+    });
+})();

package/index.js

@@ -1,7 +1,9 @@
-var soap = require("strong-soap").soap;
-var XMLHandler = soap.XMLHandler;
-var xmlHandler = new XMLHandler();
-var WSDL = soap.WSDL;
+const soap = require("strong-soap").soap;
+const WSDL = soap.WSDL;
+const wsdlOptions = {
+  attributesKey: "attributes",
+  valueKey: "value",
+};
 
 /**
  * Cisco axlService Service
@@ -20,10 +22,10 @@ class axlService {
       version: version,
     };
   }
-  returnMethods(filter) {
+  returnOperations(filter) {
     var options = this._OPTIONS;
     return new Promise((resolve, reject) => {
-      soap.createClient(options.url, {}, function (err, client) {
+      soap.createClient(options.url, wsdlOptions, function (err, client) {
         client.setSecurity(
           new soap.BasicAuthSecurity(options.username, options.password)
         );
@@ -59,7 +61,7 @@ class axlService {
       });
     });
   }
-  getMethodParams(method) {
+  getOperationTags(operation) {
     var options = this._OPTIONS;
     return new Promise((resolve, reject) => {
       WSDL.open(
@@ -69,10 +71,10 @@ class axlService {
           if (err) {
             reject(err);
           }
-          var operation =
-            wsdl.definitions.bindings.AXLAPIBinding.operations[method];
-          var operName = operation.$name;
-          var operationDesc = operation.describe(wsdl);
+          var operationDef =
+            wsdl.definitions.bindings.AXLAPIBinding.operations[operation];
+          var operName = operationDef.$name;
+          var operationDesc = operationDef.describe(wsdl);
           var envelopeBody = {};
           operationDesc.input.body.elements.map((object) => {
             var operMatch = new RegExp(object.qname.name, "i");
@@ -95,13 +97,17 @@ class axlService {
       );
     });
   }
-  executeMethod(method, params) {
+  executeOperation(operation, tags, opts) {
     var options = this._OPTIONS;
-    var cleanParams = Object.fromEntries(
-      Object.entries(params).filter(([_, v]) => v != "")
-    );
+
+    var clean = opts?.clean ? opts.clean : false;
+    var dataContainerIdentifierTails = opts?.dataContainerIdentifierTails ? opts.dataContainerIdentifierTails : '_data';
+     
+    // Let's remove empty top level strings. Also filter out json-variables
+    Object.keys(tags).forEach((k) => (tags[k] == '' || k.includes(dataContainerIdentifierTails)) && delete tags[k]);
+
     return new Promise((resolve, reject) => {
-      soap.createClient(options.url, {}, function (err, client) {
+      soap.createClient(options.url, wsdlOptions, function (err, client) {
         client.setSecurity(
           new soap.BasicAuthSecurity(options.username, options.password)
         );
@@ -111,22 +117,27 @@ class axlService {
           reject(err.root.Envelope.Body.Fault);
         });
 
-        var axlFunc = client.AXLAPIService.AXLPort[method];
+        var axlFunc = client.AXLAPIService.AXLPort[operation];
 
         axlFunc(
-          cleanParams,
+          tags,
           function (
             err,
             result,
-            envelope,
-            rawResponse,
-            soapHeader,
-            rawRequest
           ) {
             if (err) {
               reject(err);
             }
-            resolve(result.return);
+            if (result?.hasOwnProperty("return")) {
+              var output = result.return;
+              if (clean) {
+                output = cleanObj(result.return);
+              }
+              resolve(output);
+
+            } else {
+              reject('No return results');
+            }
           }
         );
       });
@@ -154,4 +165,24 @@ const nestedObj = (object) => {
   }
 };
 
+const cleanObj = (object) => {
+  Object.entries(object).forEach(([k, v]) => {
+    if (v && typeof v === "object") {
+      cleanObj(v);
+    }
+    if (
+      (v && typeof v === "object" && !Object.keys(v).length) ||
+      v === null ||
+      v === undefined
+    ) {
+      if (Array.isArray(object)) {
+        object.splice(k, 1);
+      } else {
+        delete object[k];
+      }
+    }
+  });
+  return object;
+};
+
 module.exports = axlService;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cisco-axl",
-  "version": "1.0.1",
-  "description": "Package to make Cisco AXL easier",
+  "version": "1.1.1",
+  "description": "A library to make Cisco AXL a lot easier",
   "main": "index.js",
   "scripts": {
     "test": "NODE_OPTIONS=--experimental-vm-modules NODE_NO_WARNINGS=1 NODE_TLS_REJECT_UNAUTHORIZED=0 node ./test/tests.js"
@@ -21,6 +21,7 @@
     "strong-soap": "^3.4.0"
   },
   "devDependencies": {
+    "json-variables": "^10.1.0",
     "node-emoji": "^1.11.0"
   }
 }

package/test/tests.js

@@ -20,70 +20,76 @@ var computer = emoji.get("computer");
 var finished = emoji.get("raised_hand");
 
 (async () => {
-  console.log(`${spy} Let's first get a list of all the methods.`);
-  var methodArr = await service.returnMethods();
-  console.log(computer,methodArr);
+  console.log(`${spy} Let's first get a list of all the operations.`);
+  var operationArr = await service.returnOperations();
+  console.log(computer, "Found", operationArr.length,"operations.");
+  const random = Math.floor(Math.random() * operationArr.length);
+  console.log(`${spy} Let's pick out out at random operation: '`,operationArr[random],"'");
   console.log(
-    `${next}  Now let's get a list of all the methods that include the word 'partition'.`
+    `${next}  Now let's get a list of all the operations that include the word 'partition'.`
   );
-  var methodFilterArr = await service.returnMethods("partition");
-  console.log(computer,methodFilterArr);
+  var operationFilteredArr = await service.returnOperations("partition");
+  console.log(computer, operationFilteredArr);
 
   console.log(
-    `${cat} Great. Let's add a new route partition via 'addRoutePartition'.`
+    `${cat} Great. Let's add a new route partition via 'addRoutePartition' operation.`
   );
 
-  var method = "addRoutePartition";
+  var operation = "addRoutePartition";
 
   console.log(
-    `${next}  We'll need to get what params to pass to the SOAP client first.`
+    `${next}  We'll need to get what tags to pass to the SOAP client first.`
   );
-  var params = await service.getMethodParams(method);
-  console.log(computer,params);
-  console.log(`${sparkles} Awesome, let's update the name and description fields.`);
-  params.routePartition.name = "INTERNAL-PT";
-  params.routePartition.description = "Internal directory numbers";
-  console.log(computer,params);
+  var tags = await service.getOperationTags(operation);
+  console.log(computer, tags);
+  console.log(
+    `${sparkles} Magnificent, let's update the name and description fields.`
+  );
+  tags.routePartition.name = "INTERNAL-PT";
+  tags.routePartition.description = "Internal directory numbers";
+  console.log(computer, tags);
   console.log(
     `${next}  Now we will attempt to add the new partition. Function should return an UUID to represent the new partition.`
   );
   await service
-    .executeMethod(method, params)
+    .executeOperation(operation, tags)
     .then(async (results) => {
-      console.log(computer,results);
+      console.log(computer, results);
       console.log(
-        `${cat} Great let's get a list of all the partitions on our cluster now. First we'll get the params needed for this call.`
+        `${cat} Awesome, let's get a list of all the partitions on our cluster now. First we'll get the tags needed for this call.`
       );
 
-      method = "listRoutePartition";
-      params = await service.getMethodParams(method);
-      console.log(computer,params);
+      operation = "listRoutePartition";
+      tags = await service.getOperationTags(operation);
+      console.log(computer, tags);
 
       console.log(
         `${spy} We want to list all partitions, so we'll be searching for a wildcard (%%) in the name and description fields.`
       );
-      params.searchCriteria.name = "%%";
-      params.searchCriteria.description = "%%";
-      console.log(computer,params);
+      tags.searchCriteria.name = "%%";
+      tags.searchCriteria.description = "%%";
+      console.log(computer, tags);
       console.log(
-        `${sparkles} Great, now that we've updated our params, we'll send the AXL request via SOAP.`
+        `${sparkles} Astounding, now that we've updated our tags, we'll send the AXL request via SOAP.`
       );
 
       await service
-        .executeMethod(method, params)
+        .executeOperation(operation, tags)
         .then((results) => {
-          console.log(`${list}  Here are a list of all the partitions on our cluster:`);
+          console.log(
+            `${list}  Here are a list of all the partitions on our cluster:`
+          );
           results.routePartition.map((str) => {
             var outString = `${check} ${str.name}`;
             console.log(outString);
           });
         })
         .catch((error) => {
-          console.log(skull,error);
+          console.log(skull, error);
         });
     })
     .catch((error) => {
-      console.log(skull,"Adding a new partition failed", error);
+      console.log(skull, "Adding a new partition failed", error);
     });
-  console.log(finished,"Test all finished. Thanks!");
+  console.log(finished, "Test all finished. Thanks!");
 })();

package/test/wsdl.js

@@ -0,0 +1,38 @@
+var soap = require("strong-soap").soap;
+var WSDL = soap.WSDL;
+
+var method = "addPhone";
+
+const wsdlOptions = {
+  attributesKey: 'attributes',
+  valueKey: 'value',
+  xmlKey: 'xml',
+};
+
+WSDL.open(`./schema/current/AXLAPI.wsdl`, wsdlOptions, function (err, wsdl) {
+  if (err) {
+    reject(err);
+  }
+
+  var operation = wsdl.definitions.bindings.AXLAPIBinding.operations[method];
+  var schemas = wsdl.definitions;
+  var schema = wsdl.definitions.schemas['http://www.cisco.com/AXL/API/14.0'];
+  var operName = operation.$name;
+  var part = wsdl.definitions.messages.AXLError.parts;
+  var complexType = schema.complexTypes[method];
+  var operationDesc = operation.describe(wsdl);
+  var requestElements = operationDesc.input.body.elements[0].elements;
+
+  operationDesc.input.body.elements.map((object) => {
+    var operMatch = new RegExp(object.qname.name, "i");
+    if (operName.match(operMatch)) {
+      nestedObj(object);
+    }
+  });
+});
+
+const nestedObj = (object) => {
+  object.elements.map((object) => {
+    console.log(object.qname.name);
+  });
+};