Introduction

Industries such as banking, finance, and health care must comply with government regulations imposed by agencies like the SEC or HIPPA. In such scenarios, customers require greater control over the messaging and communications in their enterprise. The levels of policy enforcement, archiving, and auditing needed for such compliance significantly exceed the base functionality included in email and unified communication software.

Regulations, laws, and control points are always evolving, which makes compliance complex. Enterprises require a flexible mechanism to add, remove, or update compliance rules to the existing messaging and collaboration solutions. IBM® Sametime® Chat Rooms and Broadcast Communities offer an API-based, extensible solution by which customers can integrate their compliance tools with the Sametime infrastructure. A number of add-on solutions have been created by third-party vendors and partners, providing additional functionality to address compliance needs.

Architecture

General concerns of a compliance product are:

- Whether content violates corporate policy
- Storing a list of users who received a message, for future audit
- Determining which users should be permitted to communicate

By definition, users who are authorized to log in to Sametime Advanced are permitted to communicate, so Persistent Chat Rooms and Broadcast Communities pass the ethical wall test.

Architecture of the compliance API of Broadcast Communities is depicted as below.





When the adapter is deployed in a clustered environment, only the adapter on the node where the user is logged in is notified of the action.

Usage of Compliance API

Compliance API of Sametime Chat and Broadcast Communities addresses following functional areas:

Compliance API & Broadcast Communities

The participants in Broadcast Communities have four tools for connecting with their peers:

· Broadcast Announcements
· Instant Poll
· Skill Tap
· Broadcast Chat

To enforce or implement Compliance Features for Broadcast Tools, a plug-in needs to be created which extends com.ibm.collaboration.realtime.plugin.PluginBroadcastHandler class. For each event to be monitored for the Compliance, two methods per event need to be implemented. For more details on the architecture and event flow, please refer to the SDK Documentation.

The compliance API first checks to see whether a compliance adapter is registered which handles Broadcast Tool Events (PluginBroadcastHandler), and, finding one, forwards the details of the Broadcast Tool Event as a call to the method [broadcast tool name]([broadcast tool name]Event) on that adapter (Refer to Table 2 Broadcast Tools - Compliance API) .
The Sametime Chat Rooms & Broadcast Communities Server will withhold the broadcast event from target recipients until interactions with the compliance adapter have completed. The “[broadcast tool name]Event” parameter encapsulates the details of the incoming request and the results from the compliance adapter in writable fields like “status” and “reason”. The adapter can potentially modify the text of the broadcast tool event or block the action entirely.

As a next step, compliance API will calls out [broadcast Tool Event] ([broadcast Tool Event]EventStatus) method. The general pattern is that the xxEventStatus object contains the same details as the xxEvent object, but they are now immutable in the EventStatus version. This call is made to allow the compliance adapter to archive the final result.

As a final step, based on the compliance Check outcome, if permitted, the broadcast event is sent to the recipients with modifications (if any, based on the compliance checks).

Following are the APIs which must be implemented in the plug-in for the Broadcast Tools:

Broadcast Tool	API
Broadcast Announcements	announcement (AnnouncementEvent event)
	onAnnouncement (AnnouncementEventStatus status)
Instant Poll	instantPoll (InstantPollEvent event)
	onInstantPoll (InstantPollEventStatus status)
Broadcast Chat	broadcastChat (BroadcastChatEvent event)
	onBroadcastChat (BroadcastChatEventStatus status)
Skill Tap	skilltapRequest (SkilltapRequestEvent event)
	onSkilltapRequest (SkilltapRequestEventStatus status)
	addSkilltapFAQ (AddFAQEvent event)
	onAddSkilltapFAQ (AddFAQEventStatus status)
	editSkilltapFAQ (AddFAQEvent event)
	onEditSkilltapFAQ (AddFAQEventStatus status)
	deleteSkilltapFAQ (AddFAQEvent event)
	onSkilltapFAQDelete (AddFAQEventStatus status)
Common	userJoin (UserJoinEvent event)
	onUserJoin (UserJoinEventStatus status)

