Roles, Permissions, and Access Controls

Overview of Aisera Roles and Permissions

There are several levels of Aisera permissions. Before you can begin setting up roles, it is important to understand the different versions of the Aisera Admin UI that affect how permissions are granted.

Each User Role has a permission value, so you can assign roles to users with out-of-the-box functionality.

In addition, you can control permissions at the tenant level or at the application level, using the Access Control feature.

This topic includes the following sections: Aisera Admin UI Versions

User-level Permissions

Tenant-level Permissions

Application-level Permissions

Content-level Permissions (ACLs per Knowledge Article)

Third Party APIs

IMPORTANT!: When you create roles and permissions, it is a best practice to document the reasons with examples of each role and permission you created. Although you can see the permissions in the UI, it may be difficult for you to determine where a specific restriction is coming from.

Understanding Aisera Admin UI Versions

If you have Administrator privileges, you can manage Roles and Permissions using the Aisera Administration application (Aisera Admin UI).

Permissions for each Role in the Aisera platform are based on the type of Aisera Administration application you’re using, and the Entity Types that your application has access to.

Entity Types refer to Aisera objects. These are items like Intents, Fulfillments, Tickets, and Data Sources that you interact with in either the embedded application (bot) you’re creating, or within the Aisera Administration application.

The User Role, the Entity Types available to that role, and the permissions on each of the Entity Types, determine the entities that you will see on windows within the application. Privilege levels for the entities are: Read, Write (Read and Write), or None..

For instance, if your User Role is excluded from accessing the Intents Entity Type (object), then you will not see any Intents values or information when you look at windows within the Aisera Administration application. If your role only has Read privileges for the Intent entity, then you will be able to see (but not change) Intent data within a window.

Variations of the Aisera Administration Application

The three main variations of the Aisera Administration application are:

• AI Service Desk

• AI Customer Service Desk

• AI Ops

Both of the Administration Application configurations have access to the following Common Entity Types (objects):

• User

• Ticket

• Datasource

• Channel

• Integration

• Flow

• System Trigger

• JobExecution

• Settings

• Audit

• Email Template

• Model

• ModelJob

• TenantUser

Each of the Administration configurations has access to specific additional entity types.

• AI Service Desk

  • Request

  • Application

  • EzType

  • EzEntiity

  • Knowledge

  • AccessAttribute

  • Intent

  • Conversation Message

  • IntentUtteranceRevision

  • DirectEscalation

• AI Customer Service Desk

  • Request

  • Application

  • EzType

  • EzEntity

  • Knowledge

  • AccessAttribute

  • Intent

  • Conversation Message

  • IntentUtteranceRevision

• AI Ops

  • MajorIncident

  • AiseraAlert

  • CmdbCi

As you can see, the AI Service Desk and AI Customer Service Desk are similar configurations.

Using the Default Roles

The Aisera application (out-of-the-box) roles are designed to operate with the correct permission levels for most of the Aisera Administration and embedded applications. You can create custom roles, as described below, but this is not a common use case.

Each of the Administration configurations has the following default roles.

Default Role Descriptions

The following tables give you an idea of permission levels for each role per entity type and application variation.

Read and Write for Entity Types

The following table describes how the Read and Write privileges work within the Entity Types.

Aisera Entities and Related Windows

This section describes the usable Aisera Entities and the views you see related to them in the Aisera Administration Application (Admin UI).

See ExEntity above.

Role Permissions Tables

This determines the views you can see and the fields you can interact with while acting within a specific role.

User Level Permissions

If you have been assigned to an Administrator role in the Aisera Administration application, you can assign any of the default (out-of-the-box) application roles to new users.

Assigning Roles to Users

1. Open Settings > User Accounts from the left navigation menu of the Aisera Administration application.

2. Choose the + New User Account button.

3. Enter the email address and the name of the New User.

   
4. Select the checkbox next to the role that you want this user to have, based on the actions that this user will perform within your organization or within the Aisera Administration application (Admin UI) .

Changing a User’s Role

To change the Role for an Existing User:

1. Select Settings > User Accounts from the left navigation menu of the Aisera Administration application.

2. The User Account window contains a list of current users.

3. Select a User Account to edit by hovering your cursor over the end of a row

   until you see a pencil icon.

4. Click on the pencil icon to see the Edit User Account window.

   
5. Select a new role for the user by choosing a check box next to the role you

   want to give this user.

6. Uncheck any existing roles.

7. Click the OK button.

Tenant-Level Permissions

