Provision Phones Nightmare

Cross Cluster Real-Time Monitor

Here is something you might enjoy, it is a product description of our Cross Cluster Real-Time Monitor.

Think of it as Call Manager Real-Time Monitor for all the clusters in the enterprise.

How Do I Test My Provisioning Engine?

Ah! So, you have a brand new provisioning engine and you want to know how to test it. Well, that's really simple. You have two choices, first you can just terminate the Apache Tomcat UCDT service that is running and then relaunch it in a command mode window. Or, you can just leave it as is and use the system logs within UCDT to debug it.

First, let's talk about Log4J.

The system already has Log4J installed, so, you can just tag along and use the logging files to write your debugging data.

In case you have never used Log4J, you can simply add these few lines of code to make it work:

First, for any class you have created add this line just after the "public class....." line:


private static Logger logger = Logger.getLogger(<theClassNameOfTheClassIAmInsideOf>.class);


Now, to use Log4J you only need to sprinkle these kinds of lines about in strategic places:


logger.info("Entering method executeTemplate for LDAP there is no Values data.");


Perfect, now you can basically write debugging messages to the UCSPT-CE.log file that is located in:

C:\Program Files\Cisco Systems\UCDT\Tomcat\webapps\UCSPT-CE\logs 

Be liberal in writing to the file while in test/debug mode as it will only help you to find out where you are in the code.

The best way to debug, hands down, is to kill the Apache Tomcat UCDT service and run it in a command mode window. This will allow you to avoid Log4J and just do a ton of System.out.println's where ever you need so you can determine what is going on. And, one of the great side benefits is that you can just kill the CMD mode window to kill UCDT - waiting for the Apache Tomcat UCDT service to restart can be a little bit like watching grass grow on a hot summer day (I mean, it can be slow).

OK, I wont tell you how to stop a service, other than to say you will do it from your "Start Task Manager" function. Click on the Services tab and then click the Services button on that page. From there you can find it. If you are running something less than Windows 7 you will just have to google "services.msc", or just run it on your PC.

Once killed and stopped, you might want to change its properties so that its "Startup Type" is "Manual", you will need to launch UCDT manually if you do this.

You will need two things, first a setup.bat file and know where to put it.

The setup.bat file is a simple little bat file that will set up the classpath and path. So, within the folder:

C:\Program Files\Cisco Systems\UCDT\Tomcat\bin

create a new file called setup.bat and within that file paste these lines:

SET JAVA_HOME=C:\Program Files\Cisco Systems\UCDT\Tomcat\
SET JRE_HOME=C:\Program Files\Cisco Systems\UCDT\Tomcat\jre
SET PATH=%JAVA_HOME%;%PATH%;%JAVA_HOME%\bin;%PATH%;


It is the typical stuff you need to set, look in C:\Program Files\Cisco Systems\ and you will find all the folders deployed there.

From this point you can just add System.out.println() statements througout your code and watch the console to view any messages that will help you do identify where you are in the code or what is causing whatever problem your are working through.

Whether you want to use Log4J (highly recommend once you are in production mode) or you will want to use System.out.println, the choice is yours.

Good luck with it!

UCDT Provisioning Engines - The secret to integration

Today, UCDT will allow a programmer to build their own provisioning engine. The engine, as noted in a previous post will need to be written in Java and start with defining a class that implements the GenericProvisionInterface class. That class, once linked into the provision.xml file will allow the user of UCDT to build templates and execute them against the target server.

Now, what was missing from the previous post was a detailed discussion about what exactly needed to be setup within the UCDT database to allow all of this to work. As a note, the upcoming UCDT 9.3 will serve to make all of what you will read here mostly obsolete. However, to fully understand the inner workings of UCDT it is best that a programmer understand these things about provisioning engine integration.

First, do recall that there is a concept of UCProduct and UCProductVersion. These are found both in the provision.xml file and in the UCSYSTEM database table. Within the provision.xml file they are found in any of the lines:

