Cisco Unified Communications Manager Management Agent

One of our core competency in identity and access management space is implementation of solutions based on Forefront Identity Manager platform. In the course of implementing several of such projects we have developed products and IP assets. Parts of these assets we are offering either as community asset (check our GitHub profile) or products available from Predica.

(cc) Narisa

Judging by number of inquiries we are getting through our web page one of most popular element from our offering is Cisco Unified Communication Manager management agent. Our development lead – Maciej, took some time to provide a bit of insight on this MA. Enjoy …

As you have, or have not, already noticed Predica provides an interface to integrate Cisco Unified Communications Manager with FIM. This interface is of course dedicated Management Agent that can “talk” to CUCM AXL web services providing FIM with native connectivity interface to CUCM. Number of questions we get on the topic might be related to the fact that at this moment Predica is the only company offering such solution (see Google search result ). To help to understand our offering to those who looks for it we’ve decided to share our product in a greater depth on this blog.

CUCM instance data

This post is intended to be a small demo of our MA’s capabilities. Let’s start by introducing the data that will be used. First, let’s have a look at the users defined in our CUCM instance:

As you can see, we only have 3 users in the system (of course CUCM will usually have many more of them, probably several dozens thousand users, but this will suffice for our purposes).

Users in CUCM can be “connected” to phone numbers, which in most cases is what we are interesting to get from, in many ways. We support all of them (more on this later), but this scenario assumes that “phone lines” are associated with users by “Device profiles”. Here is a device profile associated with users “GCH060”:

It has two lines (“phone numbers”): 11 and 12.

Our MA is able to handle three types of CUCM objects for now: Users (called “End users” in CUCM), Phones (called “Devices” in CUCM) and Hunt Lists. Let’s see how it works in practice.

Creating Predica CUCM MA

First we need to create a new MA using FIM Synchronization Service Manager.

After starting “Create Management Agent” wizard I selected “Extensible Connectivity 2.0” as MA type. I also gave it a descriptive name so that later I know what I am using.

Note: This MA supports both ways to operate in FIM – ECMA 1.0 and ECMA 2.0. This demo uses 2.0 version, because 1.0 will become obsolete in the future.

Next I selected our dll that contains the MA: “Predica.FimExtensions.CCM.dll”. Naturally, I needed to copy it first to FIM extensions directory: “C:Program FilesMicrosoft Forefront Identity Manager2010Synchronization ServiceExtensions”. After selecting the dll I needed to press “Refresh interfaces” – it allows the tool to scan our assembly and verify that it in fact contains a correct MA definition:

Next screens contain configuration entries for our MA. I left all of them blank.

We provide two ways of configuring the agent. One way is to fill all the fields in Sync Manager. Another way is through a configuration file. I choose to follow this approach because it’s easier to change an XML file than to click through UI of Sync Manager. More on configuration file – later in this post.

In “Select Object Types” screen I choose to handle only User object type. It is easier to operate on a single type when presenting a simple demonstration.

I choose to use all user’s attributes.

Configuring a user Anchor is necessary – I use “ID” attribute which contains a GUID generated by CUCM.

We do not want CUCM to create new users in Metaverse, we only want to join users that are already present. So we configure a single Join rule and no Projection rules. UserId attribute needs to be equal to accountName in Metaverse in order to map CUCM users to users already handled by FIM.

For the purposes of this demo we will only define two Export attribute flows. First and Last Names, when modified through FIM portal, will be sent to CUCM, just to show that exporting data from FIM to CUCM is also supported:

And it’s done – our CUCM MA is almost ready to communicate with Cisco Call Manager.

MA configuration

As I mentioned before, we support two ways of configuring our MA. You can either fill in the fields in Sync Manager or create a simple XML file. You can also split the configuration using both approaches – values from Sync Manager always take precedence over the ones defined in config file.

To use configuration file, you first need to modify the sync engine config: “C:Program FilesMicrosoft Forefront Identity Manager2010Synchronization Servicedllhost.exe.config”.

Open it and add this entry in “configSections” section:

[sourcecode language=”xml”]
<section name="ccmSettings" type="System.Configuration.AppSettingsSection, System.Configuration, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" restartonexternalchanges="false" requirepermission="false"></section>
[/sourcecode]

Then, add this entry just below “configSections” section:

[sourcecode language=”xml”]
<ccmSettings configSource="ccm_settings.config" />
[/sourcecode]

