Creating advanced discussion filters using Extras hash

Caution

This article is for advanced users.

Introduction

Tender allows you to associate key/value pairs to discussions and users. This Extras hash can be used to add custom fields to your users for example, and can also be used for advanced filtering of discussions, using your own parameters.

Extras parameters can be set:

• On discussions through the API.
• On users through SSO. If set on users, they will be copied to every discussion they create.

In this article, we will look at a simple use case: tagging customer with a paying/**free** parameter, as well as the plan they are currently on. We can then use this extra information to add discussions from paying customer to a special queue, where they get priority.

Setting extra parameters on users

When you create the encrypted SSO hash, any extra key that you include will be saved in the extras hash of this user. So if your SSO token looks like this:

{
  "name": Julien",
  "email": "user@example.com",
  "expires": "Fri Jan 12 00:24:23 UTC 2010",
  "customer_type": "paying",
  "customer_plan": "Plan A"
}

The extras hash on this user will contain the keys customer_type and customer_plan. Now, the next time this user creates a discussion, those parameters will be associated with the discussion, and you can filter on them.

Some important considerations:

• Values from extras parameters is not escaped. You should make sure it's safe!

• Some key names are reserved: important and beta. You can't use those in the extras hash.

• While the key may appear in the interface capitalized, they are indeed stored as given. We apply some transformations on the key name to make it easier to read and understand, but the real key name is still customer_type.

• The extras hash, if present in the token, will override any previous value. So if you connect the user once providing customer_type, and then at a different time providing customer_plan (but not customer_type), customer_type will be lost. If you intend to use this functionality, make sure you provide all the extra keys in the token each time.

Setting extra parameters on the discussion

Extra parameters can be set on the discussion with the API. Simply use the extras key to provide a hash:

> curl -H "Accept: application/vnd.tender-v1+json" \
  -H "Content-Type: application/json" \
  -d "{'title':'MY TITLE', ..., 'extras':{'favorite_food': 'tacos'}}" \
  "https://EMAIL:PASS@api.tenderapp.com/help/categories/:category_id/discussions"

Filtering

Once your discussions have extra parameters associated with them, you can simply filter them using the Extras hash options. You can find the filters interface by going to Accounts & Settings > Settings

Then choosing Discussions filters on the left:

We can now create our filter for paying customers:

And save the filter:

Notes: you are not limited to filter on a specific value: you can use Ruby regular expressions as well. For example, if you have two type of plans, basic and premium, and that each type has several options (basic-1, basic-2, premium-1, ...), you can use a regular expression to check for all premium plans:

customer_plan=~premium

Checking the queue

Now that we have our filter in place, let's verify that it works. Our user Julien logged in through SSO with the appropriate parameters and creates a discussion.

It has been filed in the proper queue:

Conclusion

The Extras Hash, while reserved for advanced users, is quite powerful and allows you to filter discussions on pretty much any parameter relevant to your business. You can of course use it in combination with any of the other fields.

Have a question? Start a discussion.