Admin Guide

Filtering a usersource


You may wish to filter the records from a usersource so that only some of them are converted into Deskpro users/agents.

For example, suppose you have a database which contains every subscriber you’ve ever had, but you only want to grant portal access to the active subscribers; or you have an Active Directory containing records for everyone in your company, but you only want staff from the IT department to become agents.

In this situation, you can use the Filter option when you set up the authentication app to limit which users/agents are allowed to log in. You can use filters with any Deskpro authentication app. (For authentication apps that support Auto Sync, filtering will also limit which accounts are created when syncing.)

When Deskpro connects to an external usersource, each user record is interpreted by Deskpro as a user array: a set of values describing properties of the user. The values available will depend on what information is stored in the external usersource.

To create a filter, you must write a filter expression which matches the user records which you want to become Deskpro users or agents.

Note

The format you use to write your filter expression is the Expression Language of Symfony, a PHP programming framework. Luckily, writing a filter doesn’t require you to understand programming or even most of the Expression Language. This section will explain everything you need to know to create a filter.

Viewing a user array

To create a filter, first you must view a user array to see what data the usersource provides about each user.

  1. Follow the installation process for the authentication app you want to use, up until the point where you have entered all the settings.

  2. Click Test Settings.

  3. A pop-up window opens. Enter the name and username and password of a user record as stored in the external source.

  4. If the credentials you’ve entered are valid, you’ll see another pop-up window.

    ../_images/authfilter-test-success.png

  5. Click Show raw user data.

You’ll see the user array in the Raw user data box. For ease of viewing, it’s best to copy the contents of the box into a text editor.

Here’s a simplified example of a user array that might be returned from a usersource.

DATA RECORD:
Array
(
    [company] => Array
        (
            [0] => Acme Global
            [1] => Acme Special Services Ltd.
        )
      [department] => Array
       (
         [0] => IT
       )
    [displayname] => Array
        (
            [0] => Tessie
        )
    [userprincipalname] => Array
        (
            [0] => tessie.west@example.com
        )
    [teams] => Array
        (
            [0] => qa
            [1] => product
            [2] => compliance
        )
    [friendly_identity] => tessie.west
    [domain] => example.com
    [first_name] => Tessie
    [last_name] => West
    [email_address] => tessie.west@example.com
    [active] => yes
)

The user array contains a mixture of simple values, like this:

[friendly_identity] => tessie.west

and arrays (yes, arrays within the array), like this:

[teams] => Array
       (
           [0] => qa
           [1] => product
           [2] => compliance
       )

The arrays are just a way to store one or more values. In our example output, some of the arrays only contain one value, like this:

[displayname] => Array
    (
        [0] => Tessie
    )

Even though this particular user only has one value for [displayname], the fact that it’s an array tells us that some user records might have more than one [displayname].

Note

Some usersources will return a long user array with a lot more information than this simple example. Don’t worry, you don’t need to understand what all of it means: you just need to find the value or array that is relevant to your desired filter.

You need to find a value that distinguishes the user records you want in your filter from the records you don’t want. You may need to look at the user arrays for several different user records to work out what value to use.

Writing a filter expression

You can now write a filter expression based on the values in the user array.

Your filter will specify values which must be true for a user/agent to be able to log in to DeskPRO (and to be synced).

Enter the expression in the Filter field of the authentication app.

../_images/authfilter-field.png

Matching a simple value

Let’s say, in the example above, you want to match only users with the value:

[active] => yes

You’d do that with this filter:

user["active"] == "yes"

This simply means that only those users with [active] => yes will pass the filter.

On further testing, say you found that the possible values are:

[active] => yes [active] => trial [active] => no

and you decide that you want to match yes and trial.

You could do that with the filter:

user["active"] != "no"

This filter will match users that do not have the value no.

Matching an array value

You can match on the value at a specific place in an array.

Suppose your user records have a [company] array, and these are some possible values:

User 1:

[company] => Array ( [0] => Acme Global [1] => Acme Special Services Ltd. )

User 2:

[company] => Array
     (
         [0] => A1 Products
         [1] => A1 Australia
     )

You realise you want to match users where the [0] value is Acme Global.

You’d do that with this filter:

user["company"][0] == "Acme Global"

Matching any value within an array

Often, you won’t want to match a particular position within an array, but just check if a value is contained anywhere within an array. For example:

User 1:

[teams] => Array
    (
        [0] => qa
        [1] => product
        [2] => compliance
    )

User 2:

[teams] => Array
    (
        [0] => product
        [1] => sales
        [2] => marketing
    )

User 3:

[teams] => Array
    (
        [0] => support
    )

Suppose you want to match users who have product anywhere in the [teams] array. You can do this:

"product" in user["teams"]

You can also use not in to match users who don’t have a particular value anywhere within an array.

Advanced filters

As well as the simple == (equals) and != (does not equal) you can use:

and - useful if you want to check two different variables e.g. [active] => yes and "product" in user["teams"]

or

not

There are also other advanced operators you can use, including regular expressions; see the Symfony docs for details.

Testing a filter expression

Once you have entered the filter expression in the Filter field, use the Test Users button to check which user records match.

If a user matches the expression and passes the filter, you will see the usual success pop-up:

../_images/authfilter-test-success.png

If the user doesn’t match the filter, the test will fail. You will be able to see at the end of the log that it failed because of the filter:

../_images/authfilter-test-fail.png

The message will be something like:

failed verification check for filter "user["company"][0] == "Acme""

You should make sure to test both with user records that you expect to pass and that you expect to fail.

When you are happy with your filter, click Save.

Warning

If you are syncing agents from a usersource with a lot of records, make sure your filter works. If you accidentally create a large number of agents, you can cause serious problems with your helpdesk.

Multiple filters

You can install multiple copies of each authentication app, each with a different filter.

This is useful if you want to take all the user records from a source, but assign different usergroups depending on a certain value. You can simply install the app multiple times, with different filters and a different Grant usergroup setting.

Comments (0)

Add a comment

Add a comment

You need to log in before you can submit a comment.

Need a password reminder?