<provision provisionProduct="ThirdParty" provisionProductVersion="LDAP" provisionClass="ldap.LDAPProvision"/>



All of the provisioning engines you create must be defined within "ThirdParty" as the Product with the ProductVersion being something meaningful to you and your intended audience. For example, above is how an LDAP provisioning engine might appear. And, the last item there is of course the name of the java class that extends the class you created to implement GenericProvisionInterface.

Within UCSYSTEM you will see that there are three columns, a unique ID, the UCPRODUCT and the VERSION. The unique ID should just be the next sequential number from a SELECT MAX on that tables SYSTEM_ID column. The UCPRODUCT must be the "ThirdParty", exactly as you have it in your provision.xml's provisionProduct field. And, the VERSION must be the same value that you have in your provision.xml's provisionProductVersion field.

The provision.xml snippet and the screen capture above align with each other as you can see the provision.xml entry matched on like 26 of the UCSYSTEM table.

OK, That is the first part of getting a provisioning engine working. The next part is just as easy, but, it might seem hard at first glance. Let's first break it down by the work steps, then let's go into each one individually, then let's recap those items:

In order to make use of a provisioning engine, you must create templates that use them, a script that organizes those templates and a superscript that coordinates multiple scripts. Do recall that a template is the lowest level in the hierarchy of the system. The template might generate hunderds or thousands of commands to a UC Server, or it might only generate one or two commands, or maybe no commands at all. The next level up is the Script. The Script will control the execute order of several templates. And, like a script running multiple templates, a SuperScript will coordinate the execution of multiple Scripts.

So, our first task is that we have to create a SuperScript, a Script and any Templates that will be running.

Next, we need to associate a server device to the enterprise for our target server type.

Finally, we need to added data for our enterprise/branch.

At this point we can run provisioning. And, please keep in mind that the term 'provisioning' is a bit missleading here as the actual function of the provisioning engine might have absolutely nothing to do with provisioning. For example, we might be scraping all the data out of LDAP to be transferred to a 3rd party database. Or, we might be executing a process to perform tests against deployment phones - ensuring that they are operational.

Creating the SuperScript is easy, we simply need to go to the Template Builder's user interface and select SuperScript to add in the SuperScript.

Adding the templates is easy, too, we can use the Template Builder UI for that.

Adding the Script is the tricky part (only until UCDT 9.3 is delivered), and to do that is not too bad. Here's what you need to do.

Within the database locate the SCRIPT table. You will find a table that has 6 columns: SCRIPT_ID, AUTHOR, CREATED_DATE, FK_SYSTEM, SCRIPT_VERSION and SCRIPT_NAME.

You will make one or more entries in this table to define your script(s). SCRIPT_ID should be set to the MAX(SCRIPT_ID) + 1 so that it is the next sequential value for the existing values in that table. 

AUTHOR can just be set to '1', for Superadmin, unless you want to tie it to another specific user ID.

CREATED_DATE can be something easy like "2013-11-01 08:00:00", but you can feel free to set it to any date and time you desire.

FK_SYSTEM will be the SYSTEM_ID from the UCSYSTEM table for the provisioning engine server you want this to apply against. Be aware that the SERVERS table will define actual servers, the UCSYSTEM table defines a class of servers, like LDAP servers.

SCRIPT_VERSION must match the version you supplied in the provision.xml file and the version identified in the UCSYSTEM table.

SCRIPT_NAME is the name you would like to use so that you and your users recognize it.

Here is a sample of my Script table, notice that my LDAP's entry is tied to FK_SYSTEM '26' and that lines up nicely with the example up above.

Now, with that built we can use the UCDT user inteface to add templates to it and to add it to a SuperScript.

Here is an example SuperScript that uses my LDAP class:

In the example above I created a SuperScript titled ProvisionLDAP and within that I added two scripts, the first script is titled "AddNewEmployee" and the other is "Customer.EnableForJabber". The "AddNewEmployee" script is simply named and is only a script that contains one template to read data from LDAP. The second template "Customer.EnableForJabber" is a script that also only contains one template and that template will connect to the appropriate CUCM and update the enduser appropriately.

