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.

There are two sections to this docs page –

  • Using Groups *without* using Active Directory integration
  • Using Active Directory integration to sync Groups with AD

Which should you use? Well, 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!


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

This method is a little harder and involves using existing groups inside Microsoft Active Directory. Enabling AD integration will allow your groups to reflect your AD structure, making many reports more intuitive and easier to read. This will keep the groups updated automatically, but does require a few conditions to be met before it can be implemented.

As a note, it *may* be possible to set up LDAP in this same way, but we rely on the free Splunk app “Splunk Supporting Add-on for Active Directory.” That app used to be fairly LDAP capable, but may not be so any more.  If you’d like to try this, it is OK with us and if it works, that’s great!  Unfortunately if it doesn’t work, we will not be able to provide a significant amount of support for you.

Prerequisites for using AD groups in the Cisco CDR Reporting and Analytics app are that you have Microsoft Active Directory set up in your company, that the directory structure or some field in AD/LDAP contains items you would like to use as your groups in the CDR app, and that you have an account you can use to access AD to retrieve this information. If you find those are all the case, then this set of steps might be something to try.

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.

This is only one example, though it is a very common one. 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.

Now that we’ve determined which Active Directory fields need to be mapped into the CDR App’s groups fields, we need to enable a mechanism to retrieve that information from AD into Splunk. This will be done with the Splunk Supporting Add-on for Active Directory.

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

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
| 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.

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.

Troubleshooting

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.




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