Enabling and using Groups

Groups allow you to use the Cisco CDR Reporting and Analytics app as a miniature contact center.

Those names can be used elsewhere, too – they’re full class citizens of the app and you can search on them in Browse Calls, report on them in General Report, and otherwise just use those like you use any other field.

First note this is actually optional!

While useful, this isn’t actually required to make the product work so if you don’t have time to set it up right now, this is OK. Keep it in mind though, you might find you want it sooner rather than later!

Second, there’s two ways to do this!

There are two sections to this docs page –

Which should you use?

If you are just testing the waters or trying out how Groups work, you can easily put in half a dozen entries manually and use that to get a feel for what it does.  If you have a way to maintain a CSV file with information, you could use this to upload it.  (Just make sure it’s in the right format).  Also, if you don’t have Active Directory set up or if your Splunk server won’t be allowed to access AD, then the manual way may be your only option.

If you have Active Directory and will be allowed to access it to retrieve a list of users, groups and numbers (and perhaps subgroups), then I’d suggest giving it a try!

If you’ve already set this up and are looking for information on things to do with groups, see our user docs on groups!

1) Enabling and Using Groups Without Active Directory

Click Setup > Define Groups in the app’s main navigation bar.

On that page you can:

  1. Get more information about how to use these pages
  2. Edit existing groups and extensions
    • Useful for making small, quick changes to a few entries
  3. Add new groups and extensions
  4. Upload a new CSV
    • The new CSV overwrites the old lookup, so replaces it entirely. Make sure you include everything!
    • If the team that manages identities can give you a properly formatted CSV (see #5), this is where you can upload it to your system.
  5. Download a CSV version of the existing groups and extensions
    • You could edit this and re-upload as per #4
    • Also useful to give as a “template” to your networking team.
  6. Or find new, unassigned groups and extensions to add.
    • Numbers that are already in a group are filtered out of this list, so don’t be alarmed that you can’t see everything!

If you are going to use the manual groups, this is all you need to do. The advantages are that this is quick and easy for smaller installations. The drawback to this method is that you must remember to keep these groups manually updated.

Once a few entries are in place, hop over to our User Docs section for Using Groups for more ideas!

– OR –

2) Enabling Groups lookups to use Active Directory

Why are we working so hard?  Why not just use Microsoft Active Directory, which will be a more complete picture.  This will also keep the groups updated automatically, but does require a few conditions to be met before it can be implemented.

Note that you may need to contact your AD administrator to complete some of the steps. Also be aware that a large portion of these instructions are using the core Splunk product and not using the CDR App specifically. As such, additional help with and documentation for the Splunk Supporting Add-on for Active Directory and lookups can found in Splunk’s documentation.

Determine the logical Mapping of Active Directory fields to CDR fields

The CDR app’s “Groups” should have at a minimum the number, name and group fields. A subgroup field is semi-optional – it doesn’t have to be set to any particular value, but it does have to be a column in our lookup. You’ll see that at the end of the search we will add this as an empty field, but otherwise it won’t be included in this example.

Active Directory already has fields that would normally match up with the fields needed for the CDR app;

  • number should be mapped to AD field telephoneNumber
  • name should be mapped to AD field displayName
  • group should be mapped to AD field department
  • subgroup is not mapped in this example, though we still need to output a blank column.
  • (Also, subgroup2, subgroup3 and subgroup4 should exist in the output.  These require some customization to “turn on” in the app, but they have to exist though if you find yourself needing them let us know and we can  help!)

We provide a very common, simple example below.  Your own mapping of CDR app groups to Active Directory fields may differ. For instance, your environment may be better suited to using the Location field in AD to populate group.

Follow these instructions for now, and at the end there’s a link to a blog that makes this all even better!

Step 1: Install and Configure the Splunk Supporting Add-on for Active Directory

The Splunk Supporting Add-on for Active Directory is also known as SA-ldapsearch.

You should have a working installation of this app when finished.

Step 2: Create the search to retrieve records.

The following LDAP search should retrieve all users that are included in the Base DN you included in your LDAP setup.

| ldapsearch search="(&(objectClass=user) (!(objectClass=computer)))" 
    attrs="userAccountControl, telephoneNumber, displayName, department"
| rex field=telephoneNumber mode=sed "s/[^0-9+]//g" 
| where userAccountControl="NORMAL_ACCOUNT" 
    AND isnotnull(telephoneNumber) AND telephoneNumber!="" 
| rename telephoneNumber AS number, displayName AS name, department AS group
| table number, name, group, subgroup, subgroup2, subgroup3, subgroup4

