Active Directory Employee List - 0.1 - Screenshot 4

Active Directory Employee List

Description

This plugin allows you to query an active directory server to retrieve an optionally filtered list of users and display it as a list within a WordPress site. Some of the features of this plugin include:

  • Widget – a widget is provided, with a few filtering/formatting options, to allow you to display a user list in any widgetized area
  • Shortcode – a shortcode is provided, with all of the plugin’s filtering/formatting options, to allow you to display a user list within any page or post
  • Output builder – a full-featured output builder is provided, allowing you to completely customize the format in which each user is displayed within the list. The output builder even allows conditional (if…elseif…else) statements.
  • Format options – in addition to the output builder (which is used for each individual user), the following formatting options are also available:
    • before_list – Any HTML code you would like to appear before the list of employees. This code is output before the opening title_wrap tag.
    • after_list – Any HTML code you would like to appear after the list of employees. This code is output after the closing list_wrap tag.
    • after_title – Any HTML code you would like to appear between the closing title_wrap tag and the opening list_wrap tag.
    • title_wrap – The HTML element you would like to use to wrap the list title (if set). Just the element name, please; no opening or closing brackets.
    • title_class – The CSS class you would like applied to the list title (if set). If you would prefer that no CSS class be applied to the title, leave this blank.
    • title_id – If you would like to apply an HTML ID to the list title, you can indicate that here. Remember that IDs should be unique, so, if you plan on using multiple employee lists on a single page, you should leave this blank.
    • title – The title you would like to appear at the top of the list. The title is output prior to the opening of the list itself.
    • list_wrap – The HTML element you would like to use to wrap the entire list. Just the element name, please; no opening or closing brackets.
    • list_class – The CSS class you would like to assign to the opening list_wrap tag, aiding in styling the entire list. If you would prefer that no CSS class be applied to the list, leave this blank.
    • list_id – If you would like to apply an HTML ID to the list itself, you can indicate that here. Remember that IDs should be unique, so, if you plan on using multiple employee lists on a single page, you should leave this blank.
    • item_wrap – The HTML element you would like to use to wrap each individual employee in the list. Just the element name, please; no opening or closing brackets.
    • item_class – The CSS class you would like to assign to each individual employee in the list. If you would prefer that no CSS class be applied to the list, leave this blank.
    • item_id – If you would like to apply an HTML ID to each individual employee in the list, you can indicate that here. You can use placeholder variables for user information (any of the fields that are set to be retrieved, plus the user’s username (samaccountname). Simply wrap the placeholder variable with percent symbols (so, to use a placeholder for samaccountname, use %samaccountname%) All disallowed characters (the @ symbol, dots, spaces, etc.) will be replaced with hyphens. Remember that IDs should be unique, so, if you plan on using multiple employee lists that may include the same employee multiple times on a single page, you should leave this blank. Likewise, you should use a placeholder variable that will be unique.
  • Field chooser – choose which Active Directory fields to retrieve from the server (note that any fields included in the output builder must be chosen in the field chooser, otherwise they won’t be retrieved and, therfore, won’t be displayed)
  • Single user display – feed a username to the shortcode or widget, and a single user will be retrieved and displayed, rather than a list of users
  • Search form – a simple search form (the input keyword is searched against all fields being retrieved) is provided
  • Multisite-compatible – Options can be set for the entire network, and can be overridden on each individual site within the network. Some options can even be overridden in the widget or shortcode itself.
  • Information cache – Information retrieved by this plugin is cached for 24 hours after it is retrieved (this option is not currently configurable, but will probably be in future versions) in order to avoid hitting the AD server more than necessary.

You can connect to the Active Directory server using SSL and/or TLS, if desired. You can also provide multiple Active Directory server addresses to allow load-balancing (a random server is chosen from the list before connecting and querying).

This plugin currently utilizes version 3.3.2 (with some extended functionality built specifically for this plugin) of the adLDAP class from Scott Barnett & Richard Hyland. It has also been tested with version 3.1-Extended and version 3.3.2-Extended as they are included with various versions of the Active Directory Authentication Integration and Active Directory Integration plugins. This plugin is potentially incompatible (and has not been tested) with Active Directory Integration, though; as it all depends on in which order the adLDAP class is instantiated (if this plugin’s copy of adLDAP is included before that plugin’s version, that plugin may not work properly).

Important Note

At this time, this plugin has only been tested on a handful of WordPress installations (all on similar server configurations) with a single Active Directory server, so it is entirely possible that there will be bugs or errors that stop it (or other plugins) from working properly. In order to improve this plugin, please share any feedback you have.

Installation

This plugin can be installed as a normal plugin, a multisite (network-active) plugin or a mu-plugin (must-use).

To install as a normal or multisite plugin manually:

  1. Download the ZIP file of the current version
  2. Unzip the file on your computer
  3. Upload the active-directory-employee-list folder to /wp-content/plugins

To install as a normal or multisite plugin automatically:

  1. Visit Plugins -> Add New in your Site Admin (for normal WordPress installations) or Network Admin (for multisite WordPress installations) area
  2. Search for Active Directory Employee List
  3. Click the “Install” link for this plugin

To activate the plugin on a single site:

  1. Go to the Plugins menu within the Site Admin area and click the “Activate” link

To network-activate the plugin on a multisite network:

  1. Go to the Plugins menu within the Network Admin area and click the “Activate” link

To install as a mu-plugin:

  1. Download the ZIP file of the current version
  2. Unzip the file on your computer
  3. Upload all of the files inside of the active-directory-employee-list folder into your /wp-content/mu-plugins directory. If you upload the active-directory-employee-list folder itself, you will need to move active-directory-employee-list.php out of that folder so it resides directly in /wp-content/mu-plugins

Frequently Asked Questions

Where should I seek support if I find a bug or have a question?

The best place to seek support is in the official WordPress support forums. If you don’t get an answer there, you can try posting a comment on the official plugin page. Finally, you can hit me up on Twitter if you want me to take a look at something.

Will this plugin work in a multisite environment?

Yes. It can be activated normally on each individual site or it can be network-activated.

Will this plugin work in a multi-network environment?

Yes. However, at this time, it is not optimized for a multi-network environment (without a set of functions that are currently unavailable to the public, as they are still under development separately from this plugin). Therefore, it will function as any other multisite-compatible plugin would function.

Can I use this as a mu-plugin?

You should be able to, though it will make the plugin potentially even more incompatible with the Active Directory Integration plugin.

Can I show/retrieve members of a specific AD group?

Yes, that is part of the core functionality of this plugin. You can easily filter the list of retrieved users with a specific AD group.

Can I show/retrieve members of multiple AD groups together?

Not at this time. You can only provide one group at a time to filter the results.

Can I display a single user with this plugin?

Yes, you can provide a username (samaccountname or userPrincipalName) to retrieve and display a single user from active directory.

How do I use the output builder?

Documentation for the output builder can be found on the official plugin page.

How do I know which Active Directory fields might be available?

Following is a list of standard Active Directory fields of which I am aware (I used a list from a company called Computer Performanceto compile this list):

  • cn – Common name – First name and last name together
  • description – Full text description of user/group
  • displayname – The name that should be displayed as the user’s name
  • dn – The pre-formatted user string used to bind to active directory
  • givenname – The user’s first name
  • name – Should be the same as CN
  • samaccountname – The unique user ID of the user (generally the login name)
  • sn – The user’s last name
  • userprincipalname – A unique user ID, complete with domain, used for logging in
  • mail – The user’s email address
  • mailnickname – The username portion of the user’s email address
  • c – Country or region
  • company – The name of the user’s company
  • department – The name of the user’s department in the company
  • homephone – The user’s home telephone number
  • l – The physical location (city) of the user
  • location – The computer location (??) of the user?
  • manager – The user’s boss or manager
  • mobile – The user’s mobile phone number
  • ou – Organizational unit
  • postalcode – ZIP code
  • st – State, province or county
  • streetaddress – First line of postal address
  • telephonenumber – Office phone number

I got a blank white screen, or only part of the page loaded; what does that mean?

That most likely means that too much information was retrieved and formatted at once by the plugin. Try retrieving/displaying fewer fields and/or filtering the list of users with a specific Active Directory group to see if that solves the issue. I have not yet implemented pagination in this plugin, so there is currently no way to limit the number of users it attempts to retrieve and display at once.

It doesn’t seem to be retrieving the complete list I expected

Unfortunately, there is a documented issue with PHP that it doesn’t allow “paging” of query results. Therefore, it will only retrieve as many users as your Active Directory is configured to allow on a single “page” (appears to be 1500 by default).

Screenshots

Output Builder Usage

You can use any of the following tags (assuming you have set the plugin to retrieve these fields) within the output builder:

  • %cn%
  • %description%
  • %displayname%
  • %dn%
  • %givenname%
  • %name%
  • %samaccountname%
  • %sn%
  • %userprincipalname%
  • %mail%
  • %mailnickname%
  • %c%
  • %company%
  • %department%
  • %homephone%
  • %l%
  • %location%
  • %manager%
  • %mobile%
  • %ou%
  • %postalcode%
  • %st%
  • %streetaddress%
  • %telephonenumber%

You can also use conditional statements within the output builder. The conditional statements should begin with an [if] block and end with an [endif] block. They can also include [elseif] and [else]blocks. The [if] and [elseif] blocks should include a condition.

For instance, if you would like check to see if the user has an email address set in their active directory profile, you would use [if mail] or [elseif mail].

The conditional statements simply check for the existence of a value in the field provided. You cannot nest conditional statements, nor can you provide multiple conditions in a single [if]/[elseif] (not yet, at least), unfortunately.

An example of a conditional might look something like:

<h3>[if mail]<a href="mailto:%mail%">%givenname% %sn%</a>[elseif displayname]%displayname%[else]%givenname% %sn%[endif]</h3>

Download

You can download the current version of this plugin from the WordPress repository.

17 thoughts on “Active Directory Employee List

  1. Pingback: Active Directory Employee List 0.2.1a | Ten-321 WordPress Plug-Ins

  2. George

    Hello!
    Thanks for you plugin! I hope that a lot of companies will find it very usefull!

    Unfortunatelly i have this ussue during activation process:
    Parse error: syntax error, unexpected T_FUNCTION in C:\Program Files (x86)\Apache Software Foundation\Apache2.2\htdocs\wordpress\wp-content\plugins\active-directory-employee-list\active-directory-employee-list.php on line 66
    Can you help?
    I use WordPress 3.2.1.

    Thanks a lot!

    Reply
    1. Curtiss Grymala Post author

      I think this is a PHP compatibility issue. I’m working on a fix for the problem (in the meantime, if you want to try it yourself, you can simply replace line 65 with the code shown below); but I was made aware of another problem that probably needs to be fixed before you’ll be able to really use it.

      add_action( 'widgets_init', create_function( '', "register_widget( 'active_directory_employee_list_widget' );" ) );

      Reply
  3. Kev Easom

    Hello,
    does the plug-in actually enable us to display a directory listing on the front end of the blog, or is it only active on the admin side of WP? I’m building an intranet and want to display a company directory, populated by the AD information.

    Reply
    1. Curtiss Grymala Post author

      This plugin displays a list of Active Directory members on the front-end of the website. In a few more days, I’ll have a public link I will share to show the plugin in action.

      If you try out the plugin, please let me know how it goes. I have still only had a few people report about their experiences with the plugin, so I’m not sure how well it’s working out. I’d love to hear your feedback to help improve it. Thanks.

      Reply
      1. Jeremy

        Hi Curtiss!

        I also need to display the Directory on one of the WP pages/posts. How do I show it on the page? Do you have the public link to show the plugin in action?

        Thanks,

        Jeremy

        Reply
        1. Curtiss Grymala Post author

          Jeremy,
          You can see the plugin in action at http://www.umw.edu/. There are a few ways to see the plugin in action on that site:

          1. Choose the “People” radio button in the search interface at the top of the page and search for a name. You’ll see results returned by this plugin.
          2. Click “Helpful Links” at the top of the page and choose the “Directory” (in the row of icons at the bottom of the Helpful Links window); then search for a name.
          3. Visit a page like http://adminfinance.umw.edu/our-staff/. That page uses the shortcode to output a list of employees within a specific security group.

          The shortcode used on that page is simply:
          [ad-employee-list group="MY_SECURITY_GROUP"]
          where “MY_SECURITY_GROUP” should be replaced with the name of the security group or distribution list you want to use.

          Reply
  4. Pingback: Live Examples of Some Plugins | Ten-321 WordPress Plug-Ins

  5. Matt

    Hi there- I’m trying to use this plugin (Active Directory Employee List) but when I do a search, it never returns any matches.

    I am using the plugin “Active Directory Integration” (which has a test tool and when I run it, I am able to see the AD connection is successful) – When I use the same settings in AD Employee List for connecting to our AD, it returns nothing. I’m using the latest development version as the current released version was giving me the error of not saving any settings. Any feedback or help troubleshooting would be great.

    Thanks,
    Matt

    Reply
    1. Curtiss Grymala Post author

      Are you using Active Directory Integration, or are you using Active Directory Authentication Integration? Both of those plugins, along with the Active Directory Employee List plugin all use the same adLDAP class, but they might be using different versions of it (and one of them is going to override the other).

      I know that the development versions of Active Directory Authentication Integration and Active Directory Employee List are compatible with each other; I would just encourage you to use the development versions of both in order to make sure that the classes match up.

      If you’re using Active Directory Integration, I’ll have to take a look and see what might be causing the conflict between the two plugins. Thanks.

      Reply
  6. Matt

    Active Directory Integration – Version 1.1.1 | By Christoph Steindorff, ECW GmbH – I’ll try yours and see if it makes a difference and report back as well.

    Reply
  7. Patrick

    Hello, I am trying to use Active Directory Authentication Integration and Active Directory Employee Listing and I keep getting an error. The message is below:

    LDAP Not Supported

    Your PHP configuration does not appear to support LDAP connections; therefore, the Active Directory Authentication Integration plug-in will not work at all. It is recommended that you deactivate the plug-in until you are able to update your PHP configuration to support LDAP.

    I have setup my WordPress site on Windows Server 2008. Is there something I am missing? Thanks.

    Reply
    1. Curtiss Grymala Post author

      PHP by default does not include the LDAP module. If that message is appearing, it indicates that the LDAP module is not installed and/or configured within your PHP install. You’ll need to have that module installed before you’ll be able to use the plugin. Thank you.

      Reply
  8. SD

    It looks like the paging issue has been resolved, is there any chance of an update so that those of us who have AD larger than 1000-1500 people can use this? http://bugs.php.net/bug.php?id=42060 (scroll to bottom, seems to be fixed in latest php and also previously in the ldap libraries). Thanks!!!!! :)

    Reply
  9. Binoy

    Dear Curtiss,

    First I want to thank you for making this freely available. It is exactly what we want. Had a question regarding the installation. For some reason, AD authenctition module is not able to authenticate (authentication is happening for only one user) also AD employee list module I am getting this errort

    Installing the plugin…

    Could not create directory. /var/www/html/wordpress/wp-content/plugins/active-directory-employee-list/css

    I have given full prermissions. Appreciate your help.

    Best Regards

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *