[[{“value”:”
Introduction
This post is part of a series on extending SAP Joule with custom capabilities by using Joule Studio CLI. If you are new to Joule capability development or need help setting up your environment, start with Building Custom Joule Capabilities: Getting Started.
Assume you’ve built your first Joule capability which includes scenarios such as one functionality to return salary information. The scenarios are well-described, the functions return useful data, and everything works in your test environment. Then someone from HR asks: “Wait, can every employee see the salary report scenario when they talk to Joule?”
That’s the moment the most people realize they need access control.
The problem is straightforward: in a customized Joule capability developed using Joule Studio CLI every scenario is visible to every end user. That’s fine for general-purpose skills, but the moment you’re surfacing sensitive data (compensation figures, financial forecasts, headcount plans, performance ratings) you need to ensure that Joule only presents those scenarios to the people authorized to use them.
The solution is visibility_condition, a declarative field you add directly to a scenario YAML. When a user sends a message to Joule, the platform evaluates each scenario’s visibility condition against the user’s identity token before even considering whether the scenario matches the intent. If the condition evaluates to false, the scenario is completely invisible to that user. It won’t match, it won’t respond, and it won’t appear in any suggestions.
In this post, you’ll build a small HR capability with two scenarios: one that any employee can access (general HR information like office locations and holiday schedules), and one restricted to members of an IAS group called HR_Managers (salary reports and compensation data). By the end, you’ll understand exactly how to gate any scenario behind group membership, and you’ll know the full range of attributes you can use to build more sophisticated access patterns.
Note: The complete source for this capability, along with all other examples from this series, is available on GitHub.
How Visibility Conditions Work
Before writing any YAML, it’s worth understanding what Joule actually does with a visibility_condition at runtime.
When a user sends a message, Joule’s orchestration layer retrieves the user’s IAS identity token. It then iterates over all scenarios registered in the active capability deployment and evaluates each scenario’s visibility_condition against the token. Scenarios that pass the condition (or have no condition at all) are added to the candidate pool for intent matching. Scenarios that fail are dropped entirely. They don’t participate in matching, and the user has no indication they exist.
This means the access control is enforced before any LLM-based intent matching happens. You’re not relying on the model to “know” not to use a restricted scenario. The scenario is structurally unavailable.
The default behavior (no visibility_condition field) is equivalent to always visible. Any scenario without this field is included in the candidate pool for every user.
Joule currently supports two condition object types:
ibn_targets: Gates a scenario on SAP Work Zone navigation targets. Useful for capabilities that should only appear when the user has access to a specific Work Zone application or tile.ias_attributes: Gates a scenario on attributes present in the user’s IAS identity token. This is the focus of this post.
For most access control use cases, ias_attributes is what you want. It reads directly from the identity token that IAS issues when the user authenticates, which means it reflects your authoritative identity system with no additional configuration required on the Joule side.
Prerequisites
This post assumes you have the Joule CLI installed and the other prerequisites mentioned in the overview blog post. If you haven’t done that yet, start with the first blog post in this series, which covers CLI installation, BTP subaccount configuration, and your first deployment end-to-end.
For this walkthrough specifically, you’ll need:
- IAS admin access in the tenant connected to your Joule deployment. You need permission to create groups and assign users.
- Two test user accounts: one that you’ll add to the
HR_Managersgroup (your “HR Manager” persona), and one that you’ll leave unassigned (your “regular employee” persona). These users should’ve access to the end_user BTP Role to be able to access Joule itself. - The Joule CLI authenticated and pointed at your development subaccount.
Step 1: Configure IAS Groups
IAS group membership is the attribute we’ll use to gate the salary scenario. Before writing any YAML, set up the group and assign your test user.
Log in to your IAS admin console at https://<your-tenant>.accounts.ondemand.com/admin. Navigate to Applications & Resources in the left-hand menu, then select Groups.
Click Create and fill in the group name exactly as HR_MANAGERS. The name is case-sensitive. The value in your scenario YAML must match it precisely. Add a description and save.
Next, create your HR Manager test user. Navigate to Users & Authorizations > User Management and click Add User. Fill in the details and set the email to whatever address you want to use for testing.
Important for fictive email addresses: When creating a test user with a made-up email address, make sure to select Set initial password rather than Send activation email. An activation email sent to a non-existent address will never arrive, and the account will be stuck in an unactivated state.
After the user logs in for the first time, IAS will prompt them to set a new password. Once they do, IAS sends a verification email to the address on file. For a fictive address this will never arrive, leaving the account in an unverified state that can cause login issues. To work around this, go back to the user’s profile in the IAS admin console and check Verify Email directly. This marks the email address as verified without sending any email.
With the user created, open their profile and go to the Groups tab. Click Add and assign them to HR_MANAGERS. Save the changes.
If you’d rather not create a second user at all, you can assign the HR_MANAGERS group to your own IAS user account instead. That lets you test the restricted scenario directly without managing a separate persona. To test the regular employee path, simply remove yourself from the group and log back in.
Leave your regular employee test user with no group assignment. You don’t need to do anything to “deny” access. The absence of the group membership is sufficient. The visibility condition will evaluate to false for any user not in the listed group.
One important note: IAS group membership is reflected in the identity token that gets issued at login time. If you assign a user to a group while they have an active session, they may need to log out and log back in before the change takes effect in Joule. Keep this in mind when you’re testing.
Step 2: The Capability File
The capability file is minimal. We have two scenarios and two functions, and since both functions use simple message actions (no external system calls), we don’t need any system_aliases. This keeps the focus squarely on the access control pattern.
schema_version: 3.27.0
metadata:
namespace: joule.ext
name: hr_reports_capability
version: 1.0.0
display_name: HR Reports
description: Demonstrates role-based scenario access using IAS group attributes
The namespace: joule.ext marks this as an extension capability to be able to be deployed to the unified central Joule instance (sap_digital_assistant).
Note that the schema version is 3.27.0. If you’re on an older version of the CLI and it complains, you can lower this. Just make sure you’re not below 3.23.0 if you want to use sap_licenses as an attribute, or below 3.15.0 if you want to combine ias_attributes with ibn_targets conditions.
Step 3: The Public Scenario
The public scenario has no visibility_condition, which means it’s included in the candidate pool for every user regardless of their identity attributes.
description: >
Get general HR information including company policies, office locations,
and the annual holiday schedule for all employees.
target:
name: public_info
type: function
The description field is the primary input to Joule’s intent matching. Write it as a natural-language description of what a user would ask to trigger this scenario. Joule compares the user’s message against this description semantically, so be specific about the kinds of questions it handles. Something like “company policies, office locations, and the annual holiday schedule” gives the model clear signal about what belongs here.
The target points to the public_info function by name.
Any end user can ask Joule about holiday schedules, office locations, or company policies, and this scenario will be available to match their intent.
Step 4: The Restricted Scenario: Deep Dive
The restricted scenario is where the interesting work happens. Here’s the full YAML:
description: >
Access salary reports and compensation data. Retrieve team salary
summaries and compensation benchmarks for your department.
visibility_condition:
objects:
– type: ias_attributes
attributes:
– attribute: groups
match: ANY
values:
– HR_MANAGERS
target:
name: restricted_info
type: function
Let’s walk through every field in the visibility_condition block.
visibility_condition.objects is an array. This design allows you to specify multiple condition objects in a single scenario. When you provide more than one object, all of them must evaluate to true for the scenario to be visible. It’s an implicit AND across objects. This is how you build compound conditions like “user must be in the HR_Managers group AND have a specific Work Zone navigation target available.”
type: ias_attributes tells Joule to evaluate this condition against the attributes in the user’s IAS identity token. IAS embeds user attributes (including group memberships) into the JWT it issues at authentication time.
attribute: groups specifies which IAS attribute to check. The groups attribute contains the list of IAS groups the authenticated user belongs to. This is the most common attribute to use for role-based access control.
match: ANY controls how the user’s attribute value is compared against the values list. With ANY, the condition evaluates to true if the user belongs to at least one of the listed groups. The alternative is match: ALL, which requires the user to be a member of every group in the values list. Use ALL when you need compound group requirements, for example “must be in both HR_MANAGERS and Senior_Staff.”
values is the list of IAS group names to check against. In this case, it’s a single group: HR_MANAGERS. You can add multiple group names here and combine them with match: ANY to grant access to users from any of several groups. This is useful when different teams or roles should all have access to the same sensitive scenario.
Supported attributes for ias_attributes:
groups: IAS group membership (the most common use case)email: IAS emailuser_uuid: the unique identifier of the specific user, useful for individual-level access. This GUID can be found in IAS when viewing the user.- Custom attributes: any custom attribute you’ve configured in IAS for your users
sap_licenses: SAP product license assignments (available since schema version 3.23.0); enables license-based feature gating
Step 5: The Dialog Functions
Both functions in this example use simple message actions. In a real capability, these would call APIs, run queries, or invoke more complex action chains. Here we keep them simple so the focus stays on the visibility pattern rather than the function implementation.
The public function:
action_groups:
– actions:
– type: message
message:
type: text
content: >
Here is the general HR information you requested. Our company
policies are available on the HR portal. Office locations include
our headquarters and regional offices. The annual holiday schedule
has been published for this year.
The restricted function:
action_groups:
– actions:
– type: message
message:
type: text
content: >
Here are the salary reports for your team. The compensation
summary shows current salary bands and recent adjustments.
This information is confidential and restricted to HR Managers.
Both functions follow the same structure: a single action_groups entry containing a single actions list with one message action of type text. The content field contains the response Joule will deliver when the function is invoked.
In production, you’d replace these static messages with api-request actions that call your actual HR APIs. The visibility_condition on the scenario works identically regardless of how complex the downstream function becomes. The access gate is enforced at the scenario layer, before the function is ever invoked.
Step 6: Deploy and Test
Your directory structure should look like this before deploying:
├── da.sapdas.yaml
└── capabilities/role_based_access/
├── capability.sapdas.yaml
├── scenarios/
│ ├── public_scenario.yaml
│ └── restricted_scenario.yaml
└── functions/
├── public_info.yaml
└── restricted_info.yaml
First, run the linter to catch any structural issues:
joule lint
Fix any errors before proceeding.
Deploy the capability:
joule deploy -c -n “hr_reports_test”
The -c flag compiles, and -n provides the assistant name. Once the deployment completes, launch it in Joule:
joule launch “hr_reports_test”
Test 1: HR Manager user: Log in to Joule as your HR Manager test user (the one assigned to the HR_Managers group in IAS). Ask something like: “Can you show me salary reports for my team?”
Joule should match the restricted scenario and return the salary report message. Both scenarios are in the candidate pool for this user, and the intent of the question clearly maps to the restricted scenario’s description.
Test 2: Regular employee: Log out and log back in as your regular employee test user (not in HR_MANAGERS). Ask the same question: “Can you show me salary reports for my team?”
Joule should respond that it can’t help with that request, or may return a generic fallback. The restricted scenario is not in the candidate pool at all for this user. Even if the intent perfectly matches the restricted scenario’s description, Joule cannot select it.
Try asking about office locations and holiday schedules with both users. The public scenario should work identically for both.
Advanced Patterns
The example above covers the most common case (single group, ANY match) but visibility conditions support more sophisticated patterns.
Multiple groups with ANY match: Add additional group names to the values array to grant access to users from any of those groups. For example, granting access to both HR_Managers and Finance_Directors requires only adding Finance_Directors to the values list.
ALL match for compound group requirements: Change match: ANY to match: ALL when a user must belong to every group in the list.
Individual user access with user_uuid: Replace attribute: groups with attribute: user_uuid and provide specific user UUIDs in the values list. This pins scenario access to named individuals, which is useful for capability owners or designated testers.
Email-based access with email: Use attribute: email with specific email addresses in the values list as an alternative to user_uuid when you want to identify individuals by a more readable identifier. This is handy for small allowlists where maintaining a list of UUIDs would be impractical.
Combining multiple attributes within ias_attributes: You can list multiple attributes entries inside a single ias_attributes object. When you do this, all of them must evaluate to true for the scenario to be visible. This is an AND condition, not an OR. In the example below, a user must both belong to the HR_MANAGERS group and have the specific email address. Meeting only one of the two conditions is not enough:
visibility_condition:
objects:
– type: ias_attributes
attributes:
– attribute: groups
match: ANY
values:
– HR_MANAGERS
– attribute: email
match: ANY
values:
– hrmanager@jouledev.com
License-based gating with sap_licenses (schema version 3.23.0+): Use attribute: sap_licenses to gate scenarios based on which SAP product licenses a user holds.
Combining ias_attributes with ibn_targets (schema version 3.15.0+): Add a second object to the visibility_condition.objects array with type: ibn_targets to require both group membership and Work Zone navigation target availability. Since all objects in the array must evaluate to true, this creates an AND condition across the two types.
Conclusion
The visibility_condition field gives you a declarative, zero-code mechanism for controlling which users can access which scenarios in your Joule capability. The access control lives entirely in the scenario YAML. There’s no conditional logic in your function code, no middleware to configure, and the only changes required are to your IAS configuration (for example, creating groups).
The key points to take away:
- Scenarios with no
visibility_conditionare always visible to all end users ias_attributesreads directly from the IAS identity token at runtimematch: ANYgrants access if the user is in at least one listed group;match: ALLrequires membership in every listed group
In the next post in this series, we’ll look at document grounding: connecting Joule to enterprise document repositories so responses are grounded in your organization’s actual content.
“}]]
metadata:
namespace: joule.ext
name: hr_reports_capability
version: 1.0.0
display_name: HR Reports
description: Demonstrates role-based scenario access using IAS group attributesThe namespace: joule.ext marks this as an extension capability to be able to be deployed to the unified central Joule instance (sap_digital_assistant).Note that the schema version is 3.27.0. If you’re on an older version of the CLI and it complains, you can lower this. Just make sure you’re not below 3.23.0 if you want to use sap_licenses as an attribute, or below 3.15.0 if you want to combine ias_attributes with ibn_targets conditions. Step 3: The Public ScenarioThe public scenario has no visibility_condition, which means it’s included in the candidate pool for every user regardless of their identity attributes.description: >
Get general HR information including company policies, office locations,
and the annual holiday schedule for all employees.
target:
name: public_info
type: functionThe description field is the primary input to Joule’s intent matching. Write it as a natural-language description of what a user would ask to trigger this scenario. Joule compares the user’s message against this description semantically, so be specific about the kinds of questions it handles. Something like “company policies, office locations, and the annual holiday schedule” gives the model clear signal about what belongs here.The target points to the public_info function by name. Any end user can ask Joule about holiday schedules, office locations, or company policies, and this scenario will be available to match their intent. Step 4: The Restricted Scenario: Deep DiveThe restricted scenario is where the interesting work happens. Here’s the full YAML:description: >
Access salary reports and compensation data. Retrieve team salary
summaries and compensation benchmarks for your department.
visibility_condition:
objects:
– type: ias_attributes
attributes:
– attribute: groups
match: ANY
values:
– HR_MANAGERS
target:
name: restricted_info
type: functionLet’s walk through every field in the visibility_condition block.visibility_condition.objects is an array. This design allows you to specify multiple condition objects in a single scenario. When you provide more than one object, all of them must evaluate to true for the scenario to be visible. It’s an implicit AND across objects. This is how you build compound conditions like “user must be in the HR_Managers group AND have a specific Work Zone navigation target available.”type: ias_attributes tells Joule to evaluate this condition against the attributes in the user’s IAS identity token. IAS embeds user attributes (including group memberships) into the JWT it issues at authentication time.attribute: groups specifies which IAS attribute to check. The groups attribute contains the list of IAS groups the authenticated user belongs to. This is the most common attribute to use for role-based access control.match: ANY controls how the user’s attribute value is compared against the values list. With ANY, the condition evaluates to true if the user belongs to at least one of the listed groups. The alternative is match: ALL, which requires the user to be a member of every group in the values list. Use ALL when you need compound group requirements, for example “must be in both HR_MANAGERS and Senior_Staff.”values is the list of IAS group names to check against. In this case, it’s a single group: HR_MANAGERS. You can add multiple group names here and combine them with match: ANY to grant access to users from any of several groups. This is useful when different teams or roles should all have access to the same sensitive scenario.Supported attributes for ias_attributes:groups: IAS group membership (the most common use case)email: IAS emailuser_uuid: the unique identifier of the specific user, useful for individual-level access. This GUID can be found in IAS when viewing the user.Custom attributes: any custom attribute you’ve configured in IAS for your userssap_licenses: SAP product license assignments (available since schema version 3.23.0); enables license-based feature gating Step 5: The Dialog FunctionsBoth functions in this example use simple message actions. In a real capability, these would call APIs, run queries, or invoke more complex action chains. Here we keep them simple so the focus stays on the visibility pattern rather than the function implementation.The public function:action_groups:
– actions:
– type: message
message:
type: text
content: >
Here is the general HR information you requested. Our company
policies are available on the HR portal. Office locations include
our headquarters and regional offices. The annual holiday schedule
has been published for this year.The restricted function:action_groups:
– actions:
– type: message
message:
type: text
content: >
Here are the salary reports for your team. The compensation
summary shows current salary bands and recent adjustments.
This information is confidential and restricted to HR Managers.Both functions follow the same structure: a single action_groups entry containing a single actions list with one message action of type text. The content field contains the response Joule will deliver when the function is invoked.In production, you’d replace these static messages with api-request actions that call your actual HR APIs. The visibility_condition on the scenario works identically regardless of how complex the downstream function becomes. The access gate is enforced at the scenario layer, before the function is ever invoked. Step 6: Deploy and TestYour directory structure should look like this before deploying:├── da.sapdas.yaml
└── capabilities/role_based_access/
├── capability.sapdas.yaml
├── scenarios/
│ ├── public_scenario.yaml
│ └── restricted_scenario.yaml
└── functions/
├── public_info.yaml
└── restricted_info.yamlFirst, run the linter to catch any structural issues:joule lintFix any errors before proceeding.Deploy the capability:joule deploy -c -n “hr_reports_test”The -c flag compiles, and -n provides the assistant name. Once the deployment completes, launch it in Joule:joule launch “hr_reports_test”Test 1: HR Manager user: Log in to Joule as your HR Manager test user (the one assigned to the HR_Managers group in IAS). Ask something like: “Can you show me salary reports for my team?”Joule should match the restricted scenario and return the salary report message. Both scenarios are in the candidate pool for this user, and the intent of the question clearly maps to the restricted scenario’s description.Test 2: Regular employee: Log out and log back in as your regular employee test user (not in HR_MANAGERS). Ask the same question: “Can you show me salary reports for my team?”Joule should respond that it can’t help with that request, or may return a generic fallback. The restricted scenario is not in the candidate pool at all for this user. Even if the intent perfectly matches the restricted scenario’s description, Joule cannot select it.Try asking about office locations and holiday schedules with both users. The public scenario should work identically for both. Advanced PatternsThe example above covers the most common case (single group, ANY match) but visibility conditions support more sophisticated patterns.Multiple groups with ANY match: Add additional group names to the values array to grant access to users from any of those groups. For example, granting access to both HR_Managers and Finance_Directors requires only adding Finance_Directors to the values list.ALL match for compound group requirements: Change match: ANY to match: ALL when a user must belong to every group in the list.Individual user access with user_uuid: Replace attribute: groups with attribute: user_uuid and provide specific user UUIDs in the values list. This pins scenario access to named individuals, which is useful for capability owners or designated testers.Email-based access with email: Use attribute: email with specific email addresses in the values list as an alternative to user_uuid when you want to identify individuals by a more readable identifier. This is handy for small allowlists where maintaining a list of UUIDs would be impractical.Combining multiple attributes within ias_attributes: You can list multiple attributes entries inside a single ias_attributes object. When you do this, all of them must evaluate to true for the scenario to be visible. This is an AND condition, not an OR. In the example below, a user must both belong to the HR_MANAGERS group and have the specific email address. Meeting only one of the two conditions is not enough:visibility_condition:
objects:
– type: ias_attributes
attributes:
– attribute: groups
match: ANY
values:
– HR_MANAGERS
– attribute: email
match: ANY
values:
– hrmanager@jouledev.comLicense-based gating with sap_licenses (schema version 3.23.0+): Use attribute: sap_licenses to gate scenarios based on which SAP product licenses a user holds.Combining ias_attributes with ibn_targets (schema version 3.15.0+): Add a second object to the visibility_condition.objects array with type: ibn_targets to require both group membership and Work Zone navigation target availability. Since all objects in the array must evaluate to true, this creates an AND condition across the two types. ConclusionThe visibility_condition field gives you a declarative, zero-code mechanism for controlling which users can access which scenarios in your Joule capability. The access control lives entirely in the scenario YAML. There’s no conditional logic in your function code, no middleware to configure, and the only changes required are to your IAS configuration (for example, creating groups).The key points to take away:Scenarios with no visibility_condition are always visible to all end usersias_attributes reads directly from the IAS identity token at runtimematch: ANY grants access if the user is in at least one listed group; match: ALL requires membership in every listed groupIn the next post in this series, we’ll look at document grounding: connecting Joule to enterprise document repositories so responses are grounded in your organization’s actual content.”}]] Read More Technology Blog Posts by SAP articles
#SAPCHANNEL