You may wish to filter the records from a usersource so that only some of them are converted into Deskpro Users or Agents.

For example, suppose you have a database which contains every subscriber you’ve ever had, but you only want to grant Help Center 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 and 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.

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. Click on View Log.

1. Select 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
)
 copy
 copy

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

[friendly_identity] => tessie.west
 copy

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

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

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
    )
 copy

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

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 or Agent to be able to log in to Deskpro (and to be synced).

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

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
     )
 copy
 copy

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
    )
 copy
 copy

User 2:

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

User 3:

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

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

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:

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.

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.