Interface SecurityControls

Name-based role assignment via sys_agent_access_role_mapping (M2M).

Accepts:

• Role name strings for OOB or platform roles (e.g., 'admin', 'itil').
• Role objects for custom roles defined by this app via Role({ name, ... }).
• DbRecord<'sys_user_role'> references via Record({ table: 'sys_user_role', data: { name } }).

Each entry is emitted as a platform-resolvable reference — the target instance's coalesce logic resolves the role's name to the correct sys_id. This makes roleMap cross-instance safe even when role sys_ids differ across instances. Requires ZP10 / AP3+.

Note: DbRecord<'sys_user_role'> cannot carry sys_id-only data (TypeScript rejects data: { sys_id: ... } because sys_id is not in Data<'sys_user_role'>). Users must provide name (or another coalesce key column) in data.

Sys_id-based references go to roleRestrictions instead. At least one of roleRestrictions or roleMap must contain a role.

Role Restrictions — role assignment via the legacy role_list column on sys_agent_access_role_configuration. Roles resolve to sys_ids at build time and are stored as a comma-joined sys_id list.

Accepts:

• Role sys_id strings (GUIDs) — pushed directly into role_list.
• Role objects — Role({ $id, name, ... }). The role's build-time sys_id is resolved by the SDK keys registry and stored.
• DbRecord<'sys_user_role'> references — resolved to the referenced record's sys_id at build time.

Not accepted: plain string role names (e.g., 'admin', 'itil'). Use roleMap for name-based authoring — that path resolves names to sys_ids on the target instance at install time, which is cross-instance safe. roleRestrictions only stores literal sys_ids and is intended for:

• Backward compatibility with pre-ZP10 / pre-AP3 customer instances (which lack the sys_agent_access_role_mapping M2M table).
• Cases where customer instances are cloned from a common production baseline so role sys_ids match across all targets.

Either roleRestrictions or roleMap (or both) must contain at least one role — the build fails with a diagnostic otherwise.

User Access - Define who can access and interact with this skill

Type system enforces either 'authenticated' OR roles (not both) Creates sys_security_acl (gen_ai_skill type) and sys_security_acl_role records Automatically adds display_value attributes to generated XML

For authenticated users (any logged-in user):

userAccess: {
    type: 'authenticated'
}
Copy

For specific roles using role NAMES (RECOMMENDED - easier!):

userAccess: {
    type: 'roles',
    roles: ['admin', 'itil']  // Role names - automatically resolved
}
Copy

Or using sys_ids:

userAccess: {
    type: 'roles',
    roles: ['2831a114dbde1340d7d8a33be399c100']  // admin role sys_id
}
Copy