Agents

This guide covers Zendesk agent management at GitLab, including the automated agent sync process and manual agent administration. The agent sync automatically maintains agent metadata from GitLab’s team data, while manual processes are used for provisioning and special cases.

Administrators should review the Administrator tasks section.

Understanding Zendesk agents

What are Zendesk agents

Zendesk agents are team members with access to the agent workspace. Unlike end-users who can only submit and view their own tickets, agents can:

• View and manage all tickets
• Access internal notes and fields
• Use macros and triggers
• Perform administrative tasks (based on role)

We largely manage agents via the agent sync (for the Customer Support Operations and Support teams) and via the provisioning/deprovisioning process.

Agent sync

The agent sync manages metadata for Customer Support and Customer Support Operations team members in Zendesk. Other agent accounts (integrations, bots, etc.) are managed manually.

When does it run

• Zendesk Global: 0000 UTC every day
• Zendesk US Government: 0000 Pacific every day

What does it manage

Each run will update the following for the agents:

• GitLab.com user ID (a custom User field)
• GitLab.com username (a custom User field)
• Zendesk Group membership
• Manager tag (a custom User field)
• Name
• Out of Office status (a custom User field)
• Signature
• Select user tags (see How does it work for more details)
• User region (a custom User field for Zendesk Global only)

Any modifications to the agent outside of the sync in Zendesk will be overridden by this.

How does it work

When the scheduled pipeline is triggered, two primary actions occur:

• A clone of the Support team YAML files occurs
• The bin/sync script runs

This script itself acts a bit differently depending on the Zendesk instance it is tied to

Zendesk Global

1. It fetches the groups of the Zendesk instance.
2. It reads the contents of the Support team YAML files
   • Note it skips select users who should not be in the sync, either because they are not editable (the Owner) or not targets for the sync currently
3. It fetches the user information for each user found in the YAML files via Zendesk
4. It fetches a list of those on PTO (as per the Support - Time Off calendar’s entries)
5. It loops over each agent to compare:
   • The Zendesk user data to the YAML user data, specifically:
     • If the organization they are associated to is GitLab
     • Their name and email
     • Their alias (alternative display name in Zendesk), if they have opted into using one
     • Their signature
     • Their user fields
     • Their tags, derived from:
       • Their current title
       • Who they report to
       • A tag to enable article editing
       • A tag to enable article publishing (if the YAML dictates they should have it)
       • A shift tag (if their working_hours attribute in the YAML files indicates they should have one)
     • Their default group (determined by meeting one of the following criteria, in the order they appear):
       1. BPO for those with an email containing [email protected]
       2. Support AMER for those with a region containing AMER
       3. Support APAC for those with a region containing APAC
       4. Support EMEA for those with a region containing EMEA
       5. General for anyone not meeting the above criteria
   • It compares the user’s current Zendesk group memberships with the groups they should belong to (based on YAML data and default group logic). Groups missing from Zendesk are added; extra groups not in YAML are removed.
6. It then performs updates, using the following API endpoints:
   • User modification
   • Adding a group membership
   • Removing a group membership

Zendesk US Government

1. It fetches the groups of the Zendesk instance.
2. It reads the contents of the Support team YAML files
   • Note it skips select users who should not be in the sync, either because they are not editable (the Owner) or not targets for the sync currently
3. It fetches the user information for each user found in the YAML files via Zendesk
4. It fetches a list of those on PTO (as per the Support - Time Off calendar’s entries)
5. It loops over each agent to compare:
   • The Zendesk user data to the YAML user data, specifically:
     • If the organization they are associated to is GitLab
     • Their name and email
     • Their alias (alternative display name in Zendesk), if they have opted into using one
     • Their signature
     • Their user fields
     • Their tags, derived from:
       • Their current title
       • Who they report to
       • A tag to enable article editing
       • A tag to enable article publishing (if the YAML dictates they should have it)
       • A shift tag (if their group memberships indicate they should have one)
     • Their default group (determined by meeting one of the following criteria, in the order they appear):
       1. General if they have a role of Light agent
       2. Support for anyone not meeting the above criteria
   • It compares the user’s current Zendesk group memberships with the groups they should belong to (based on YAML data and default group logic). Groups missing from Zendesk are added; extra groups not in YAML are removed.
   • Notes if the user is changing their PTO status (i.e. coming back from or leaving for)
6. It then performs updates, using the following API endpoints:
   • User modification
   • Adding a group membership
   • Removing a group membership

Note: Due to the smaller team size in US Government, the sync automatically updates ticket assignees when agents return from or leave for PTO. This courtesy automation is not needed in Global due to the larger team size and existing coverage.

Requesting changes to the sync

To request the changes to the agent sync, please create a Feature Request issue (as it will require manual intervention by the Customer Support Operations team).

Administrator tasks

Modifying the agent sync

To modify the agent sync, you will need to create a MR in the project repo. The exact changes being made will depend on the request itself.

After a peer reviews and approves your MR, you can merge the MR. When the next deployment occurs, it will be synced to Zendesk.

Manually creating an agent

To create an agent in Zendesk:

1. Hover over + Add at the top-left of the page (when not on the admin panel)
2. Click User
3. Fill out the Name
4. Fill out the Email
5. Ensure the User type is that of Staff member
6. Set their Role accordingly
7. Click Add