com.almworks.jira.structure.api.sync

Interface SyncAuditLog

@PublicApi
public interface SyncAuditLog

This interface is used by synchronizers to log audit information regarding their actions, configuration changes, etc. Synchronizers can optionally implement support for undoing action records from the audit log.

This component replaces Structure 2.x component SynchronizerUndoRecorder

Author:

Igor Sereda, Igor Baltiyskiy

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	SyncAuditLog.ActionGroup

Method Summary

Modifier and Type	Method and Description
List<SyncAuditLog.ActionGroup>	getActions(long syncInstanceId, long structureId, long timestampFrom, long timestampTo) Retrieve recorded actions.
boolean	isActionGroupRecorded(List<MapObject> actions) Checks if the synchronizer audit log that contains the specified actions is going to be actually recorded.
void	recordActions(long syncInstanceId, String syncModuleKey, long structureId, MapObject description, List<MapObject> actions) Like recordActions(SyncInstance, MapObject, List), but doesn't require a SyncInstance.
void	recordActions(SyncInstance syncInstance, MapObject description, List<MapObject> actions) Adds records to the audit log for a logical group of actions taken by one synchronizer in the course of one run.

Method Detail

recordActions

void recordActions(@NotNull
                   SyncInstance syncInstance,
                   @Nullable
                   MapObject description,
                   @Nullable
                   List<MapObject> actions)

Adds records to the audit log for a logical group of actions taken by one synchronizer in the course of one run. Can also be used to record meta-actions that affect multiple synchronizer instances.

The format of each action string is up to the synchronizer. If the synchronizer supports undo for the action, there should be enough information for it to perform the undo.

All records are represented as MapObjects. They are stored in JSON format as generated by MapObject.toString().

Parameters:

description - optional: description of the change

actions - a list of actions in the arbitrary format. If an action is null or an empty String, it is skipped. If the list is null or empty, no action records are created - only description record if description is provided

recordActions

void recordActions(long syncInstanceId,
                   @NotNull
                   String syncModuleKey,
                   long structureId,
                   @Nullable
                   MapObject description,
                   @Nullable
                   List<MapObject> actions)

Like recordActions(SyncInstance, MapObject, List), but doesn't require a SyncInstance.

Parameters:

syncInstanceId - ID of the sync instance or 0 if the actions refer to multiple synchronizers

syncModuleKey - module key of the synchronizer that performed the actions or an empty string if the actions refer to multiple synchronizer instances

structureId - ID of the structure, with which the synchronizer instance (or instances) is associated. 0 if the actions refer to synchronizer instances associated with multiple structures

See Also:

recordActions(SyncInstance, MapObject, List)

isActionGroupRecorded

boolean isActionGroupRecorded(@Nullable
                              List<MapObject> actions)

Checks if the synchronizer audit log that contains the specified actions is going to be actually recorded. This method can be used to check if there's a need to call recordActions(SyncInstance, MapObject, List) in case preparation of description is a resource-heavy operation.

Parameters:

actions - a list of actions to be later passed to recordActions

Returns:

true if recordActions will do any meaningful work

getActions

List<SyncAuditLog.ActionGroup> getActions(long syncInstanceId,
                                          long structureId,
                                          long timestampFrom,
                                          long timestampTo)

Retrieve recorded actions. You can filter the actions to get actions for a particular sync instance, for a period of time, or both.

The actions are grouped together so that each group corresponds to a single recordActions(com.almworks.jira.structure.api.sync.SyncInstance, com.almworks.jira.structure.api.util.MapObject, java.util.List<com.almworks.jira.structure.api.util.MapObject>) call. Action groups come in the order of decreasing timestamp

Note: the number of actions in the returned action groups is subject to the hard limit. If there are too many actions, the actions in the last action group might be truncated.

Parameters:

syncInstanceId - 0 or sync instance ID to filter by sync instance

structureId - 0 or structure ID to filter by sync instances installed on this structure

timestampFrom - minimum timestamp (ms from the Epoch), inclusive; Long.MIN_VALUE yields all actions from the beginning

timestampTo - maximum timestamp (ms from the Epoch), exclusive; Long.MAX_VALUE yields all actions until the end