Package com.documentum.fc.client

Interface IDfAuditTrailManager

public interface IDfAuditTrailManager
The Documentum server can log the occurrence of a predefined set of events to the audit trail. This interface allows the clients to specify which events should be logged. Clients can specify that an event be logged if it occurs for any object in the repository, or only if it occurs for instances of a type and its subtypes, or if it occurs for all instances of the type that are controlled by a specific application and/or a specific policy. Applications can define custom events; these events can be registered, but it is the application's responsibility to identify for which objects the events should be logged and to log the event when it detects the occurrence of the event.
Since:
5.1

  • Method Details

    • getAllEvents

      IDfList getAllEvents() throws DfException
      Gets a list of all the events(String) available in the repository.
      Returns:
      List of all events available in the repository.
      Throws:
      DfException

    • getApplicableEvents

      IDfList getApplicableEvents(IDfId objectId) throws DfException
      Gets a list of applicable events(String) for the object.
      Parameters:
      objectId - Object Id of an object instance or object type that can be audited. If this is an object instance, the method gets its object type to determine the applicable events. If null, the method returns all the available events in the repository. If the object id does not represent an auditable entity, the method returns an empty list.
      Returns:
      List of applicable events for the object.
      Throws:
      DfException

    • isEventAudited

      boolean isEventAudited(IDfId objectId, String event) throws DfException
      Indicates if this event is currently being audited for the object. The method returns true if there is any registration for auditing it, regardless of conditions of registration (controlling app and policy information).
      Parameters:
      objectId - Object Id of an object instance or object type that can be audited. If null, the method tests if the event is audited for the whole repository.
      event - Name of the event.
      Returns:
      True if the event is audited.
      Throws:
      DfException

    • isEventAuditedForType

      boolean isEventAuditedForType(String typeName, String event, String controllingApp, IDfId policyId, String stateName) throws DfException
      Indicates if this event is currently being audited for the object type. The arguments (controllingApp, policyId, stateName) define the conditions under which the event is registered for auditing. If included, the return value indicates whether the event is audited under those conditions.
      Parameters:
      typeName - The name of the type.
      event - Name of the event.
      controllingApp - Name of the application that controls this object. This parameter allows you to turn on auditing only when the object is controlled by this application. If it is set to null, the method tests for the existence of an object type event registration that is not controlled by any application.
      policyId - Object id of a dm_policy object. This parameter allows you to turn on auditing only when the object instance is controlled by this policy. If it is set to null, the method tests for the existence of an object type event registration that is not controlled by any policy.
      stateName - Name of the policy state that allows you to turn on auditing only when the object instance is in a particular state in the policy. This parameter is ignored if policyId is null.
      Returns:
      True if the event is audited.
      Throws:
      DfException

    • registerEvent

      void registerEvent(IDfId objectId, String event) throws DfException
      Registers an event for the object. Even if the object contains controlling app and policy information, it is ignored.
      Parameters:
      objectId - Object ID of the object or type. null if this is for the whole repository. If this is an object type, it behaves the same as registerEventForType with null controllingApp and policyId.
      event - Name of the event.
      Throws:
      DfException

    • registerEventForType

      void registerEventForType(String typeName, String event, boolean auditSubtypes, String controllingApp, IDfId policyId, String stateName, boolean signAudit, int authentication, String eventDescription, IDfList attributeList) throws DfException
      Registers an event for object type.
      Parameters:
      typeName - The name of an object type.
      event - Name of the event.
      auditSubtypes - Indicates if subtypes should also be audited.
      controllingApp - Name of the application that controls this object. This parameter allows you to turn on auditing only when the object instance is controlled by this application. If the event is dm_all_workflow or dm_all, do not use this parameter. Including it will cause an exception to be thrown. If it is set to null, this parameter is ignored.
      policyId - Object ID of a dm_policy object. This parameter allows you to turn on auditing only when the object instance is controlled by this policy. If it is set to null, this parameter is ignored. If the event is dm_all_workflow or dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      stateName - Name of the policy state that allows you to turn on auditing only when the object instance is in a particular state in the policy. If policy id is set to null, this parameter is ignored. If the event is dm_all_workflow, this parameter should not be used. Otherwise, an exception is thrown.
      signAudit - Defines whether the audit records created need to be signed. The default is false if not specified.
      authentication - Specify if an application must authenticate the user or require a signature before the event. If the event is dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      eventDescription - Specify a user-friendly description of the event. If the event is dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      attributeList - A list of attributes of the type that should be included in each audit record. If typeName is dm_process, this must contain attributes of dm_workflow. If the event is dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      Throws:
      DfException

    • registerEventForTypeEx

      void registerEventForTypeEx(String typeName, String event, boolean auditSubtypes, String controllingApp, IDfId policyId, String stateName, boolean signAudit, int authentication, String eventDescription, IDfList attributeList, boolean eSignatureRequired) throws DfException
      Registers an event for object type.
      Parameters:
      typeName - The name of an object type.
      event - Name of the event.
      auditSubtypes - Indicates if subtypes should also be audited.
      controllingApp - Name of the application that controls this object. This parameter allows you to turn on auditing only when the object instance is controlled by this application. If the event is dm_all_workflow or dm_all, do not use this parameter. Including it will cause an exception to be thrown. If it is set to null, this parameter is ignored.
      policyId - Object id of a dm_policy object. This parameter allows you to turn on auditing only when the object instance is controlled by this policy. If it is set to null, this parameter is ignored. If the event is dm_all_workflow or dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      stateName - Name of the policy state allows you to turn on auditing only when the object instance is in a particular state in the policy. If policy id is set to null, this parameter is ignored. If the event is dm_all_workflow, this parameter should not be used. Otherwise, an exception is thrown.
      signAudit - Defines if the audit records that will be created to be signed. The default is false if not specified.
      authentication - Specify if an application must authenticate the user or require a signature before the event. If the event is dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      eventDescription - Specify a user-friendly description of the event. If the event is dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      attributeList - A list of attributes of the type that should be included in each audit record. If typeName is dm_process, this must contain attributes of dm_workflow. If the event is dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      eSignatureRequired - Spefifies whether the event requires electronic signature
      Throws:
      DfException

    • registerEventForObject

      void registerEventForObject(IDfId objectId, String event, boolean signAudit, int authentication, String eventDescription, IDfList attributeList) throws DfException
      Registers an event for object instance.
      Parameters:
      objectId - Object id of an object instance.
      event - Name of the event.
      signAudit - Whether the audit records for the event must be signed by the server.
      authentication - Whether an application must authenticate the user before creating the audit trail entry for the event. If the event is dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      eventDescription - Specify a user-friendly description of the event. If the event is dm_all, this parameter should not be used. Including it will cause an exception to be thrown.
      attributeList - A list attribute names from the object's type to be included in each audit record. If the event is dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      Throws:
      DfException

    • registerEventForObjectEx

      void registerEventForObjectEx(IDfId objectId, String event, boolean signAudit, int authentication, String eventDescription, IDfList attributeList, boolean eSignatureRequired) throws DfException
      Registers an event for object instance.
      Parameters:
      objectId - Object id of an object instance.
      event - Name of the event.
      signAudit - Whether the audit records for the event must be signed by the server.
      authentication - Whether an application must authenticate the user before creating the audit trail entry for the event. If the event is dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      eventDescription - Specify a user-friendly description of the event. If the event is dm_all, this parameter should not be used. Including it will cause an exception to be thrown.
      attributeList - A list attribute names from the object's type to be included in each audit record. If the event is dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      eSignatureRequired - Spefifies whether the event requires electronic signature
      Throws:
      DfException

    • registerEventForObjectEx2

      void registerEventForObjectEx2(IDfId objectId, String event, boolean auditSubtypes, String controllingApp, IDfId policyId, String stateName, boolean signAudit, int authentication, String eventDescription, IDfList attributeList, boolean eSignatureRequired) throws DfException
      Registers an event for object type.
      Parameters:
      objectId - Object id of an object instance.
      event - Name of the event.
      auditSubtypes - Indicates if subtypes should also be audited.
      controllingApp - Name of the application that controls this object. This parameter allows you to turn on auditing only when the object instance is controlled by this application. If the event is dm_all_workflow or dm_all, do not use this parameter. Including it will cause an exception to be thrown. If it is set to null, this parameter is ignored.
      policyId - Object id of a dm_policy object. This parameter allows you to turn on auditing only when the object instance is controlled by this policy. If it is set to null, this parameter is ignored. If the event is dm_all_workflow or dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      stateName - Name of the policy state that allows you to turn on auditing only when the object instance is in a particular state in the policy. If policy id is set to null, this parameter is ignored. If the event is dm_all_workflow, this parameter should not be used. Otherwise, an exception is thrown.
      signAudit - Defines whether the audit records created need to be signed. The default is false.
      authentication - Specify whether an application must authenticate the user or require a signature before the event. If the event is dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      eventDescription - Specify a user-friendly description of the event. If the event is dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      attributeList - A list of attributes of the type that should be included in each audit record. If typeName is dm_process, this must contain attributes of dm_workflow. If the event is dm_all, do not use this parameter. Including it will cause an exception to be thrown.
      eSignatureRequired - Spefifies whether the event requires electronic signature
      Throws:
      DfException

    • registerEvents

      void registerEvents(IDfId objectId, IDfList events) throws DfException
      Registers a list of events for the object.
      Parameters:
      objectId - The object Id of the object or type. null if this is for the whole repository.
      events - A list of events.
      Throws:
      DfException

    • registerEventsFromQuery

      void registerEventsFromQuery(String query, IDfList events) throws DfException
      Registers the events specified in IDflist for the objects returned by the query.
      Parameters:
      query - The query to be run. For example: dm_sysobject where object_name='foo'
      events - A list of events.
      Throws:
      DfException

    • registerEventsInFolder

      void registerEventsInFolder(IDfId folderId, IDfList events) throws DfException
      Registers a list of events for all sysobjects under the folder.
      Parameters:
      folderId - The object id of the folder.
      events - A list of events
      Throws:
      DfException

    • setRegisterEvents

      void setRegisterEvents(IDfId objectId, IDfList events) throws DfException
      Sets a list of events for the object. This method clears the registration of the object and register the only events (with no controlling app and policy id) on the list.
      Parameters:
      objectId - The object id of the object or type. null if this is for the whole repository.
      events - A list of events.
      Throws:
      DfException

    • getRegisteredEvents

      IDfList getRegisteredEvents(IDfId objectId) throws DfException
      Gets a list of registered events(String) for the object. Even if the audit trail registration contains controlling app and policy information, it is ignored.
      Parameters:
      objectId - Object Id of an object instance or object type that can be audited. If null, the method returns the events audited for the whole repository. If this represents an object type, the method behaves the same as getRegisteredEventsForType with no controllingApp and policy information.
      Returns:
      List of events that is registered for the object.
      Throws:
      DfException

    • getRegisteredEventsForType

      IDfList getRegisteredEventsForType(String typeName, String controllingApp, IDfId policyId, String stateName) throws DfException
      Gets a list of registered events(String) for the object type.
      Parameters:
      typeName - The name of the object type
      controllingApp - The name of the application that controls this object. This parameter allows you to turn on auditing only when the object instance is controlled by this application. If it is set to null, the method tests for existence of object type event registration with no controlling application.
      policyId - Object id of a dm_policy object. This parameter allows you to turn on auditing only when the object is controlled by this policy. If it is set to null, the method tests for existence of object type event registration with no policy information.
      stateName - Name of the policy state allows you to turn on auditing only when the object is in a particular state in the policy. This parameter is ignored if policyId is null.
      Returns:
      List of events that is registered for the object type.
      Throws:
      DfException

    • unregisterEvent

      void unregisterEvent(IDfId objectId, String event) throws DfException
      Unregisters an event for the object.
      Parameters:
      objectId - The object ID of the object or type. null if this is for the whole repository. If this represents an object type, the method behaves the same as unregisterEventForType with no controlling app and policy information.
      event - The name of the event.
      Throws:
      DfException

    • unregisterEventForObject

      void unregisterEventForObject(IDfId objectId, String event, IDfId policyId, String stateName) throws DfException
      Unregisters an event for the object type. If you include the optional policy-related parameters, the method removes the registration for the event under those conditions.
      Parameters:
      objectId - The object ID of the object or type. null if this is for the whole repository. If this represents an object type, the method behaves the same as unregisterEventForType with no controlling app and policy information.
      event - The name of the event.
      policyId - Object ID of a dm_policy object. This parameter allows you to turn on auditing only when the object is controlled by this policy. If it is set to null, the method tests for existence of object type event registration with no policy information. If event is dm_all_workflow, do not use this parameter.
      stateName - Name of the policy state allows you to turn on auditing only when the object is in a particular state in the policy. This parameter is ignored if policyId is null.
      Throws:
      DfException

    • unregisterEventForType

      void unregisterEventForType(String typeName, String event, String controllingApp, IDfId policyId, String stateName) throws DfException
      Unregisters an event for the object type. If you include the optional parameters (controllingApp or policy-related parameters), the method removes the registration for the event under those conditions.
      Parameters:
      typeName - The name of the object type
      event - The name of the event.
      controllingApp - Name of the application that controls this object. This parameter allows you to turn on auditing only when the object instance is controlled by this application. If event is dm_all_workflow, do not use this parameter. If it is set to null, the method tests for the existence of an object type event registration with no controlling application.
      policyId - Object id of a dm_policy object. This parameter allows you to turn on auditing only when the object is controlled by this policy. If it is set to null, the method tests for the existence of object type event registration with no policy information. If event is dm_all_workflow, do not use this parameter.
      stateName - Name of a policy state; allows you to turn on auditing only when the object is in a particular state in the policy. This parameter is ignored if policyId is null.
      Throws:
      DfException

    • unregisterEvents

      void unregisterEvents(IDfId objectId, IDfList events) throws DfException
      Unregisters a list of events for the object.
      Parameters:
      objectId - The object ID of the object or type. null if this is for the whole repository.
      events - A list of events.
      Throws:
      DfException

    • unregisterEventsFromQuery

      void unregisterEventsFromQuery(String query, IDfList events) throws DfException
      For each object returned by the query, removes the registrations for the specified events.
      Parameters:
      query - The query to be run to retrieve the objects from which to remove the event registrations. For example: dm_sysobject where object_name='foo'
      events - A list of events.
      Throws:
      DfException

    • unregisterEventsInFolder

      void unregisterEventsInFolder(IDfId folderId, IDfList events) throws DfException
      Unregisters a list of events for all sysobjects under the folder.
      Parameters:
      folderId - The object ID of the folder.
      events - A list of events
      Throws:
      DfException

    • unregisterAllEvents

      void unregisterAllEvents(IDfId objectId) throws DfException
      Unregisters all events for the object. It includes event registration entries with controlling app and/or policy information.
      Parameters:
      objectId - The object ID of the object instance of type. If null, it represents the whole repository.
      Throws:
      DfException

    • createAudit

      IDfId createAudit(IDfId objectId, String event, String[] stringArgs, IDfId[] idArgs) throws DfException
      Creates an audit trail entry for application events. Use this method in an application to create an audit trail entry of type dm_audittrail for application events. Using this method to create a dm_audittrail object automatically sets many of the attributes in the object and saves the object when the method completes. (If you used IDfSession.newObject to create the audittrail object, you have to set each attribute individually and call save().) This method does not require a save method to save the audittrail entry. However, if you call createAudit in an explicit transaction, the audit trail object is not created until the transaction is explicitly committed. Anyone can use createAudit. No special permissions or privileges are needed.
      Parameters:
      objectId - Identifies the object of the audited event. Use the object's object ID.
      event - Identities the audited event. Use the event's name.
      stringArgs - Array of up to 5 additional string arguments
      idArgs - Array of up to 5 additional ID arguments
      Returns:
      ID of dm_audittrail object
      Throws:
      DfException
      Since:
      6.0

    • parseBatchedIds

      List<IDfPair<IDfId,String>> parseBatchedIds(IDfId audittrailId) throws DfException
      Get a list of BatchAudit from an audittrail object. When oneAuditPerBatch flag is turned on during the batch, The batch generates a dm_batch_flush audittrail for objects created inside the batch. Each dm_batch_auditrail entry can contain multiple object ids. This method parses the dm_batch_flush audittrail and returns the list of batched object id and operation pairs
      Parameters:
      audittrailId - The dm_batch_auditrail object id
      Returns:
      the list of id/operation pairs. Return null if the object is not a dm_batch_flush audittrail object, if the object does not exist, or there is no batched event
      Throws:
      DfException - if the object is not a dm_audittrail
      Since:
      6.5