Content Access Control

• Content-level Permissions (ACLs per Knowledge Article)

• Content Access Control via 3rd Party APIs (especially for ServiceNow and Confluence)

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 (Content Access Control via API)

   Before the application/bot serves content to a user, the Aisera platform can make a call to an external data system like Confluence/Jira/ServiceNow. The third-party API sends the Aisera platform acknowledgement that the user has access to content that the Aisera software is about to serve to the user. Data sources like Confluence only use the Content Access Control via API method. See the link above for step-by-step instructions.

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;