Compliance API & Persistent Chat Rooms

The Persistent Chat room is a group chat that records a transcript of messages posted by users, and displays the most recent of these whenever a user enters the room. The whole transcript can be accessed, and search tools are supplied to help find entries from a specific time or user, or with a specified search string. The Persistent Chat also permits users to post files, which are archived by the server and can be downloaded by any user visiting the room.

Like the Broadcast tools, the Persistent Chat Compliance APIs use two communication phases to the adapters, following the pattern action (actionEvent) for a decision phase, followed by onAction (actionEventStatus) for reporting the final result for archiving.

Enforcing Compliance on Join Events

Persistent Chat rooms are set to permit only certain users or groups to join. Any incoming action to join a room goes through an access control mechanism in the Sametime Chat Rooms & Broadcast Communities server before permission is granted. To enforce compliance on Join Events, a Compliance Adapter implementing “PluginUserJoinHanlder” needs to be installed on the server. If the Compliance Adapter is installed, the server may also seek approval for every attempted join, to permit the adapter the opportunity to scrutinize the action against its own, possibly more stringent, criteria.

Below are the compliance adapter API functions involved:
PluginUserJoinHandler - Interface

• void userJoin(UserJoinEvent event) - called when a user is trying to join a chat room
• void onUserJoin(UserJoinEventStatus) - called when a user is joining or leaving a chat room

Some compliance vendors inject disclaimer messages when a user joins the room (for example, "Note that business guidelines apply to chat room use, and room content is actively monitored for compliance"). This can be achieved by setting status Event status MODIFIED and putting the disclaimer text into the reason field of the status object.

Enforcing Compliance on Chat Transcript

Allowing the third-party compliance product to inspect and possibly block or modify a transcript entry requires each line to be presented to the compliance API. Sametime Advanced must withhold publication to the room until all compliance adapters have returned their judgments. To enforce compliance on Join Events, the Compliance Adapter implementing “PluginChatTextHandler” needs to be installed on the server. Below are the compliance adapter API functions involved:

PluginChatTextHandler - Interface

• void chatText(ChatTextEvent event)
• void onChatText(ChatTextEventStatus)

The ChatTextEvent and ChatTextEventStatus include a text field initially populated with the user's attempted post text. If status is set to MODIFIED, the revised text that has been written into the event field will be used as the final modified post to the Chat room. For MODIFIED or BLOCKED the reason field is echoed to originating User.

Enforcing Compliance on Files Posted To Chat Rooms

There may be requirements to manipulate files before they are posted to the Persistent Chat room. This manipulation can include virus scanning or other content-based inspection. To enforce compliance on Join Events, the Compliance Adapter implementing “PluginFilePostHandler” needs to be installed on the server. Based on the compliance check outcome, the adapter can return the modified file or block the post entirely. Below are the compliance adapter API functions involved:

PluginFilePostHandler - Interface

• void filePost(FilePostEvent event) – called When User Posts a File
• void fileDelete(FilePostEvent event) - called When User Deletes a File
• void onFilePost(FilePostEventStatus)
• void onFileDelete(FilePostEventStatus)

The FilePostEvent.getFile() returns a java.io.File object, which is actually a path+filename descriptor to a file on a system. If a modification is needed, the adapter should overwrite the file and set the MODIFIED status. A separate set/getFileName is used for the file name as it will be presented in the UI for the room.

Enforcing Compliance on Chat Room FAQ

There may be requirements to enforce compliance checks on Chat Rooms FAQs before they are created, edited, or deleted. To enforce compliance on Chat Room FAQ Events, a Compliance Adapter implementing “PluginAddFAQHandler” needs to be installed on the server. The Question and Answer fields of the FAQ are available for inspection, and may be modified by the compliance adapter in the create and edit cases. Below are the compliance adapter API functions involved:

PluginAddFAQHandler - Interface