Here is that template for reading data from LDAP:

You might look at that template and wonder where all the specific's are for reading LDAP. Well, all the specifics are within the provision engine I wrote. So, the way it works is that UCDT will pass to my provision engine the LDAP server credentials and basedn so that the Java code used can access the AD data. The "Values" you see in the template above will be used as a filter to read data from LDAP and then pass that back for use in a latter template.

Keep in mind that in the template you see "$VAR_USERNAME_VAR" and also "$VAR_ENABLEMENT_VAR", those are variables that will be set within the UCDT datapool prior to actually kicking the SuperScript containing this template off for execution.

Now, One final item to keep in mind is a table that maps templates to their respective script owner, and yes, a template can belong to one and only one script. However, a script may belong to many SuperScripts (in case you were wondering). The table that contains the mapping of templates to scripts is the TEMPLATE table itself. Here are the columns within that table:

      template_id numeric(10,0) NOT NULL,

      name character varying(150) NOT NULL,

      description character varying(150) NOT NULL,

      pos_in_script numeric(10,0) NOT NULL,

      body text NOT NULL,

      fk_script numeric(10,0) NOT NULL,

      include_in_xls numeric(10,0) DEFAULT NULL::numeric,

      reference_template numeric(10,0) DEFAULT NULL::numeric,

      fk_template_type numeric(10,0) DEFAULT NULL::numeric,

      dynamic_templating numeric(10,0) DEFAULT (0)::numeric,

      tagged_templates text,

      axis numeric(10,0) NOT NULL DEFAULT (0)::numeric,

The two columns we care about here are the FK_SCRIPT column and the POS_IN_SCRIPT. The FK_SCRIPT must be the SCRIPT_ID from the SCRIPT table for our script and the POS_IN_SCRIPT is any numeric value. The numeric value will be sorted ascending to provide the proper order of execution of the templates within the script.

This entire process is important to understand, so, it is good that you have read this far. But, when UCDT 9.3 is released you will not need to specifically set the FK_SCRIPT and POS_IN_SCRIPT, nor will you have to insert rows, manually, into the SCRIPT table. Personally, I cannot wait until this is released!

Now that you have setup these tables you are ready to provision, or, rather, you are ready to test your provision engine code :)

Putting it all together, now.

You already wrote your provision engine code, and now you want to test it. So, you need to stop tomcat and deploy your new provision code to:

 C:\Program Files\Cisco Systems\UCDT\Tomcat\webapps\UCSPT-CE\WEB-INF\classes

You need to update provision.xml so that your server type can be provisioned with the code you deployed.

You need to update UCSYSTEM to add a single entry for this new provision engine under the product heading of "ThirdParty".

You need to manually update the database to add an entry to the SCRIPT table and you need to use the UCDT Template Builder UI to add a SuperScript to include this new Script and you need to use the Template Builder UI to create one or more templates to include in the Script. Use the database editor PGAdminIII to manually alter the TEMPLATE table data to move your templates in the proper order if they need to be reordered.

Now, with all this set you are in operations mode. You can create a branch with data, make sure you assigned a server to your branch (ThirdParty only pre-UCDT 9.3) and then you can go to the provision page to test, test, test.

Well, I hope this helps you. In my next post I will discuss testing of your provision engine code.

Cheers!



Creating a new SQLServer 2012 Provisioning Engine

After getting the Microsoft SQLServer 2012 installed I was able to turn my attention to the code to integrate to UCDT.

The first step is to get your IDE up and running and create a new project to build the engine you want.

For me, I created a Java structure to hold a class you need to start with, and then a package to hold my code.

Now, be sure to keep track of any Jar's you need to get your product working because you will need to drop them into the UCDT WebApps Lib folder in order for it to work.

