The Grouparoo Blog
In the process of integrating Grouparoo with Zendesk, I searched the documentation for the right way to format tags, but was unable to find it. I thought I'd write up a guide to help others on the same journey.
In case you are "that person" and just want the answer, here it is:
Tags needs to be lowercase and not have any spaces. You can have underscores.
More Details
Zendesk has the concept of tags which can be set on users using the Support API. User tags are pretty cool because they will get copied to the tickets the user creates. Tags then become the best way to route those tickets to the appropriate resolution.
Here is what it looks like to set the tags via the API:
import zendesk from "node-zendesk";
async function updateTags(tags: Array<string>) {
const remoteUri = `https://${subdomain}.zendesk.com/api/v2`;
const client = new zendesk.createClient({ username, token, remoteUri });
const payload = {
user: {
external_id: "testuser123",
name: "Required Name",
tags: tags,
},
};
try {
const user = await client.users.createOrUpdate(payload);
console.log("tags", user.tags);
} catch (error) {
console.log("error", error.result.toString());
}
}
And here are some outputs:
// standard lowercase tag
await updateTags(["first", "second"]);
// -> tags [ 'first', 'second' ]
// automatically lowercases it
await updateTags(["Third"]);
// -> tags [ 'third' ]
// spaces actually make two tags unexpectedly
await updateTags(["Fourth Tag"]);
// -> tags [ 'fourth', 'tag' ]
// clears tags
await updateTags([""]);
// -> tags []
// clears tags
await updateTags([" "]);
// -> tags []
// ignores leading and trailing spaces
await updateTags([" five "]);
// -> tags [ 'five' ]
// it doesn't like most punctuation but is ok with underscores
await updateTags(["one!", "_here_", "!"]);
// -> tags [ 'one', '_here_' ]
Basically, the function splits the given string or array of strings into lowercase tags. So, if you want to translate some name to a tag (like we do with Grouparoo groups) and predict what it will be in Zendesk, you need to format it correctly.
This function makes the name lowercase and removes spaces and most punctuation. I decided to replace all unsupported punctuation to the one kind of punctuation that I know Zendesk does handle: underscores.
import zendesk from "node-zendesk";
function makeTagName(groupName) {
// tags can't have spaces and have to be lowercase
let tagName = groupName.toLowerCase();
// replace with underscore all punctuation
tagName = tagName.replace(/[^a-z]/g, "_");
return tagName;
}
async function updateTags(tags: Array<string>) {
const remoteUri = `https://${subdomain}.zendesk.com/api/v2`;
const client = new zendesk.createClient({ username, token, remoteUri });
const payload = {
user: {
external_id: "testuser123",
name: "Required Name",
tags: tags.map((tag) => makeTagName(tag)),
},
};
try {
const user = await client.users.createOrUpdate(payload);
console.log("tags", user.tags);
} catch (error) {
console.log("error", error.result.toString());
}
}
Here is how that works out:
// does not allows spaces actually to make two tags unexpectedly
await updateTags(["Fourth Tag"]);
// -> tags [ 'fourth_tag' ]
Grouparoo
This learning and many more are built into the Grouparoo Zendesk plugin. Grouparoo enables you to sync data from your product database or warehouse, create smart cohorts, and use this (and more!) logic to tag them in Zendesk. Check it out!
Tagged in Connections Engineering Notes
See all of Brian Leonard's posts.
Brian is the CEO and co-founder of Grouparoo, an open source data framework that easily connects your data to business tools. Brian is a leader and technologist who enjoys hanging out with his family, traveling, learning new things, and building software that makes people's lives easier.
Learn more about Brian @ https://www.linkedin.com/in/brianl429
Get Started with Grouparoo
Start syncing your data with Grouparoo Cloud
Start Free TrialOr download and try our open source Community edition.