• void addFAQ(AddFAQEvent event) – called when FAQ is added
• void editFAQ(AddFAQEvent event) – called when FAQ is edited
• void deleteFAQ(AddFAQEvent event) – called when FAQ is deleted
• void onAddFAQ(AddFAQEventStatus)
• void onEditFAQ(AddFAQEventStatus)
• void onFAQDelete(AddFAQEventStatus

Enforcing Compliance on Chat Room and Transcript Deletion

An entire chat room, or part of chat transcript, can be deleted. Transcripts can be deleted based on the start and end times. Based on the Compliance checks, these deletion operations may be disallowed. To enforce compliance on Chat Room FAQ delete Events, a Compliance Adapter implementing “PluginChatDeleteHandler” needs to be installed on the server. Below are the compliance adapter API functions involved:

PluginChatDeleteHandler - Interface

• void chatRoomDelete(ChatRoomDeleteEvent) – called When Chat Room is deleted
• void chatTextDelete(ChatTextDeleteEvent) – called when portion of the Transcript is deleted
• void onChatRoomDelete(ChatRoomDeleteEventStatus event)
• void onChatTextDelete(ChatTextDeleteEventStatus)

Deployment of Compliance API JAR

Compliance API is deployed as a JAR file in the Sametime Advanced server environment. Adding the JAR to a folder requires the WebSphere class path to be updated. Or you can add this to the existing locations like \IBM\WebSphere\AppServer\profiles\STADVAppProfile\optionalLibraries\rtc. This will require a restart of the server.

Clustered environments will require the JAR to be placed on all nodes, and a node synchronization to be executed.

Integration with other tools

Other compliance solutions can be integrated with the Sametime Advanced Compliance Adapter to protect corporate brand and reputation, ensure ethical practices, and maintain compliance. Vantage for IBM Sametime is an offering from an IBM Business partner and can be integrated with Sametime Advanced Compliance Adapter.

Refer to ibm.com/partnerworld/gsd/solutiondetails.do?solution=13448&expand=true for further details.

Compliance API Samples

There are two samples detailed in this article. In these samples, we define a plugin with id “com.ibm.sametime.compliance.ChatRoomAdapter”. This contains multiple extension points.:

ChatRoomTextSaveAdapter -- is of extension type com.ibm.collaboration.realtime.plugin.chat_text_handler. This extension also defines the action class as com.ibm.sametime.compliance.ChatRoomTextSaveAdapter which saves the chat transcript to a file.

ChatRoomTextBlocker -- is also of extension type com.ibm.collaboration.realtime.plugin.chat_text_handler. This defines the action class as com.ibm.sametime.compliance.ChatRoomTextBlocker and blocks user-entered content based on the list of identified blocked text.

"Saving Chat Transcript" Sample

This sample helps you store some of the attributes of the chat to a file for audit purposes. This can be extended to save the details to a database. ChatRoomTextSaveAdapter implements the PluginChatTextHandler interface to capture and save chat room transcripts.

private static String File_Path = "ChatTextAudit.txt";
File_Path class variable holds the path to the file where the transcripts are stored.

chatText(ChatTextEvent event) is the method called when a user enters a transcript into the chat room. This method appends the transcripts to the file with the following details:
· Sender of the transcript – user details are retrieved from the method event.getOriginatingUser().getID()
· Transcript Text – Text can be retrieved from the event.getText() method.
· Time of the transcript
· Chat room Name – Chat room name is retrieved event.getSessionDetailUtil().getSessionName(event.getSessionID())
· If chat room id is required to be captured, event.getSessionID() can be used directly.

"Blocking Content" Sample

This sample describes how Compliance API can be used to restrict content entered in the Chat Rooms, based on certain keywords. To demonstrate this, ChatRoomTextBlocker class is created and implements the PluginChatTextHandler interface.

The following variables are defined at the class level:

● private final static List RESTRICTED_KEYWORDS = new ArrayList();
● private final static String BLOCKED_STRING = "[Unacceptable word or pattern]";
● private final static List RESTRICTED_PATTERNS = new ArrayList();

The RESTRICTED_KEYWORDS and RESTRICTED_PATTERNS variables are initialized with the list of Restricted Keywords and Patterns in public void init(Properties properties, PluginStartupCallback callback) method of the ChatRoomTextBlocker class.

public void init(Properties properties, PluginStartupCallback callback) 

{

…..

		// Initialize Restricted Keywords 

		RESTRICTED_KEYWORDS.add("USER NAME");

		RESTRICTED_KEYWORDS.add("PASSWORD");

		RESTRICTED_KEYWORDS.add("CREDIT CARD NUMBER");

//Generic Pattern to Identify VISA, Master or AMEX Credit Card Number

RESTRICTED_PATTERNS.add(Pattern.compile("\\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|3[47][0-9]{13})\\b")); 

//Generic Pattern to Identify SSN Number of format NNN-NN-NNNN

RESTRICTED_PATTERNS.add(Pattern.compile("\\b\\d{3}[- ]?\\d{2}[- ]?\\d{4}\\b")); 

}

To find and replace restricted keywords in the entered chat text,
1. Get the User ID from the ChatTextEvent parameter using getOriginatingUser() method
2. Get the Entered Text from the ChatTextEvent parameter using getText() method
3. If text contains any of the restricted keywords or patterns, replace them using String.replaceAll(String keyword, String replacement) method.

// Find and Replace Restricted Keywords

for (String keyword : RESTRICTED_KEYWORDS)

		{

			if (text.contains(keyword))

			{

				text = text.replaceAll(keyword, BLOCKED_STRING);

				textChanged = true;

			}

		}

// Find and Replace Restricted Patterns

for (Pattern pattern : RESTRICTED_PATTERNS)

{

    Matcher matcher = pattern.matcher(text);  

   while (matcher.find())

  {

     String b =  matcher.group();

     text = text.replaceAll(b.substring(0, b.length()), BLOCKED_STRING);

     textChanged = true;

  }

}

4. Set the modified text to event object.

5. Set the event status as EventStatus.EVENT_MODIFIED_TYPE
6. Optionally enter a reason for the text modification using event.setReason() method

if (textChanged)

		{

			event.setText(text);

			event.setStatus(EventStatus.EVENT_MODIFIED_TYPE);

			event.setReason("Entered text was modified to comply with corporate policies");

		}

Finally, public void onChatText(ChatTextEventStatus status) is implemented to send final status back to the user.

public void onChatText(ChatTextEventStatus status) {

		int stat = status.getStatus();

		String statStr = "UNDEFINED STATUS";

		switch (stat) {

		case EventStatus.EVENT_OK_TYPE:

			statStr = "text permitted";

			break;

		case EventStatus.EVENT_BLOCKED_TYPE:

			statStr = "text blocked, reason = " + status.getReason();

			break;

		case EventStatus.EVENT_MODIFIED_TYPE:

			statStr = "text modified, reason = " + status.getReason()

			  + ", final text = " + status.getText();

			break;

		}

		_logger.fine(statStr);

}

Installing the Samples

Both samples are included in the attached JAR file, which you can deploy to your Sametime Advanced server. Refer to the deployment section to install the sample.

Running the Samples

Once the samples are deployed and the Sametime Advanced Server has been restarted, the samples will be invoked whenever a user sends a text into any chat room. When the Save plugin is invoked, it writes the chat's text into a file.

The content of the saved chat looks like the following image:



When the blocker sample is invoked, it changes text according to the defined rules. When a user enters the text that is not acceptable per the policy defined in the compliance sample, that user sees the text replaced with a ‘[Unacceptable word]’ message, accompanied by the status message: Entered Text is modified to comply with corporate policies

Conclusion

The API-based solution for enforcing compliance in Sametime Chat and Broadcast Communities is flexible and easily deployed. The APIs work with a number of add-on solutions provided by vendors and business partners.

About the authors

Josephine E Justin

Josephine E Justin is a Advisory Software Engineer with over 13 year of experience. She is currently working with IBM Collaboration Solutions Team in India.

Manish Patel

Manish Patel is an IBM Accredited Architect with over 14 years of IT experience. He is currently working with IBM Collaboration Solutions Team in IBM Software Group India.