The first two lines ( | ldapsearch… and attrs) are the base LDAP search. It uses its own non-obvious syntax, but it’s likely you won’t need to change this line because as it is it will include all AD user objects and exclude computer objects. We also use the attrs attribute to trim down the returned set of fields to just those we need. (Makes it run 10x as fast!)

The third line ( | rex … ) strips out dashes, parenthesis and spaces from the telephone number to leave only the digits and the plus sign if it’s in there.

The fourth and fifth lines ( where userAccountControl=… ) search for only those accounts that are “regular” users, and ones where they have a telephone number. Searching for the “regular” users is difficult in the ldap search because userAccountControl is a multivalued field and ldapsearch finds this difficult. Since Splunk has no issues at all with searching multivalued fields, we do this filtering here.

The sixth ( | rename … ) and seventh lines ( | table … ) make the output into the right format and match up the AD field names with the CDR field names. NOTE that it’s very important the table command contains all 4 fields – number, name, group subgroup – even if you don’t have data for one of them.

Confirm that search works in a new Search window in the Splunk Support Add-on for Active Directory. Note it may take a few seconds or even minutes for results to come back. Be patient! We are going to schedule the update so it won’t matter a lot if it takes a few minutes to run.

Step 3: Create the outputlookup

Now that we have a search that returns the data we need to enable AD groups to be used in the CDR App, we need to use that search to create the lookup file we need.

Modify the search above (or your version of it) and add to the end of it

| outputlookup groups

Like so:

| ldapsearch search="(&(objectClass=user) (!(objectClass=computer)))" 
    attrs="userAccountControl, telephoneNumber, displayName, department"
| rex field=telephoneNumber mode=sed "s/[^0-9+]//g" 
| where userAccountControl="NORMAL_ACCOUNT" 
    AND isnotnull(telephoneNumber) AND telephoneNumber!="" 
| rename telephoneNumber AS number, displayName AS name, department AS group
| table number, name, group, subgroup, subgroup2, subgroup3, subgroup4
| outputlookup groups

Run that search once manually to populate the lookup the first time. Note that the outputlookup command is somewhat invisible – the search results you’ll see in Splunk will look just like the results you get if you didn’t have the outputlookup command in it. This is normal and expected. Wait until you get results to display, then you can proceed.

If this looks good and is all you need, great.  Keep going to schedule the search.

If everything works to this point but you want to take it to the next level, I wrote a blog on getting accurate names that takes this to the next level.  Go there and do that instead of the rest of this.

Step 4: Schedule the search

Save that search by clicking Save As then Report. Name it <Your Company Name>_AD_Lookups_for_CDR. You do not need to have it include a timerange picker.

In the Report has been created dialog, click Schedule. Set the options appropriately for your environment (perhaps daily at 2:00 AM with a scheduling window of an hour to let Splunk move the exact timing a bit if it needs to).

Step 5: Test

In the CDR App, click Setup then Define groups (optional). Click the tab for Edit/Delete Extensions/Groups. It should mirror the list from the search we created.

If it returns an appropriate list, we are done.


If you do not get a list of groups when you click Setup, Define groups (optional) then Edit/Delete Extensions/Groups, then there is a problem in the lookup. Your first step should be to carefully review the steps to create the lookup. Note especially the following things:

  1. The Test connection button near the bottom of the Splunk Supporting Add-on for Active Directory should return successfully. Please consult with your AD administrator if it does not.
  2. The search you crafted in Step 2 should return data. If it does not, review this search and correct as required.
  3. Review the syntax for the | outputlookup groups command in Step 3.
  4. Make sure you ran the full command from Step 3 at least once to initially populate the groups lookup.
  5. Ensure your schedule for the <Your Company Name>_AD_Lookups_for_CDR saved search is correct and enabled.

You can also confirm that the lookup is populated with this command:

| inputlookup groups

If all steps appear correct but you still get no data and the above inputlookup doesn’t display anything either, then you might want to confirm permissions on the lookup itself. The following outlines how to check and set those.

    1. In Splunk’s interface at Settings, Lookups, Lookup table files.
    2. Change App Context to All (or uncheck the option to Show only objects created in this app context).
    3. Search in the upper right for the word groups.
    4. For the groups.csv item, click the Permissions link under Sharing.
    5. In the resulting dialog, ensure that it should appear in All apps and that Everyone has at least read permission to it.

Next steps

Once you have that set up and working, you might want to visit a blog I wrote on getting accurate names that takes this to the next level.  With the blog’s search, we grab more than just the one phone field.  More importantly, it gives you a sort of template to use to extend this even farther.

If you just want tips on what to explore with your newly set-up groups, see our user docs on groups!

If you have any comments at all about the documentation, please send it in to docs@sideviewapps.com.