These modifications tell the environment that it should look for CUCM-specific configuration entries in a file called “ccm_settings.config”. Go ahead and create it, next to the dllhost.exe.config. Here is the simplest configuration file content that is used in this demo:

[sourcecode language=”xml”]
<?xml version="1.0" encoding="utf-8" ?>
<ccmSettings>
<add key="CCM.url" value="https://192.168.1.200:8443/axl/"/>
<add key="CCM.username" value="admin"/>
<add key="CCM.password" value="password"/>
<add key="CCM.soapActionHeader" value="CUCM:DB ver=7.0"/>

<add key="CCM.queries.users" value="u.pkid, u.userid, u.firstname, u.lastname, d.pkid phoneid, n.dnorpattern phonenumber from enduser as u left outer join enduserdevicemap as eudm on eudm.fkenduser=u.pkid left outer join device as d on d.pkid = eudm.fkdevice left outer join devicenumplanmap as dmap on dmap.fkdevice=d.pkid left outer join numplan as n on dmap.fknumplan = n.pkid where u.status == 1 and (eudm.defaultprofile is null or eudm.defaultprofile == ‘t’)" />
</ccmSettings>
[/sourcecode]

As out can see, it contains information “how to connect to CUCM” and a query that is used to fetch users from CUCM, along with their phone numbers. Remember how I stated that we support all ways of associating users with phones in CUCM? Well, here it is. It is all just a matter of a correct query sent to CUCM web services. Nothing is hard-coded, you have full control over the communication process and data sent to and from CUCM.

Testing our configuration

Now after initial setup let’s test our MA in simple import operation. Let’s configure Full import staging operation and pull users from our sample CUCM instance. As you can see below we have pulled three user’s objects from CUCM:

Among others we can see our test user GCH060 with some additional details:

In user details we can see multivalue attribute PhoneNumber, which provides information about line extensions assigned to user in Call Manager.

In similar manner we can pull and expose other information from CUCM as our agent is building connector space attributes based on the output from queries used to pull the data so it is not fixed in anyway in code base.

Also agent can retrieve references between objects and present it as reference attribute. This enabled scenarios where agent can present information about devices assigned to a user with device details and reference attribute which points to the user, or hunt list (line groups) information with list of users, who are members of these groups (actually who’s lines are assigned to these groups).

Through this agent we can also provision new users to CUCM and synchronize passwords and PINs to this target system. But this will be presented in second part of our CUCM description as this post has already become a bit longer than expected. Hopefully with benefit to all who may be interested in that kind of solution.

For further details on our CUCM MA and also on our experience of migration v1 Extensible MA to ECAMv2 … stay tuned to our blog.

FimExplorer

In my previous post I explained how you can execute any query in FIM and see the results. Remember how cumbersome that was?

Today I introduce our next internal project that just got open sourced: FimExplorer. Here is what it looks like (bear in mind that it’s not supposed to be pretty;) ):

And here is what it can do:

  • run any xpath query against FIM
    • you can choose what attributes will be fetched; all are fetched by default
  • find objects by ID
  • display results in grid
  • display single object information in a dialog (double-click the grid row)
  • navigate through references (click on the ID link)
  • export displayed results to XML (this one produces the same results as FIM migration cmdlets: Export-FIMConfig / ConvertTo-FIMResource / ConvertFrom-FIMResource, read MSDN for more info)
  • import objects from XML (generated by FimExplorer or FIM cmdlets) and show them in grid; this can be useful for “offline” analysis
  • it is not required to run on a machine with FIM installed

You can find the code on GitHub and CodePlex. Compiled, ready-to-run version is also available (on CodePlex). Of course you are more than welcome to send contributions via pull requests.

Before running the application you need to modify it’s configuration file (Predica.FimExplorer.exe.config). Just replace the initial settings with your own FIM URL, username and password.

Important (at least for those who will explore code of this project):

It uses our FimCommunication library under the hood. It is referenced as a Git submodule. So after you clone the FimExplorer repository make sure to also run “git submodule init” and “git submodule update” commands to download it!

Executing any XPath queries in FIM, the hard way

Being able to execute any query in FIM and get the results can be crucial when developing FIM-based solutions. Analysis based on real data can be very helpful during debugging as well as designing FIM objects to complete a certain task.

<sarcasm mode=”on”>
Fortunately Microsoft knows this is the case and provided an easy way to send XPath to FIM and get the result set.
</sarcasm mode=”off”>

