Systems and records
Dataset role and permission metadata for portable task data
By SourceX Editorial · Updated
10 sections
Short answer
A portable task dataset should state, for every action, who acted as a pseudonymous ID, what kind of actor it was, which roles that actor held at the time of the action, which capability the action used, where the authority came from, and on whose behalf it was done. Ship a role dictionary that maps each source role to portable capabilities, so a buyer can check whether each step was permitted without the supplier's systems.
Provenance trail
Dataset role permission
Key takeaways
- Role values such as agent, admin or a custom profile name only make sense inside the system that defined them, so a package needs its own dictionary.
- Record roles as they were at the time of each event, not as they are on the export date; staff change roles and permissions get edited.
- Separate the actor type (person, service account, automation, AI agent) from the role, and record delegation when one acts for another.
- Approvals and separation of duty are part of the task: a model that never sees a second approver learns that one person can do everything.
- Keep identities pseudonymous and export only the capabilities a task used, not a full map of the supplier's access configuration.
What role and permission context should accompany a portable task dataset?
Every event in a task should say who acted, what kind of actor they were, which roles they held at that moment, which capability the action required, and where that authority came from. Without that context, a buyer training or evaluating an agent sees actions with no sense of whether the actor was allowed to take them, and the model learns to imitate an admin's moves from a junior agent's seat.
Context is the operative word. Task datasets built from ticketing, CRM or ERP histories travel well once they have stable IDs, a manifest and schemas, but authority does not travel by itself. A note that says ticket closed by user 4411 is fine inside the help desk and meaningless in a buyer's training pipeline. The specification below is the minimum that makes permission context portable.
Why does a role name lose its meaning outside the source system?
Because each system defines roles differently and none of them shares a vocabulary. A role field is a label for a bundle of permissions that only the source system can expand.
Three systems show the spread. The Zendesk Users API accepts only end-user, agent or admin as a role, and agents on higher plans can carry a separate custom_role_id that defines what they may do. Salesforce gives each user one profile and any number of permission sets, which can be bundled into permission set groups whose members receive the combined permissions; profiles and permission sets grant access but are not used to deny it. SCIM, the identity provisioning standard, carries roles and entitlements as free-form values with no defined vocabulary and leaves the authorization model to each service provider.
The practical consequence is that you cannot ship the role string alone. A buyer reading agent in one file and Support Tier 1 in another has no way to know whether those actors could issue a refund, change account ownership or delete a record. The package has to carry that expansion itself.
Which actor, role and authority fields belong on every event?
These fields sit on every event, or on an actor-in-event record when an event involves several actors. Field names are suggestions; the semantics are what matter. Observability conventions already point the same way: the OpenTelemetry user.roles attribute is defined as the array of user roles at the time of the event, and it replaced an older single-valued role field.
| Field | Meaning | Format | Example value (illustrative) |
|---|---|---|---|
| actor_ref | Pseudonymous, stable ID for the actor across the package | Opaque string, salted per package | act-7f3c |
| actor_type | What kind of actor performed the action | human, service_account, automation_rule, ai_agent, external_party | human |
| roles_at_event | All roles the actor held when the event happened | List of role_ref values from the role dictionary | support_tier1, billing_viewer |
| capability_used | The specific permission this action required | capability_ref from the dictionary, or unknown | account.owner.change |
| authority_source | How the actor came to hold that capability | role, direct_grant, group_membership, delegation, policy_exception | role |
| on_behalf_of | The actor whose authority was being exercised, if different | actor_ref or empty | act-2b91 |
| approval_ref | Event ID of the approval that authorized this action, if one was required | event_id or empty | evt-0092 |
| role_snapshot_basis | How roles_at_event was established | audit_log, role_history_table, export_date_assumed, inferred | audit_log |
| source_role_values | Raw role strings from the source system, kept verbatim | List of strings | agent; custom role 360004 |
How do you map source roles to portable capabilities?
Ship a separate dictionary file that every event refers to. Each portable role lists the capabilities it grants, the source values it was mapped from, and the date range the mapping is valid for, since permission configurations change. The rows below are invented to show the shape; your capabilities should come from the source system's own permission settings.
Build the dictionary from the system's configuration export or admin screens, not from what people remember about their jobs. List every role value that appears in the task events, expand each into the permissions it carried during the export window, then keep only the capabilities that some task actually used. Give capabilities verb-style names such as ticket.escalate or quote.approve so a buyer can read a step and its required permission together. When a role's permissions changed partway through the window, split it into two dictionary rows with separate validity dates rather than merging them; the merge is exactly the error that makes an old action look unauthorized or a new one look permitted.
| role_ref | Mapped from (source value) | Capabilities granted | Valid for | Mapping note |
|---|---|---|---|---|
| support_tier1 | Zendesk role agent with custom role Tier 1 | ticket.read, ticket.reply, ticket.escalate | Whole export window | Cannot change account owner or issue credits |
| support_admin | Zendesk role admin | ticket.all, account.owner.change, user.role.change | Whole export window | Also holds settings rights not used in any task |
| sales_rep | Salesforce profile Standard User plus permission set Sales Core | opportunity.edit, quote.create | Before mid-year reorganization | Quote approval moved to a group later |
| sales_approver | Salesforce permission set group Deal Desk | quote.approve, discount.override | After mid-year reorganization | Combined permissions of three sets |
| workflow_bot | Integration user running automation rules | ticket.tag, ticket.route | Whole export window | Actions always carry on_behalf_of when triggered by a person |
| unknown_role | No role history available for the period | None asserted | Where role_snapshot_basis is inferred | Buyers should exclude or down-weight these events |
How should delegation, approvals and separation of duty be recorded?
Record who acted for whom and which events authorized which others, because those links are the parts of a task a model most needs to respect. Provenance vocabularies have names for both. W3C PROV-O expresses delegation with actedOnBehalfOf and lets an association between an agent and an activity carry the role the agent played, through a qualified association with hadRole. Object-centric event logs make a similar move: OCEL 2.0 qualifies each event-to-object relationship with the role the object plays in that event.
Separation of duty is the other half. The NIST role-based access control model was designed with separation of duty in mind and distinguishes static constraints, applied when roles are assigned, from dynamic ones, applied to roles activated together in a session; its standard example is that one person should not hold both teller and auditor roles. If a supplier's process required a second person to approve an access change or a discount, the dataset should show the request, the approval by a different actor_ref, and the action that followed, linked by approval_ref.
Automation needs the same treatment. When a rule or bot executes a step because a person clicked a button, record the bot as actor_type automation_rule and the person in on_behalf_of. Otherwise the dataset implies that a service account decided something a human decided.
Worked case (illustrative): an access change that needed a second approver
This case is invented for illustration; it uses counts and times only. A customer asks to transfer account ownership to a colleague. The ticket has seven events across 26 hours and four actors, one of them the workflow bot.
- evt-0090, hour 0: the customer (actor_type external_party) opens the ticket. capability_used is none; the customer has no internal role.
- evt-0091, hour 1: a tier 1 agent (roles_at_event support_tier1) replies and escalates. capability_used ticket.escalate, authority_source role.
- evt-0092, hour 20: an admin (roles_at_event support_admin) approves the transfer after an identity check. This event is the approval; it records no account change itself.
- evt-0093, hour 20: the workflow bot changes the account owner. actor_type automation_rule, capability_used account.owner.change, on_behalf_of the admin's actor_ref, approval_ref evt-0092.
- evt-0094 to evt-0096, hours 21 to 26: the tier 1 agent confirms with the customer and closes the ticket, using ticket.reply only.
- Exception in the same export: in a second ticket the tier 1 agent changed an owner directly because a temporary grant was active for a migration week. That event carries authority_source policy_exception and a note, rather than being silently mapped to support_tier1, which would teach a model that tier 1 can change owners.
Can a buyer verify permissions without the supplier's systems?
Yes, if the package carries the dictionary, a schema for the actor fields and checks that need nothing but the files. These are the checks a buyer should be able to run, and a supplier should run first.
| Check | What it verifies | Result if it fails |
|---|---|---|
| Dictionary coverage | Every role_ref and capability_ref used in events exists in the dictionary | Reject the package |
| Permission consistency | capability_used is granted by at least one role in roles_at_event, or authority_source explains why not | List the events for supplier review |
| Approval linkage | Every approval_ref points to an earlier event by a different actor_ref | Flag a possible separation-of-duty gap |
| Delegation sanity | on_behalf_of never points to the same actor_ref and the delegator held the capability | Flag the event |
| Snapshot basis share | Share of events whose role_snapshot_basis is inferred or export_date_assumed | Report the percentage; buyer decides the threshold |
| Pseudonym stability | One actor_ref per person across all files, and no names or emails anywhere | Reject the package |
| Mapping validity windows | No event uses a role mapping outside its valid-for period | List the events for remapping |
When does dataset role and permission metadata expose too much?
Role context is useful only up to the point where it starts exposing people or security design. Two kinds of overexport are common.
The first is identity. Role histories are attached to employees, so names, emails and usernames should become pseudonymous references before export. The OpenTelemetry conventions flag even a pseudonymous end-user identifier as sensitive, linkable information, which is a reasonable default for any actor_ref: keep the salt out of the package and never reuse it across buyers.
The second is configuration. A buyer needs to know which capability each step used, not the supplier's full permission matrix, admin group names, integration credentials or the list of who can reach which systems. Export the capabilities that appear in tasks and summarize the rest as not exported. Read access to records also does not equal a right to license them; the supplier still needs a rights review before any of this leaves the building.
What if role history is missing or access was rule-based?
Stop and narrow the scope when the source cannot tell you who held which role at the time. Many systems keep only current role assignments, so a staff member promoted last spring appears as an admin for every ticket they ever touched. If role history is missing for a period, mark role_snapshot_basis as export_date_assumed or inferred and let the buyer exclude those events, rather than presenting a guess as fact.
Attribute-based rules are the other limit. When access depended on conditions such as region, account tier or time of day rather than roles, a role dictionary will understate what decided the outcome. Record the condition as an authority_source of policy and a short description, and bring in the supplier's identity administrator to confirm the mapping before the package is shipped.
How should a data request specify role context?
If you are buying task data, write the actor fields, the dictionary and the validator checks into the request so the supplier knows role context is part of the deliverable rather than an afterthought. Task datasets are not held in stock at SourceX: they are sourced from U.S. businesses on request, and the request form's fields for scope, volume, language, format, timing and licensing needs are where a role and permission specification like this one should go.
Frequently asked questions
What should an actor role and authority metadata specification include?
Per event: a pseudonymous actor ID, actor type, roles held at the time, the capability the action used, the source of that authority, any delegation and a link to the approving event. Alongside it, a role dictionary mapping source role values to portable capabilities with validity dates.
Why not just export the role field from the source system?
Because role values are labels that only the source system can expand. A Zendesk agent with a custom role, a Salesforce user with several permission sets and a SCIM role string all need a dictionary before a buyer can tell what each actor was allowed to do.
Should roles reflect the export date or the event date?
The event date. People change roles and permission settings get edited, so current assignments misstate past authority. When history is missing, label the basis as assumed or inferred instead of presenting it as fact.
How should bots and AI agents appear in role metadata?
Give them their own actor type, list the capabilities their service account used, and record on whose behalf they acted when a person triggered them. That keeps automated steps from looking like independent decisions.
Does role metadata create privacy risk?
It can, because role histories describe employees. Replace names and emails with salted pseudonymous IDs, keep the salt out of the package, and export only the capabilities used in tasks rather than the full access configuration.
Sources
- The OpenTelemetry user.roles attribute is defined as the array of user roles at the time of the event. Source
- OpenTelemetry marks enduser.pseudo.id as sensitive, linkable personal information. Source
- The Zendesk Users API role accepts end-user, agent or admin, with custom_role_id for agents on eligible plans. Source
- Salesforce permission set groups give members the combined permissions of the sets they contain. Source
- SCIM roles and entitlements have no defined vocabulary, and the core schema leaves the authorization model to the service provider. Source
- NIST's RBAC model was designed with separation of duty in mind and distinguishes static and dynamic separation of duty. Source
- PROV-O expresses delegation with actedOnBehalfOf and the role an agent played with a qualified association and hadRole. Source
- OCEL 2.0 qualifies each event-to-object relationship with the role the object plays in the event. Source
Tell us what data you need
Share scope, volume, format, timing and licensing needs. Datasets are sourced on request.