In the Review Interface, queues represent an ordered list of items that users can navigate through in the document viewer. This queue is frequently referred to as the review queue, which contains queue items that can be added or removed.
The Relativity Review Interface exposes a set of APIs that you can use to implement document navigation functionality in the viewer through the use of queues.
This page contains following information:
To learn more about the APIs for queues, see these resources:
queue property. The IQueueService is exposed as the queue property on the Review API (IReviewInterfaceApi) object.The review queue contains queue items (IQueueItem), which represent content that users can view, such as the following:
A queue item object must have all the required properties set as per the IQueueItem interface. A queue item may be a member of multiple queues.
To create a queue, use the IQueueService API to call the IQueueService.createQueue function. Pass the following arguments to this function:
Array<IQueueItem | number>) as an optional second argument.The following example illustrates how to create a queue and add an item to it:
reviewapi.on("apiready", function () {
// Create an empty queue.
var myQueue = reviewapi.queue.createQueue("my-queue");
// Create a document item using createDocumentItem(artifactId: number) method on the IQueueService.
var docItem = reviewapi.queue.createDocumentItem(1234);
// Add the returned document item to the created queue.
myQueue.addItemAtEnd(docItem);
});Use the IQueueService.deleteQueue function to delete a queue. Pass this function the ID of the queue:
reviewapi.on("apiready", function () {
var result = reviewapi.queue.deleteQueue("my-queue");
});To manage items in a queue, use the IQueueService.getQueueById function to retrieve the IQueue object. The queue object exposes functions to add, remove and get queue items.
var docQueue = reviewapi.queue.getQueueById("my-queue");
// Get specified number of queue items.
var docIds = docQueue.getItems(0, 3);
// Delete a single queue item and return a boolean to indicate success or failure.
var result = docQueue.deleteItemAtIndex(2);A custom application may require contextual information related to the queue.
To include custom data on a queue, use queue.customData. The customData variable must be of type CustomData, as illustrated in the code sample:
var customData = reviewapi.queue.customData;
customData.isCustomQueueType = true;
reviewapi.queue.customData = customData;
...
if (queue.customData.isCustomQueueType) {
// Do custom workflow here
}
In the Review Interface, the navigation system uses events to coordinate actions between components. In some cases, a component raises a request event, which is handled by another component. The second component raises another request event forwarding the results.
Each queue system component raises the following queue events:
Queue pointers represent a position in a given queue. You can use multiple queue pointers to track multiple positions in the same queue.
Consider the following use case for the queue:
To illustrate this use case, the Review Interface uses queues and queue pointers as follows:
Create a queue pointer (IQueuePointer) after implementing a queue to manage the position of current item in the queue. The IQueuePointer object provides the APIs used to navigate between documents, to determine when to navigate, and to identify the queue item (IQueueItem) that is currently active.
The following code samples illustrate how to create and use a queue pointer object:
Create a queue pointer.
var docQueue = reviewapi.queue.getQueueById("my-queue");
var queuePointer = docQueue.createPointer();Access a queue pointer from the IQueue object.
var docQueue = reviewapi.queue.getQueueById("my-queue");
var queuePointersArray = docQueue.pointers;
var queuePointer = queuePointersArray[0];Access a queue pointer from the viewer collection (IViewerService.mainCollection).
var queuePointer = reviewapi.viewer.mainCollection.queuePointer;Invoke navigation on a queue pointer.
Note: All the IQueuePointer navigation functions are asynchronous. They return a Promise that resolves to a boolean, indicating whether navigation occurred.
var queuePointer = reviewapi.viewer.mainCollection.queuePointer;
// Navigate to the next document in the queue.
queuePointer
.navigateToNext()
.then(function (navigationOccurred) {
// Navigation was prevented (false) or complete (true).
})
.catch(function (ex) {
// Navigation encountered an error.
});
// Navigate to a previous document in the queue.
queuePointer
.navigateToPrevious()
.then(function (navigationOccurred) {
// Navigation was prevented (false) or complete (true).
})
.catch(function (ex) {
// Navigation encountered an error.
});Listen to queue pointer events. See QueuePointerEventType for the events that are raised by the IQueuePointer object.
var queuePointer = reviewapi.viewer.mainCollection.queuePointer;
// Handle queue pointer updated event
queuePointer.on("updated", function (event) {
var currentIndex = event.currentIndex;
});Note: When the viewer collection has a new queue pointer, the IViewerCollection raises an event ViewerCollectionEventType.QueuePointerChanged. You may need to update your event handlers to respond to events from the new IQueuePointer and to disregard events from the legacy IQueuePointer.