Of course the above statement is not really true. In order to get XPath query results in FIM you need to:

  • Go to Search Scopes configuration

  • Start to create new Search Scope and fill first screen with any data:

  • Enter query on 2nd screen and “TAB away” – get focus out of the field. The query will now be executed and you will be presented the results in a standard FIM grid:

And this works. It’s not the most comfortable solution, but it gets the job done. However it adds a massive overhead if all you need to do is just perform some quick query/data checks.

Quick Editors Note (from Tomek)

#1

Of course … there is still PowerShell which can be used here.

#2

Probably most annoying thing here is that when one will make mistake in a query or in its syntax, or just query is not proper for FIM to crunch it, you will get only this error message:

Now it is up to you to figure out what’s wrong, which in case of complex queries might be sometimes problematic.

For now this is all I have to share with you. An alternative solution to this problem will be included in my next post. And yes, this will be another Predica open source project!

Happy querying!

Predica.FimCommunication code samples

Hi, it’s Maciek again here with some FIM .NET developer goodies.

As I promised in my previous post, our FimCommunication library is now available on GitHub!

It’s time to see how it works. Bear in mind that we follow the KISS principle when we can. Therefore it was not our intention to create a, for example, full- blown LINQ provider for FIM. It could be fun, but its usefulness is questionable. You’re welcome to implement it and send us a pull request if you wish :).

Basic usage

These are some short code snippets for performing the basic operation with our FimClient:

[sourcecode language=”csharp”]
//XPath Query
var client = new FimClient();
var allPeople = client.EnumerateAll("/Person");
//Find by id
var person = (RmPerson)_client.FindById(personId);
[/sourcecode]

If no object with this ID is found, null will be returned.

Create

[sourcecode language=”csharp”]
var newPerson = new RmPerson()
{
FirstName = "person first name"
};
_client.Create(newPerson);
[/sourcecode]

Update

[sourcecode language=”csharp”]
var person = (RmPerson)_client.FindById(personId);
var personChanges = new RmResourceChanges(person);
persponChanges.BeginChanges();
person.LastName = "new last name";
_client.Update(personChanges);
[/sourcecode]

Delete

[sourcecode language=”csharp”]
var personToDelete = new RmPerson {
ObjectID = new RmReference(personId)
};
_client.Delete(personToDelete);
[/sourcecode]

Paging

Original fim2010client does not provide an easy access to executing paged queries, so we introduced it in our library. You can use it like this:

[sourcecode language=”csharp”]
var first10People = _client.EnumeratePage(
"/Person", Pagination.FirstPageOfSize(10), SortingInstructions.None
);

var second3People = _client.EnumeratePage(
/Person", new Pagination(1, 3), SortingInstructions.None
);

var allPeople = _client.EnumeratePage(
"/Person", Pagination.All, SortingInstructions.None
);
[/sourcecode]

Filtering

We created a little infrastructure code around filtering logic. For example you could create an xpath query like this:

Simple filtering

[sourcecode language=”csharp”]
var firstNameFilter = new Filter(
RmPerson.AttributeNames.FirstName.Name, "John", FilterOperation.Equals
);

var lastNameFilter = new Filter(
RmPerson.AttributeNames.LastName.Name, "mit", FilterOperation.Contains
);

var createdFilter = new Filter(
RmResource.AttributeNames.CreatedTime.Name, "2012-04-18",
FilterOperation.Equals, AttributeTypes.DateTime
);

string xpath = "/Person["+ firstNameFilter.ComposeXPath()
+ " and "
+ lastNameFilter.ComposeXPath()
+ " and "
+ createdFilter.ComposeXPath()
+ "]";

var enumerateAll = _client.EnumerateAll(xpath).ToList();
[/sourcecode]

It requires manually joining conditions with correct and/or operators, but we did not need anything more complex, like grouping conditions in some aggregator filters.

“Contains” operation

“Contains” filter operation is particularly interesting as it uses a workaround to “cheat” FIM, which by default does not handle “contains” XPath function properly. The above filter produces the following result:

[sourcecode language=”csharp”]
/Person[FirstName = ‘John’ and starts-with(LastName, ‘%mit’) and CreatedTime >= ‘2012-04-18T00:00:00’ and CreatedTime <= ‘2012-04-18T23:59:59’]
[/sourcecode]

Filtering by references