Ok, so the first thing to know is that there is an Inteface class you need to use and adhere to: GenericProvisionInterface.class.  There is a Jar file in the lib path of UCDT and you can get it from there, any system will allow you to open a Jar file and pull the files out, but I am including the interface definition here so we can talk about it:

package com.cisco.ucspt;

public interface GenericProvisionInterface {

public boolean setupConnection(String hostIP, 

                                       String portNumber, 

                                       String userId,

                                       String password, 

                                       String dbName,

                                       String version);

public boolean releaseConnection();

public String provision(String template);

}

There are three public class you need to design. First, setupConnection(); Second, releaseConnection(); and third provision().

The method setupConnection, as you can see, has all the data being passed in dealing with connection information. You might not need all of these, but they are there for your use. The origin of this information is found within the UCDT application on the Enterprise/Application menu item:

Notice that there is a tab titled "Third Party", this is where you will define all your server information. Also, note the column headers for the data, left to right you have Enterprise Name, Server Name, IP Address, User Name, Port, Version, Database Name, Throttle Speed and Test Status. We drill into each of these later, but, for now just know that you need to define the Server Name, the IP and Port if necessary and you will need to supply the User ID and Password. Also, notice that Test Status reports that no connectivity test is available, that is because this is a third party engine and not a native engine to UCDT. If we really like your OEM engine we might integrate it into the product thereby making it native.

Now, writing the code is a simple matter of creating an abstract class that will implement GenericProvisionInterface. And, of course, you can create any support class you might need to actually create your OEM solution.

My recommendation is that your package should be at the high level of WebApps/classes, since that is where all the other provisioning classes are stored.

So, just two more things to update and you are ready to start testing your code.

First, you need to update the provision.xml file, and that is located in WEV-INF/provision. Here is the contents of that file along with an edit that I made to support my MS SQLServer entry:

Line 9 contains the entry for the MS SQL Server entry that I added. The important thing to note here is that the provisionProduct field must be "ThirdParty"  and the provisionProductVersion field must match the database table entry for this server type. Finally, the provisionClass must be the name of the class that contains your code. 

The database table that needs to be updated is the ucsystems table, within that table you need to add an entry must also have a ucproduct value of "ThirdParty" and the version you add must match the provisionProductVersion added to the provisionxml file.

Ok, that is all you need to integrate, next we will talk about testing.

UCDT's Plug and Play Provisioning Engine - MS SQLServer 2012 Setup

I thought I would spend some time to work with the UCDT provisioning engine's plug-n-play architecture. I designed this a couple of years ago with another developer and the development team implemented it. So, it is really long over-due to have a look under the covers.


What I found is that it is that our design was spot-on! It is extremely easy to write OEM code and plug it into UCDT although I do have to perform a couple minor manual steps to make it work properly. That's not a problem because I am sure there will be future changes made by the development team so that it will be a smooth, 100% effortless process to plug new code into the system.


For my first OEM UCDT engine, I brushed off some old code that I had laying around for provisioning to a MSSQL Server database. I went ahead and installed SQLServer 2012 Express on my PC and set it up so that I could access it from remote application. In hind-sight this was easy, but, finding everything that had to be turned on was a bit of a pain in the backside.

First, I had to make sure the proper services were running, the SQL Server and SQL Server Browser. After installed they were set to 'Disabled', I only had to right mouse-click on them to set them to 'Automatic':

Next, I had to turn on Named Pipes and TCP/IP. I found that this had to be set up in the SQL Server Configuration Manager:

After I did that (and don't forget you have to restart the SQL Service). I had to set the TCP Port. For me, I just set all of these "TCP Port" entries to 1433, but, there is an entry at the bottom titled "IP All" which I assume means I can just set it once there and move on. I had been struggling to get this to work for so long I didn't want to leave anything to chance so I set them all.

Now, with that set I could build the MSSQL 2012 Provision Engine Code, this was simply a matter of writing code that would take a template body and then process it. I will share that code shortly, but, for now that is all I will update in this post.