Overview

The Records Retention Extension tracks the creation or update of the user-generated content within Jive and delivers it to an external archival system. The retained events are described in the official documentation. This article provides information on the Records Retention Extension in Jive by covering the following content:

• Delivery Format
• Archival Process
• Backup Duration
• Checking the Process
• Replaying Events

Description

Delivery Format

The Records Retention Module is offered in three varieties, namely SMTP, XML, and REST API. All formats capture the same data but differ in timing and structure.

• The SMTP format converts each retained communication into an email message, which is delivered to an email inbox within your company. Hence, it offers a simple mechanism to capture Jive communications by leveraging your current infrastructure. It is assumed that this mailbox will be archived and stored with third-party software, for example with backup software, independently from Jive.
• The XML format aggregates communications and compiles them on a periodic basis into a single file. Each file is placed in a directory where it can be retrieved and parsed by your archival system. While it requires additional effort, this format provides complete control and flexibility.
• The REST API format sends each event via REST to an instance of Actiance Vantage. This provides a reliable mechanism to feed information to a Vantage system for archival and analysis.

Archival Process

Once a record is sent, it is considered "processed" by the Retention module. However, an event can be replayed in case the data is lost by the target archival system. This also includes binary attachments.

• Actions are captured by the Jive code and sent to the jiveRetentionQueue table, and a copy is also placed in the jiveRetentionMessageArchive table. Both tables are located in the main App database. 
• The records are removed from jiveRetentionQueue as soon as they are delivered to you via the method that you have chosen (SMTP, XML, or REST API).

Backup Duration

The records in the jiveRetentionMessageArchive table are kept for a period of time that is specified in the retention.reaper.messagearchive.number.of.days.to.keep System Property.

Warning: Jive will keep the events on the database up to a maximum of 90 days and the binary data up to a maximum of 60 days, even if this property is set to higher values. 

Checking the Process

The Records Retention module produces an alert when an event has a failure during the retention process.  In order to see alerts, you can check the inbox where the events are being received, or, if you are using XML, you can check the folders where the XML files are stored. 

When using XML, if the event does not get stored and there is no alert, most probably, the storage is not configured correctly. Likewise, when using SMTP, if the inbox does not show the event, and there is no alert, presumably, the emails are being rejected. 

You can also enable the following loggers via the Admin Console: 

• com.jivesofware.retention.binary
• com.jivesofware.retention.task.impl

Setting these to DEBUG shows every action of the Records Retention module. You can select an event from the Records Retention Retained Events list and verify that the event is being recorded in the logs. Then, you can go to the inbox (SMTP) or the corresponding folder (XML) and confirm that the event made it to its final location. 

Replaying Events

The Records Retention Extension is designed to capture events occurring in Jive and make them available to a client's archival system. While Jive does not guarantee the availability of the historical data, the extension is designed to archive a copy of the data locally. Replaying records is the process of copying records from historical storage into the queue so that they can be redelivered.

To replay the records, execute the following SQL commands:

INSERT INTO jiveretentionqueue 
SELECT * 
FROM   jiveretentionmessagearchive 
WHERE  <SOME conditions>; 

DELETE 
FROM   jiveretentionmessagearchive
WHERE  messageid IN 
       ( 
              SELECT messageid 
              FROM   jiveretentionqueue);

 These commands can be executed on the database directly by On-Premise customers. Hosted and Cloud customers will need to open a ticket in the Jive Support Portal.

Once the records are back in the queue, the queue reader picks them up for delivery regardless of their type.

This mechanism makes it possible to resend SMTP messages that did not arrive at the inbox or replace an XML file that was lost. You can even generate XML files to represent a collection of records that were originally sent as SMTP messages.