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
andbeta
. You can't use those in theextras
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 providingcustomer_plan
(but notcustomer_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.