Cleaning up Zendesk Organisations with a sidebar app
Are you a Zendesk admin struggling with managing organizations and their associated user data? If so, you're not alone. Two common issues that Zendesk admins face are organisations with missing users, or badly mapped users. This article will show you how to fix it.
Are you a Zendesk admin struggling with managing organizations and their associated user data? If so, you're not alone.
Two common issues that Zendesk admins face are organisations being created after their users already exist, and not all users being a part of those organizations. Additionally, organizations can contain bad data and users who don't belong to the organization.
Zendesk has a longtime feature where you can automatically assign users to an organization by mapping its custom email domain. Any user that matches that domain will be added to the organization. And while creating organizations witha mapped email domain resolve this issue, it only works for users created after the fact and doesn't always update existing users.
In this blog post, I'll explain how to build/use a new sidebar app that runs in Zendesk Agent Workspace and cleans up your organisations one at a time by leveraging the ZAT and Zendesk APIs. With this app, you'll be able to easily manage your organisation data and improve your customer service workflows.
The Fix
In this article I'll show you how to use/build Organisation Cleaner, a sidebar app designed to help Zendesk admins manage their organisation data more effectively. This app leverages a few APIs to allow admins to quickly clean up any organisation based on the domains setup for that organisation.
The app's primary function is to add missing users or remove bad ones that don't match the domain. This helps to ensure that your organisation data is clean and accurate, which in turn helps to improve your customer service workflows.
To use the app, you can download the latest release from GitHub and install it as a private app in your Agent Workspace. From there, you can select the organisation you want to clean up and run the app. The app will then cleanup the organisation in browser so no data is shared with external sources.
verschorenThe purpose of this blog is explaining how Zendesk works and empower Zendesk Admins and Developers. You can take this app as a starter to make it work specifically for your organization, or use it as is.
If it really provides value for your company, consider subscribing to a paid tier of this blog to make more of these tools possible. And if you need help building this, there's always a Zendesk Partner nearby!
The App
The application runs as a sidebar app in the Organisation View of Agent Workspace. Navigate to any organisation and toggle the Apps Panel to get started.
Test Mode
The app has a build-in test mode . By default we only compare data, but don't update anything in your instance yet.
$('#test_mode').change(function() {
if(this.checked) {
test_mode = true;
} else {
test_mode = false;
}
});Similarly, if you want to look at the results in depth, each user logged in test mode has a clickthrough to the user profile, and we show real updates with a notification top right.
//show user profile
client.invoke('routeTo', 'user', $(this).data('target'));
//show notification
client.invoke('notify', 'Users added!');General Logic
The app has two options: Remove Bad Users and Add Existing Users.
Both use ZAT to get info on the current location the user is looking at in our main handleFlow() logic.
client.get('organization').then(function(organization) {
var domains = organization.organization.domains.split(' ');
var organization_id = organization.organization.id;
//Handle app logic
});Cleaning up an existing organisation
When we want to clean up an existing organisation we use the removeUsers() function.
It uses the /api/v2/organizations/${organization_id}/users endpoint to get all users in the organisation you're looking at. It then takes the Domains you added to that organisation and compares it to the Users in the organisation.
let options = {
contentType: "application/json",
url: `/api/v2/organizations/${organization_id}/users`,
type: "GET",
};
client.request(options).then((users) => {
var users = users.users;
jQuery.each( users, function( i, val ) {
var domain = val.email.split('@')[1];
if (domains.indexOf(domain) == -1) {
//update user
}
});
});For all users where the domain doesn't match ( indexOf == -1 ), we add the user to an unmatchedUsers array and print the output to a log via printOutput()
Example: removing unmatched users
In the example below I scanned the organisation Avengers for any user that didn't have an @avengers.example email-address and remove the bad Hydra agent [email protected]
Adding missing users
Adding missing users works similarly. Since an organisation has potentially multiple domains we run the search for each domain setup in our handleFlow() function.
domains.forEach(function(domain) {
addUsertoDomain(domain,organization_id);
});We first use the search API to search all users that match the domain and aren't part of the organisation via /api/v2/search.json?query. Note the -organization which excludes users in the organization.
function addUsertoDomain(domain,organization_id){
let options = {
contentType: "application/json",
url: `/api/v2/search.json?query=type:user ${domain} -organization:${organization_id}`,
type: "GET",
};
client.request(options).then((users) => {
var users = users.results;
//update users
});
}Once we find our users, we add the user to an unmatchedUsers array and print the output to a log via printOutput()
Example: adding missing users
In the example below I had seven dwarfs in Zendesk already, but never bothered to create an organization for them. Once I created the organization Seven Dwarfs with email @sevendwarfs.example the app found our seven friends, and added them to the organization
Handling the update
If our test_mode is false and we have an unmatchedUsers array, we can handle updating the users via createOrUpdateMany(). This does a basic POST to the Zendesk endpoint that allows us to update up to 100 users at once.
The reason we want to use the create_or_update_many endpoint is since this a single API call that ends up on a Job in Zendesk. We don't need to wait for multiple calls to succeed, and we don't overload the API limits.
function createOrUpdateMany(unmatchedUsers,message){
let options_nomatch = {
contentType: "application/json",
url: `/api/v2/users/create_or_update_many`,
type: "POST",
data: JSON.stringify(unmatchedUsers)
};
client.request(options_nomatch).then((update_many) => {
client.invoke('notify', message);
});
}However, since this all happens in the background, we do want to show some output. This happens with our PrintOutput() function. It adds a list of log lines to our app nicely formatted with an icon (✅/❌) and the users name/email.
verschorenA few caveats
Zendesk returns paginated results. This app only takes into account the first page of results.
For cleaning up an organization I figured chances of organizations having more than 100 users is slim. If you want, you can always update the app to add pagination and add a pull requests here.
To add missing users you're in luck. Each time you press the button we'll pull in the next 100 missing users (if there are any) since the API search excludes already added users.
The readme.md on GitHub also comes with a sample payload to import. You can use these two user sets to easily test and validate the app.
