here is a complete diagnostic checklist of everything that needs to be right simultaneously for this to work.
The Full Configuration Checklist
Step 1 — Table Attribute (Most commonly missed detail)
Navigate to your table's dictionary entry — not the field dictionary, the collection entry (the one with type = Collection).
- Open it in Advanced View
- In the Attributes field add exactly:
email_client=true
- If there are other attributes already there, append with a comma:
other_attr=value,email_client=true
⚠️ This must be on the collection-level dictionary entry of your specific table, not inherited from Task. Even though your table extends Task, this attribute needs to be explicitly set on your table's own collection entry.
Step 2 — UX Screen Record (sys_ux_screen)
Navigate to sys_ux_screen.list and verify every field matches this exactly:
| Field |
Required Value |
| Name |
anything descriptive |
| Screen Collection |
Record (from your app's scope — add the Application column to confirm) |
| Screen Condition |
table=sys_email_draft |
| Page Definition |
Compose email (not "Draft email", not "Email preview") |
| Parent Macroponent |
Workspace App Shell |
| Active |
✅ checked |
The two most common errors here are:
- Picking the wrong Screen Collection — there are multiple "Record" entries across different scopes. You need the one belonging to your workspace's application scope specifically
- Picking the wrong Page Definition — "Draft Email" and "Compose email" are different entries and only "Compose email" gives you the full composer UI
Step 3 — Workspace App Shell Scope Alignment
Your UX Screen's Parent Macroponent must point to the Workspace App Shell that is actually used by your custom workspace — not a global one or one from a different app.
To verify: open your workspace in UI Builder → check which App Shell macroponent it references → confirm the sys_id matches what you selected in the UX Screen.
Step 4 — Compose Email UI Action Visibility
The global Compose Email UI action (on the task table) checks for email_client=true in the table attributes before rendering. If Step 1 is correct, the button should appear. If you already see the button but get the wrong page, the issue is exclusively in Steps 2–3.
Step 5 — Cache / Update Set scope
If you made all these changes and it still doesn't work:
- Run
cache.do to flush the instance cache
- Confirm the
sys_ux_screen record is in the correct application scope (same scope as your workspace) and not accidentally in Global
Most Likely Culprit Given Your Description
Since you said the button appears but you get a different page rather than no button at all, Step 1 is probably fine. The fact that the wrong page opens points squarely at one of these two things in your UX Screen record:
- Wrong Screen Collection — you picked a "Record" collection from the wrong scope, so the routing rule isn't being evaluated by your workspace's shell
- Wrong Page Definition — "Draft Email" page was selected instead of "Compose email"
Check those two fields first and that should resolve it.