You can also use a special “reference” syntax to filter objects by their references. This sample filter will look for people that have managers with first name equal to “Mary”:

[sourcecode language=”csharp”]
var managerFirstNameFilter = new Filter(
"[ref]Manager,Person,FirstName", "Mary", FilterOperation.Equals
);

var query = "/Person[" + managerFirstNameFilter.ComposeXPath() + "]";
[/sourcecode]

Result XPath query:

[sourcecode language=”csharp”]
/Person[Manager=/Person[FirstName = ‘Mary’]]
[/sourcecode]

You can browse more Filter usage samples in FilterTests class available here.

Sorting

Paging and sorting kind of complete each other, so it has to be simple. We introduced our own sorting structures to be used like here:

[sourcecode language=”csharp”]
var peopleSortedDescByFirstName = _client.EnumeratePage<RmPerson>("/Person"
, Pagination.All
, new SortingInstructions(RmPerson.AttributeNames.FirstName.Name, SortOrder.Descending)
);
[/sourcecode]

It can be joined with paging:

[sourcecode language=”csharp”]
var thirdPageOfPeopleSortedAscByLastName = _client.EnumeratePage<RmPerson>("/Person"
, new Pagination(Pagination.FirstPageIndex + 2, 4)
, new SortingInstructions(RmPerson.AttributeNames.LastName.Name, SortOrder.Ascending)
);
[/sourcecode]

Sorting unit tests can be found here.

Selecting attributes to fetch

One thing we’ve learned along the way is that loading “full” objects from FIM can have negative impact on performance. It is often required to fine tune the query so that it fetches only a few selected attributes. Diagnostic logs described in previous post can help pin-point such performance-critical locations.

One attribute is particularly important: object type. It is required, because ResourceTypeFactory would not know what type it should construct if this value was missing. But you don’t have to worry about that, it’s been taken care of by the FimClient internals, this attribute is always fetched whether you requested it or not.

[sourcecode language=”csharp”]
var peopleWithFirstName = _client.EnumerateAll(
"/Person"
, new AttributesToFetch(RmPerson.AttributeNames.FirstName.Name)
);

var attributes = new AttributesToFetch(RmPerson.AttributeNames.LastName.Name)
.AppendAttribute(RmPerson.AttributeNames.AccountName.Name);

var peopleWithSelectedAttributes = _client.EnumeratePage(
"/Person"
, Pagination.All
, SortingInstructions.None
, attributes
);
[/sourcecode]

Full behavior of AttributesToFetch class can be viewed by browsing it’s tests.

This concludes the usage scenarios of our FIM communication library. Let us know what you think about it. Any suggestions, ideas?