Permissions for users of your Aisera instance (usually your company's Aisera platform) are known as tenant-level permissions.

Adding a Tenant-Level Account

You can use the + Add New Account feature to create a tenant-level account for your Aisera Gen AI Platform. This is also known as a Service Account. This account is only used by people who may need to log onto the account server to perform API calls, or other tenant-level tasks.

To create a tenant-level account:

1. Select Settings > User Account in the Aisera Admin UI.

2. Click the + Add New Account button.

3. Choose the Service Account role for your new user.

Creating a Custom Role

NOTE: If you are creating a custom role, make sure your role has at least the following permissions, which are required to view conversations with AI Lens:

• intent – Read

• channels – Read

• AiseraGPT – Read

To create a custom role:

1. Open Settings > User Accounts in the left navigation menu of the Aisera Administration application.

2. Select the Roles tab.

   
3. Choose + Create Role. Enter a Name and Description for the role.

   

   Select an appropriate level of privilege

To Edit a Custom Role (Edit)

1. Open Settings > User Accounts from the left navigation menu of the Aisera Administration application.

   
2. Select the Roles tab.

   
3. Select a role that you want to modify. Note that system and default roles are not editable. You can only modify custom roles.

4. From the Role Detail page, click the row that contains the role you want to modify.

5. Choose the edit/pencil icon in the upper-right section of the window.

   
6. Change the Name, Description or Privileges for the role.

Assigning Your Custom Roles to Users

If you have been assigned to an Administrator role in the Aisera Administration application, you can select specific users and assign custom roles to them.

1. Open Settings > User Accounts from the left navigation menu of the Aisera Administration application.

2. Stay on the New Accounts tab of the User Accounts window.

3. Choose the name of the User who you are assigning your custom role to.

4. Choose your new role(s) by selecting the checkboxes next to the new role names. You don’t have to uncheck existing roles, just select the new ones that you want to assign to this user.

Setting Application-level Access Control

Application-level access control is based on the user access attributes. You can read these attributes from the User Profile. This additional access filter works in conjunction with a user’s Aisera roles.

Applications that have no restrictions are available for all users with Read/Write access to the Entity Type called Aisera Applications.

If an access restriction is applied to an embedded application (bot) you are building, then all of the Entities under that application (such as Intents, Flows, Data Sources, Integrations, and Channels) inherit the restriction.

For example, if you want to restrict an application based on a user's department, such as restricting the application to HR Stage so that it is only accessible to users who work in the HR department.

To restrict an application:

1. Open Settings > Access Control in the left navigation menu of the Aisera Administration application.

   1. Use one of the default attributes or create a new one.

   2. Make sure you select the appropriate user profile property for each attribute.

      1. Value of this user profile property will be extracted from the user profile and set to attribute for the user.

      2. If this is a custom user profile property that is not visible in the dropdown, select "Custom" as the value for the user profile property, and then use the name of the custom field as the name of the Access Attribute.

         
2. Run an Access Attribute Extraction job from Settings > System Jobs > Generic.

   a. Select the Data Source you used for your user ingestion.

   b. Leave the Start/End time blank.

   c. Select Entity User as the entity-type.

   d. This job will extract the attributes value from the user profile and persist this data in the user’s access attributes.

3. Create user accounts for the users who are going to access the Aisera Administration application and assign roles with the. Settings > User Accounts command.

To Create Application-level Restrictions:

Application entity level restrictions are configured at application level.

1. Select an embedded application (bot you’re building).

2. Scroll to the bottom of the Details window.

   
3. Click the + Assign Access Attributes button.

4. Select the attribute Name. Names are populated based on active/enabled attribute under Settings > Access Control

5. Enter the value. Currently, you need to set the value manually.

Content-level Restrictions (ACLs for KB Articles)

You can apply Access Control to content in two different ways.

1. Knowledge Base Article metadata-based Access Control

   1. At a high level, Knowledge Base Articles can contain metadata about who can view the KBA. Metadata can also include information like country, region, and roles, depending on your knowledge base system, and the tools used to create the articles. During data ingestion, the Aisera Gen AI platform also Ingests this metadata.

   2. You can include similar information about each user when you upload and ingest User Profile data.

   3. During data ingestion, the Aisera Gen AI platform extracts the metadata tags and user profile property values and saves them separately as Access Attributes.

   4. The Aisera platform uses this information to apply a filter before sending a fulfillment answer. Once the content is found by fulfillment engines like ICM/RAG/Neural Search, the Aisera platform checks to see if that content is restricted for the bot user making the request. If the content is not restricted from this user, then the user is served the content. If the content has multiple access attributes, then the user profile should be unrestricted for all of them. For example, if a KB Article requires the user to be in a specific security group for region North America the two access attribute for this article are group=abc and region=NA and the user should not be restricted from either of these attributes if you want them to view the article.

   5. Sometimes a user's profile does not have the required metadata, but during the user session such information is passed in. The Aisera platform can use such dynamically passed information as session variables. These sessionVars are used to pass the dynamic information.

2. Using third party APIs.

   1. In this case, before we serve content to a user, we make a call to system like Jira/ServiceNow. The third-party API will send the Aisera platform abour whether the user has access to content that the Aisera software is about to serve to the user.

Activate Access Management for Content Control

The Access Management feature is disabled by default. Enable Access Management by selecting Settings > Configuration > Access Managementin the Aisera Admin UI.

Access Attributes

You apply restriction to content using Access Attributes. These are properties or tags within a KB Article that define who can view the article.

Specify which article tags have a value for an access attribute using the Ingested Tag Format.

Configure the User Profile property for each tag in the user Profile Field.

For example, to filter articles by country, configure a country access attribute with:

• add a tag to your KB articles that includes a country value in Ingested Tag Format

• add a User profile property that specifies the country of the user in a Profile Field.

The following access attributes are included in the Aisera application by default:

• Roles

• country

• company

• region

• groups

• language

You can extend this list by creating a new access attribute.

To create a new Access Attribute:

1. Navigate to Settings > Access Control.

1. Choose + New Access Attribute.

1. Enter the Name of your new Access Attribute.

2. Check the Enabled box, if you want it to start working immediately.

3. Click OK.

You can create many Customer attributes for a single tenant, such as azureId, siteGroups, securityGroups, product, subProduct, orsegmentId.

Access Attribute Properties

How to Setup Permission Ingestion

To enable the file permissions, as previously described, you must define two fields in the Knowledge Article Fields section. These fields will be integral to the process of managing and integrating permissions within the user profiles, ensuring that the system can effectively store and utilize the necessary information for access control.

In a Sharepoint KB Datasource press the new Field Mapping button and add the 2 following mappings

1. Field TagKey and Sharepoint Field keys

2. Field TagValue and Sharepoint Field values

How to add custom TagKey and TagValue

To incorporate additional custom TagKey/TagValue pairs, you have the option to define a JavaScript function within the configuration, specifically in the custom script input text box.

The JavaScript snippet below allows you to add new pairs, such as country TagKey with a Brazil TagValue. This new pair will become a distinct element within the JSON structure under the tags array, as global:country=Brazil . This flexibility allows for the dynamic expansion of custom tagging and metadata associated with the data in the JSON representation.

function transform(jsonObject) {
    var JSONParser = Java.type('org.json.simple.parser.JSONParser');
    var JSONArray = Java.type('org.json.simple.JSONArray');
    var JSONObject = Java.type('org.json.simple.JSONObject');
    var parser = new JSONParser();
    var keysList = parser.parse(jsonObject.keys);
    keysList.add("country");
    jsonObject.keys = keysList;
    var parser = new JSONParser();
    var valuesList = parser.parse(jsonObject.values);
    valuesList.add("Brazil");
    jsonObject.values = valuesList;
    return jsonObject;
} 

Ingesting Knowledge Base Article Metadata

Depending on your integrated knowledge base system, the metadata for the knowledge base articles can be in the form of a tag, a custom property, or defined at the folder level. Most of the time it varies from system to system.

Before you create Access Attributes, identify the attributes that are used as metadata for the knowledge base articles in your system.

The identified attributes must be ingested as tags.

Here are some examples:

1. Each of the Knowledge Base Articles ingested with a Data Source job have the same value for every access attribute, such as country. If this is the case with your articles, you can hardcode the tag value as shown below:

1. The metadata for each Knowledge Base Article is derived from a folder or directory. For instance, if your company knowledge base articles in SharePoint are organized in folders or directories by country. And each user only has access to the knowledge base articles for the country they are in.

   1. The country can be extracted like this via a Custom Script during the Data Source ingestion job:

function transform(jsonObject) {
	var JSONObject = Java.type('org.json.simple.JSONObject');
	var fileDir = jsonObject.FileRef;
	var country = "";
	if (fileDir) {
		if (fileDir.contains('SitePages/055')) {
			country = 'india';
			includeFile = true;
		} else if (fileDir.contains('SitePages/221')) {
			country = 'australia,new zealand';
			includeFile = true;
		}
	}
	if (country != "") {
		jsonObject.country = country;
	}
	return jsonObject;
}

b. Field mapping to ingest country metadata as a tag:

1. Each knowledge base article has this metadata available as a custom property.

   1. Ingested data already has a property that you can use.

   2. Map the field.

1. Multiple properties

   1. Using a Custom Script during Data Source ingestion, you can build two lists to create key:value pairs. One contains a list of Keys and another contains a list of Values. The order of the key and the associated value should match in both lists.

function transform(jsonObject) {
	var keys = [];
	var values = [];
	if (jsonObject && jsonObject.Product__c) {
		keys.push('Product');
		values.push(jsonObject.Product__c);
	}
	if (jsonObject && jsonObject.Product_Line__c) {
		keys.push('ProductLine');
		values.push(jsonObject.Product_Line__c);
	}
	if (jsonObject && jsonObject.Sub_Product__c) {
		keys.push('SubProduct');
		values.push(jsonObject.Sub_Product__c);
	}
	if (keys.length > 0) {
		jsonObject.keys = keys;
		jsonObject.values = values;
	}
	return jsonObject;
}

1. Field Mapping

1. SharePoint Permission

   1. Many of our customers have knowledge articles in Sharepoint and they are using Sharepoint’s in-built access control mechanism. Via this mechanism document can be restricted based on Sharepoint Site Group, List of Users (using user’s AzureId) and Azure AD Security Group. More information can be found in Group access information (ACL) for Sharepoint Knowledge Base Articles.

Access Attribute extraction

The Aisera Gen AI platform includes an algorithm to extract attribute values for knowledge and users. To extract attributes, troubleshoot, or debug access attributes, see your implementation team. This information is covered in their Implementation Guide.

User messaging

When any content gets filtered out from being served to the user because of access policy, then user will be informed via a message that some of the content was removed because of the access policy.

IMPORTANT: This message is not supported when content is served via the RAG and NS fulfillment engines.

The message is configurable. To change the message please go to the app. Select the Conversation Messages. Look for key access_policy_restricted_content_preamble.

Request Resolution Type

The request will be marked Correct Answer when we have identified an intent but intent was filtered out because of access policy. The bot understood what user was inquiring about, but it could not serve because of customer’s access policy.

If we could not identify any intent, but we found something via search then that request will be stored as Not Understood.

Optional Filters

You can apply an optional filter to an Access Attribute that is active and is specified as not required.

For example, you can apply a filter based on language.

If a user asks a question in German, and multiple documents are available on the requested topic with different languages, then you want to provide an answer from the Knowledge Base Article that is written in German. But what happens if you knowledge system doesn't have a KBA in German for the topic, but there is a KBA in English. In this case, you can designate the English document as the fallback document to answer the user’s question.

Use a JEXL-based expressions to define this type of filter.

You can define these optional filters at the tenant level. Settings > Configuration > Access Management > Access policy for optional attributes.

Single value attribute

The expression for above example is: (entity.language == null || entity.language == '' || entity.language == 'en' || entity.language == user.language)

The restrictions we defined above are:

1. If the knowledge article does not have the attribute language then the user can view it (entity.language == null)

2. If the knowledge article has an empty value for the attribute language then the user can view it (entity.language == '')

3. If the knowledge article has a value and it is en(English) for the attribute language then the user can view it (entity.language == 'en')

4. If the knowledge article has a value other than en then it should match user’s language to view the article. (entity.language == user.language)

Where:

Multi-value attributes

The Aisera platform uses the compareList system function to compare multiple value access attributes.

If you want to filter content based on the access attribute country,you can define it as an array/multi-value. This will make the knowledge article relevant for multiple countries.

To compare the country attribute defined on knowledge articles with the user’s country, use this expression: compareList(entity.country, user.country).

The following example displays the way the compareList function compares lists/array/multi-value attributes. This is part of the code and cannot be changed without release.

var compareList = function(entityList, userList) {
    var matched = false;
    if (entityList == null || entityList.size() == 0) {
        matched = true;
    } else {
        if (userList == null || userList.size() == 0) {
            matched = false;
        } else {
            for (entityAttribute: entityList) {
                if (userList.contains(entityAttribute)) {
                    matched = true;
                    break;
                }
            }
        }
    }
    matched;
};

Optional filter can be used in many different use cases.

• For one of our customer, we wanted to filter content based on two attributes: country and region.

• We wanted to use region as a back up of country. Therefore, if a knowledge article has country defined, then match it with the user profile’s country. But if country is not defined for a knowledge article, but region is defined, the match the user profile's region.

• We configured such check like this: (entity.country != null && entity.country.size() > 0 && compareList(entity.country, user.country)) || ((entity.country == null || entity.country.size() == 0) && (entity.region != null && entity.region.size() > 0 && compareList(entity.region, user.region)))

(entity.country != null && entity.country.size() > 0 && compareList(entity.country, user.country)) || ((entity.country == null || entity.country.size() == 0) && (entity.region != null && entity.region.size() > 0 && compareList(entity.region, user.region)))

• The first part of expression is checking whether the knowledge article has a country attribute, then match. (entity.country != null && entity.country.size() > 0 && compareList(entity.country, user.country))

(entity.country != null && entity.country.size() > 0 && compareList(entity.country, user.country))

• The second half checks when county is not defined but region is. ((entity.country == null || entity.country.size() == 0) && (entity.region != null && entity.region.size() > 0 && compareList(entity.region, user.region))

((entity.country == null || entity.country.size() == 0) && (entity.region != null && entity.region.size() > 0 && compareList(entity.region, user.region))

Passing Access Attributes in sessionVars

There are multiple way to pass information in sessionVars. One of them is via pre-handling flows.

SessionVar is map/property-bag/list of key value pair. Like this

{ "userId" : "abc12", "company" : "Aisera" }

Pass Access attributes with the accessAttributesproperty.

This is a string-ified json call. Assume you want to send two access attributes productLine and country for a user. Make sure the label of each key matches the access attribute name. For example, productLine in the example below is the access attribute name.

{ "productLine" : "duc1", "country" : "united states" }

The code should be passed like this in the sessionVar:

{ "userId" : "abc12", "company" : "Aisera", "accessAttributes": "{\"productLine\" : \"duc1\", \"country\" : \"united states\"}" }

Javascript to update a sessionVar:

sessionVars.put("accessAttibutes", "{\"productLine\" : \"duc1\", \"country\" : \"united states\"}"); return sessionVars;

Access Control for Content Using Third-Party APIs

Many of our customers use complex content access control on their source systems. For example User Criteria on ServiceNow or Group based access control on Confluence content. These type of access control configurations are very complex, many times involves custom scripts that evaluates access. It's not possible to apply such access control outside the context of the source system.

To support such configurations, we have support for API based access control. It is configured on a Data Source.

For ServiceNow we can use this configuration for applying access control on both Knowledge Articles as well as Service Catalogs Items.

Make sure user ingestion is setup on a schedule. To check if user has access to content, we use user’s id of the SOR. User ingestion will make sure we have user’s external ID.

Tenant configuration

Enable the tenant level flag Access Management from Settings > Configuration. This Configuration window is for tenant-level parameters.

Data source configuration

Now set the configuration for your Data Source. This example uses ServiceNow as a data source.

Where:

Download an Update Set or Check User Criteria

Ask your Aisera Implementation team to share the latest data that they have downloaded via an xml script. They can find this in the internal engineering documentation.

Validating the Third Party API

After the customer has installed this update set, you can validate If the third party API is working as expected. Using ServiceNow as an example:

1. Navigate to REST API Explorer on ServiceNow

2. Select aiser from Namespace

3. Select User criteria check from API Name

4. Use the sample payload below. Replace the userId with the sys_id of a user on their system.

5. Update the ids under knowledgeDocuments with some knowledge base article numbers from their system. If you want to test the Service Catalog, then replace the ids under catalogItems with sys_ids of some of the Service Catalog items. Try the API with a few sample users.

{ "userId": "a0f7e879db219150996f4a7f0596193f", "knowledgeDocuments": [{ "id": "KB1233" }, { "id": "KB4455" }], "catalogItems": [{ "id": "9e274809db6ddd10996f4a7f059619fa" }] }

The output of the API will look similar to the code below. ThecanView parameter will shows you whether the user has access to Knowledge Base Article or Service Catalog Item or not.

{ "userId": "a0f7e879db219150996f4a7f0596193f", "knowledgeDocuments": [{ "id": "KB1233", "canView” : true }, { "id": "KB4455", "canView": false }], "catalogItems": [{ "id": "9e274809db6ddd10996f4a7f059619fa", "canView": true }] }

User criteria with script

Many customers use scripts as part of their User Criteria. If they are not using the system variable user_id for the user’s id in the script, then the user criteria will not work properly when checked via an API. Make sure the customer is using the pre-defined variable user_id.