Package 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

  • Method Details

    • 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:

    • 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