Recipe: Assignment Control app for App Builder

Problem Statement

The Assignment Control app is a ticket sidebar application that provides targeted visibility controls for the ticket assignee dropdown. It dynamically hides specific agents and groups based on configurable targeting rules, such as the current agent's role, group membership, ticket attributes etc.

Prompt

Create a ticket_sidebar app called "Assignment Control" that hides specific agents and groups from the ticket assignee dropdown, based on whether the current agent matches configurable targeting rules.

Define six app parameters in the manifest so they appear on the app's installation settings screen (all type: text, all optional):

• `hidden_user_ids` — labelled "Hidden users". Help text: "A comma-separated list of user IDs to be hidden from the Assignee dropdown."
• `hidden_group_ids` — labelled "Hidden groups". Help text: "A comma-separated list of group IDs to be hidden from the Assignee dropdown."
• `targeted_user_ids` — labelled "Targeted users". Help text: "A comma-separated list of user IDs that are targeted to have assignees hidden."
• `targeted_user_tags` — labelled "Targeted user tags". Help text: "A comma-separated list of user tags that are targeted to have assignees hidden."
• `targeted_organization_ids` — labelled "Targeted organizations". Help text: "A comma-separated list of organization IDs that are targeted to have assignees hidden."
• `targeted_group_ids` — labelled "Targeted groups". Help text: "A comma-separated list of group IDs that are targeted to have assignees hidden."

Read these at runtime via the app registration event metadata at `metadata.settings`.

1. On load, invoke `zafClient.invoke('hide')` to hide the app from the sidebar UI.
2. On load, first call `zafClient.get('currentUser.organizations')` to prime the organizations data, then call `zafClient.get('currentUser')` to get the full current user object including `id`, `tags`, `organizations` (array of objects with `id`), and `groups` (array of objects with `id`).
3. Parse each "targeted" setting by splitting on commas, trimming whitespace, and filtering out empty strings. Ignore settings that are empty or not configured. Determine if the current user is targeted by checking if ANY of these conditions is true: their user ID (converted to a string via `String(id)`) is in `targeted_user_ids`, any of their tags is in `targeted_user_tags`, any of their organization IDs (converted to strings) is in `targeted_organization_ids`, or any of their group IDs (converted to strings) is in `targeted_group_ids`. If no targeted settings are configured or none match, display "Assignment Control — not active for your account" and stop.
4. If the current user IS targeted, fetch the assignee field by calling `zafClient.get('ticketFields:assignee')`. IMPORTANT: the string `ticketFields:assignee` uses a colon between `ticketFields` and `assignee` — this is ZAF SDK ticket field syntax, not a dot. The response is an object keyed by the exact string `ticketFields:assignee`, so you MUST access it with bracket notation: `response['ticketFields:assignee']`. From that object, read `optionGroups` (array) and `optionValues` (array).
5. Parse `hidden_group_ids` as a comma-separated trimmed list (filter out empty strings). For each entry in the `optionGroups` array, its `value` property is a string in the format `"groupId:userId"`. Split on `:` and take the first segment as the group ID. If that group ID is in the hidden list, call `zafClient.invoke('ticketFields:assignee.optionGroups.{index}.hide')` where `{index}` is that entry's numeric index in the array. Note: the invoke path uses a colon between `ticketFields` and `assignee` and dots for the rest — for example `ticketFields:assignee.optionGroups.0.hide`.
6. Parse `hidden_user_ids` as a comma-separated trimmed list (filter out empty strings). For each entry in the `optionValues` array, its `value` property is a string in the format `"groupId:userId"`. Split on `:` and take the second segment as the user ID. If the second segment is missing, treat it as an empty string and skip. If that user ID is in the hidden list, call `zafClient.invoke('ticketFields:assignee.optionValues.{index}.hide')` where `{index}` is that entry's numeric index in the array. Same colon syntax: `ticketFields:assignee.optionValues.0.hide`.
7. Listen for the event `ticketFields.assignee.optionValues.changed` via `zafClient.on()` (note: the event name uses dots, not colons). When this event fires, re-run steps 4–6 to re-apply hiding, because the available assignees change when the ticket's group changes.

Enhancement Options

Based on your organizational needs, you can extend the Assignment Control app to support your specific needs using App Builder.

Important Note: This app recipe is for the Assignment Control app. Any modifications to the recipe or its underlying logic may alter the core functionality of the app. Thoroughly test all changes in a non-production environment before deploying to your production workspace.

Please note: that as App Builder evolves including updates to underlying AI models, design components, and other dependencies, we cannot guarantee that this recipe will continue to function as expected over time. We recommend periodically validating the recipe against any platform updates.