Blog picture: (cceisenrah

Introducing Predica.FimCommunication library

Hi, my name is Maciej and here at Predica Team I’m acting as a dev lead and .NET developer. One of key focus of Predica is implementation of Identity and Access Management solutions based on Microsoft software stack, thus I had to learn my way into this world from developer’s perspective. Here on a blog I will try to share part of this knowledge for the benefit of FIM crowd … or just for fun (hopefully both).

If you are a developer with urgent need to communicate with FIM programmatically via its web services, you are most probably already familiar with FIM 2010 Resource Management Client library. It is a reference FIM client implementation provided by Microsoft, open sourced and available on CodePlex.

Regardless if it is best solution, this is definitely the recommended way of dealing with FIM objects as opposed to creating your own (if one will choose to do this I hope it will be shared on Codeplex or GitHub as well). However when working with this reference solution we had several big BUT moments when we have come across some implementation or usage details. Because of these moments we @ Predica Team have decided to create an intermediate layer between fim2010client and our application code.

This is an introductory post about our custom library that overcomes standard fim2010client shortcomings. While this will be focused mainly on developers working with FIM web service, this is also intended to give architects and other persons working with FIM necessary information to make right decisions in regards of implementation way choice.

4 main reasons why not use FIM 2010 Resource Management Client directly?

#1: ResourceTypeFactory

One of the biggest pains in creating solutions using the client in question is its DefautReourceTypeFactory class. It is responsible for creating instances of concrete FIM resource types by their names. This can be done in a very elegant way that finds correct types in runtime, but instead the default implementation forces the developer to change its code each time a new resource type is added to the solution. Take a moment to see for yourself: DefaultResourceTypeFactory.cs. This is not the most developer-friendly way to provide such functionality, to say the least.

This can be easily automated with a scripting in Powershell but again … is it really necessary?

Luckily the fim2010client team was sane enough to extract this contract to a separate IResourceTypeFactory interface. We solved this issue by implementing our own factory that just handles everything internally, with no modifications, by scanning loaded assemblies and finding the requested types using well defined, easy to follow conventions. Various performance tricks can be included here, so that the reflection logic is executed only once.

#2: Bugs

Bugs are a natural consequence of writing code – no argument here. One of advantages of open sourcing a project is allowing outsiders to find them, fix them and publish the fixes for everyone to use. We found  two bugs, fixed them and sent a unit-tested pull request on codeplex, but unfortunately it was not merged into the project. To be honest, this project does not look to be very alive after all.

In this case we are just using our own copy of the library, with our modifications applied.

#3: Initialization performance

Project wiki contains a very simple code sample that shows how a developer should use the default implementation to call FIM web services. It recommends the RefreshSchema() method to be called each time the client instance is created. It would be OK if this call did not result in downloading at least 1MB of XML! Getting rid of this requirement alone boosted our applications very much.

You can imagine that FIM schema is not something that changes so often that we should download and parse it a million times during client application life time. Why not just fetch it once, when the client is first initialized, and then reuse it for all subsequently created instances? We did not find any argument against this approach and it paid off in a massive performance gain.

#4: Paging performance

There is not much that can be done when it comes to web-service, xml-oriented communication from a developer point of view. However we found that there is one place that can greatly enhance the overall FIM-communication experience. It is the size of batch that the library uses when fetching large portions of data from FIM.

This setting is crucial for achieving the best results and it varies from project to project, so we were quite surprised when we saw that the default value is hardcoded in a constant Constants.WsEnumeration.DefaultMaxElements field and cannot be fine-tuned without recompilation of the whole solution.

We moved this value to application configuration and playing with different values proved to produce very satisfying results. To achieve this, we had to modify EnumerationRequest.cs ctor so that it looks into application configuration first searching for default’s override.

 

3 Additional reasons why to use Predica.FimCommunication

#1: Diagnostics

We all know the weird feeling that appears in our guts when we get a performance-related bug from a client that says “hello dear developer, your application sucks does not perform well because it is so damn slow on my machine!”. What can we do with such poor description? Not much.

This is why we built very extensive diagnostic logging logic into our library. Each FIM operation is sent to logging framework and can be processed in various ways. We also added a concept of “long queries”, which are logged as WARN instead of DEBUG level. The default duration of “long query” is 2500ms, but it can be changed in application configuration file.

Such logs contain lots of useful information: the XPath query that is sent to FIM, paging/sorting data as well as requested attribute names list and exact query duration. When used in web application, we also added URL and User fields to the log messages. This allowed us to fine tune FIM queries and squeeze the best performance from most resource-greedy scenarios based only on log files sent by our clients.

Short side note: we use NLog because… well, it is the best logging framework for .NET available :). You can easily send NLog’s output to standard DEBUG stream, console, file, database, e-mail, http endpoint… wherever you like. We find it particularly useful to spit every single log to DEBUG and filter it with DebugView from SysInternals on dev machines, and configure a comfortable log files structure on client servers.

#2: Unit tests

We strongly believe in the power of unit tests and test-driven development. Some of us may even be perceived as TDD zealots (count me as one).

One way or another, while the original fim2010client implementation has some unit tests, this suite is very far from being comprehensive (start here to browse it). We had a goal of testing every single aspect of our library, literally bombarding given FIM instance with various queries and commands. This led to some interesting findings in FIM behavior.

A complete unit tests suite can obviously serve as a perfect demo code for developers that want to use our FimClient APIs.

#3: Runtime configuration

The original fim2010client requires configuration to be defined in application configuration file. There is nothing wrong with this approach, it is WCF after all. But some of our solutions required gathering FIM connection information (url, username, password) from user during runtime. We extended the DefaultClient implementation to use values given in code rather than require static config-file-only information.

In closing…

I hope you enjoyed this post and are eager to put your hands on this lib. Soon I will follow up on this library and examples how to use it. As part of this series we will also publish this implementation on GitHub for FIM community to use. It was very beneficial for us in many projects so we think that it might be beneficial for community, as well as encourage others to work on FIM client library too.

Hopefully this post has made you hungry for more. So stay tuned on our blog and until then: may the FIM be with you!

Blog picture: (ccknejonbro