How do I make a new user group in Knowledge Advanced and assign articles to it?

Environment:

Oracle B2C Service sites using Knowledge Advanced

Issue:

It can be unclear when exactly answer access levels configured in Oracle B2C Service are synced into Knowledge Advanced as user groups.

Resolution:

Understand that Answer Access Levels map 1-to-1 with User Groups, but that they use different underlying database tables. The process by which some of the information about the answer access level is copied into a user group is called shadowing. For user groups, this is a one-time synchronization of a particular access level that only will occur if there is not already a shadowed user group for that answer access level ID. It occurs when manually triggered within Authoring, or when a contact with an active SLA containing the access level sends a successful authentication request to the REST API (as when they log into Customer Portal and perform a search, open an article, or see the Popular Answers widget).

To create a user group in Knowledge Advanced:

1. Use Agent Desktop to create an Answer Access Level at Configuration > Application Appearance > Customizable Menus > System Menus > Answer Access Levels according to the Oracle B2C Service documentation.
2. If you just want to get started with the user group: within Authoring, navigate to Users > User Groups > Add. Select the answer access level from the dropdown and click Save User Group Properties. It is now shadowed, and will no longer appear in that dropdown. The administrator account or any staff account which has been delegated the sysadmin role can then add the new user group to console roles, views, and content types.
3. To shadow both the new user group and web role: Skip step 2, if you like. Create an SLA with all of the answer access levels you want to shadow, and assign it to a contact. Authenticate that contact against Knowledge Advanced by logging in to Customer Portal and interacting with the knowledge base somehow (seeing a list of articles from a widget, performing a search, opening an article, etc.). Alternatively, you can send a REST API authentication request for that contact. Any time a contact generates a new userToken at authentication, it is re-shadowed. Any answer access level included in the contact's SLA(s) with an unknown external ID will be shadowed to a user group and web role at that time.

Notes:

The Documentation for Oracle B2C Service Knowledge Advanced refers the reader to the Documentation for Oracle B2C Service Products for setting up user groups, but does not explain that the relationship between Answer Access Levels, Service Level Agreements, User Groups, and Web Roles. It is difficult to understand the terminology without that explanation.

The Knowledge Advanced (KA) integration in Oracle B2C Service is an optional component that replaces much of the functionality of the base Oracle B2C Service Answers (also called Knowledge Foundation answers) with that of KA Articles. For the purpose of this answer, it is useful to recognize that KA is a cloud implementation of the legacy on-premise product Oracle Knowledge, formerly known as InQuira.

Much of the existing design was leveraged from the on-premise product directly into Knowledge Advanced. For that reason, there is a different database schema used by KA for products, categories, user groups, and even users than that used by Oracle B2C Service. These tables are added to the existing site database the first time it is connected to KA. Suffice to say, the user groups are in the tag table, which holds similar information to the products, categories, and ans_access tables. The tagresource table contains the localized labels for these tags, analagous to the Oracle B2C Service's labels table. Web roles are with console roles and API roles in another table.

Initially, user groups were mapped to answer access levels and web roles were mapped to service level agreements. Web roles, in the on-premise software, had each contained a list of 1 or more user groups with possible overlap between roles. SLAs in Oracle B2C Service similarly can contain a list of answer access levels. But from a design perspective, the SLAs of RightNow and the Web Roles of InQuira were fundamentally different - when an SLA is modified, existing instances are not changed, owing to the design idea that the SLA could reflect an existing contract with a user or organization. In InQuira, when a web role was modified, all users with that web role got the change immediately. So KA was changed: answer access levels map 1-to-1 to user groups as well as to web roles. So every web role has exactly one corresponding user group, and the web roles still exist because they are needed to link user groups to actual users within the schema. The need to log a contact in with an appropriate SLA to get the answer access level synced to web roles is an artifact of all of this.

Knowledge Advanced is agnostic to the sorting and interface visibility settings in answer access levels.

You can only use User Groups > Add to add an answer access level once for that ID, so if you need to rename the access level and respective user group and web role later you will need to do so from both the answer access level editor and from within Authoring. While it's true that a contact will be shadowed every time they authenticate with KA, that action won't trigger a user group/web role shadow unless no user group/web role with that external ID exists.

It's not possible to delete web roles from the UI directly, since they essentially only exist as a join mechanism.

Deleting a user group will remove all of its associations with existing versioned content in the database. That is, as a best practice you probably want to use Find to identify all the articles associated to a user group prior to deletion. Anything not also associated to another user group will become public as soon as the user group is deleted and will start showing up in search results for everybody after the next full crawl of the knowledge base by content processing. If you recreate the user group, it will not be initially associated with any of those articles as it will have a new GUID in the tag table.

However, user group restrictions on sections of an article will NOT be removed if the user group is deleted. They're stored within the content XML itself, by reference key. If your content type STUFF has a schema attribute SECRETS that allows a restriction by user group, the content XML might look like this:

<STUFF>...<SECRETS SECURITY="RN_ACCESS_LEVEL_3"><![CDATA[Find only sees the words in here]]></SECRETS>...</STUFF>

The indexing used by Find only works on the data within the field; you can't use Find to identify what articles have a certain user group assigned to a schema attribute. There's not a good way to even identify these articles short of pulling all the content XML from the REST API with the full=TRUE&isForEdit=TRUE parameters and searching through that to find the reference key. As a best practice, you would remove a user group's association anywhere it appears in current content XML before deleting the user group.

Because the attribute-level restriction is specified by reference key, recreating the user group with the same answer access level would actually cause the new user group to be associated with those schema attributes.

If you delete the user group associated with answer access level 3 (in this example), then you'll have an issue. If that was the only user group assigned to an attribute, the whole section no longer shows up in the article preview in Authoring (even for a sysadmin user) or when the article is served in Customer Portal. You also can't uncheck the checkbox because there is no checkbox for a nonexistent user group, although you could update the article via REST to remove the restriction or paste the content into a new article. Otherwise, there's no way to make the information in that section public again.

Unless, of course, Oracle B2C Service recycled answer access level IDs, which it does.

As a best practice, do not delete the answer access level with the highest ID number. When you create a new answer access level, its ID number is 1 plus the highest existing number. Since the reference key of a user group in KA is a concatenation of RN_ACCESS_LEVEL_ and that ID number, it is left as an exercise for the reader to imagine an alternative way to bring back the missing SECRETS section of the article in the example. Lastly, rapid deletion and reshadowing of existing user groups can cause issues with content processing and is not recommended.