oracle.ifs.fdk

Interface AuditManager

All Superinterfaces:

Remote

All Known Implementing Classes:

AuditManagerImpl, CoreAuditManager

public interface AuditManager
extends Remote

Auditing operations.

Method Summary

Modifier and Type	Method and Description
Item	createAuditReport(NamedValue[] searchOptions, NamedValue[] sortOptions, NamedValue[] reportOptions, AttributeRequest[] attrs) Creates an audit report given a search specification as a DocumentDefinition that can be used to create a Document later.
Item	createAuditTypeList(NamedValue[] def, AttributeRequest[] attrs) Creates an AuditTypeList.
long	findAuditHistory(String name) Returns the Audit History id associated with the specified name, or FDK_ITEM_NOT_FOUND exception, if no match can be found.
NamedValue[]	getAuditTypeEntries(NamedValue[] options) Returns the AuditTypeEntries for an Item type or that are contained within an existing AuditTypeList.
NamedValue[]	getAuditTypeEntriesFromAuditTypesList(long id) Returns the AuditTypes of an AuditTypeList.
Item	getAuditTypeList(String name, AttributeRequest[] attrs) Returns the AuditTypeList corresponding to the specified name.
ItemCertificate[]	getItemCertificates(long[] ids) Returns the ItemCertificates for the given Event IDs.
NamedValue[]	listAggregateEventColumnValues(String aggFunction, String[] columnNames, NamedValue[] searchOptions, NamedValue[] sortOptions) Returns an array of column values (each element of the array corresponds to a specific column).
String[]	listOperationActionSpecifications() Returns the list of registered operation action specification names.
void	postEvent(String opTypeKey, long targetItem, NamedValue[] optPayload) Posts a custom audit event.
void	removeAuditingConfiguration(long folderId) Removes the AuditingConfiguration from a Folder.
void	removeOperationConfiguration(long folderId) Removes the OperationConfiguration for a Folder.
Event[]	searchAuditHistory(NamedValue[] searchOptions, NamedValue[] sortOptions) Searches an Audit History, returning an array of matching Event instances.
void	setAuditingConfiguration(long folderId, NamedValue[] config) Sets the AuditingConfiguration for a Folder, replacing any existing AuditingConfiguration.
void	setOperationConfiguration(long folderId, NamedValue[] config) Sets the OperationConfiguration for a Folder, replacing any existing OperationConfiguration.
Item	updateAuditTypeList(long id, NamedValue[] def, AttributeRequest[] attrs) Updates the name or description of an existing AuditTypeList.

Method Detail

setAuditingConfiguration

void setAuditingConfiguration(long folderId,
                              NamedValue[] config)
                       throws FdkException

Sets the AuditingConfiguration for a Folder, replacing any existing AuditingConfiguration.

Clients may specify either an AuditTypeList ID for the new AuditingConfiguration to reference, or an explicit set of AuditTypes which will be used to create an unnamed AuditTypeList that is embedded in the new AuditingConfiguration.

Parameters:

folderId - The ID of the Folder on which to set the AuditingConfiguration.

config - The AuditingConfiguration options to set; must include one or more of the following Attributes:

• notation: {Attribute name, Attribute type}
• {Attributes.CONFIGURATION_FINAL, Boolean}
• {Attributes.CONFIGURATION_ENABLED, Boolean}
• {Options.AUDIT_TYPE_LIST_ID, Long}
• {Options.AUDIT_TYPES, NamedValue[]}
  • each element is a NamedValue where:
    • name = Operation Type Key (String)
    • value = Success Mode (Integer)

Throws:

FdkException - if the operation fails.

removeAuditingConfiguration

void removeAuditingConfiguration(long folderId)
                          throws FdkException

Removes the AuditingConfiguration from a Folder.

Parameters:

folderId - The ID of the Folder from which to remove the AuditingConfiguration.

Throws:

FdkException - if the operation fails.

setOperationConfiguration

void setOperationConfiguration(long folderId,
                               NamedValue[] config)
                        throws FdkException

Sets the OperationConfiguration for a Folder, replacing any existing OperationConfiguration. The entire configuration will be replaced as a set and not added to the existing one.

Parameters:

folderId - the folder for which to set the operation configuration

config - the operation configuration options to set; must include one or more of the following Attributes:

• notation: {Attribute name, Attribute type}
• {Attributes.CONFIGURATION_FINAL, Boolean}
• {Attributes.CONFIGURATION_ENABLED, Boolean}

Throws:

FdkException - if the operation fails.

removeOperationConfiguration

void removeOperationConfiguration(long folderId)
                           throws FdkException

Removes the OperationConfiguration for a Folder.

Parameters:

folderId - the folder from which to remove the configuration.

Throws:

FdkException - if the operation fails.

listOperationActionSpecifications

String[] listOperationActionSpecifications()
                                    throws FdkException

Returns the list of registered operation action specification names.

Returns:

An array of specification names.

Throws:

FdkException - if the operation fails.

postEvent

void postEvent(String opTypeKey,
               long targetItem,
               NamedValue[] optPayload)
        throws FdkException

Posts a custom audit event.

Parameters:

opTypeKey - The operation type key; must be a registered custom event operation key

targetItem - The target Item

optPayload - Optional event payload elements:

• notation: {Option name, Option type}
• {Options.EVENT_AUXILIARY_ITEM_IDS, Long[]}
• {Options.EVENT_AUXILIARY_STRING, String}
• {Options.EVENT_AUXILIARY_NUMBER, Long}
• {Options.EVENT_PROPERTIES, NamedValue[]}

Throws:

FdkException - if the operation fails.

searchAuditHistory

Event[] searchAuditHistory(NamedValue[] searchOptions,
                           NamedValue[] sortOptions)
                    throws FdkException

Searches an Audit History, returning an array of matching Event instances.

To specify an Audit Event search, first select the type of Audit History from which to search, using the Options.AUDIT_HISTORY_TYPE option. Allowed values:

• FdkConstants.AUDIT_HISTORY_GLOBAL
• FdkConstants.AUDIT_HISTORY_ITEM
• FdkConstants.AUDIT_HISTORY_CUSTOM

The following Audit History types require additional options:

• Specify the Options.AUDIT_HISTORY_ITEM_TARGET_ID option if the Audit History type is FdkConstants.AUDIT_HISTORY_ITEM, or for any search being performed by a non-administrator.
• Specify the Options.AUDIT_HISTORY_CUSTOM_ID option if the Audit History type is FdkConstants.AUDIT_HISTORY_CUSTOM.

After specifying the type of Audit History and its options, as described above, specify the filter options for the search (the 'where' clause), using the Options.EVENT_FILTER_*** options.

Each filter option is used to build a search expression made up of the =, >=, <=, or IN operators. The complete search query is the conjunction of each of the following expressions:

• FdkConstants.EVENT_COLUMN_ID >= Options.EVENT_FILTER_START_ID
• FdkConstants.EVENT_COLUMN_ID <= Options.EVENT_FILTER_END_ID
• FdkConstants.EVENT_COLUMN_CREATE_DATE >= Options.EVENT_FILTER_START_DATE
• FdkConstants.EVENT_COLUMN_CREATE_DATE <= Options.EVENT_FILTER_END_DATE
• FdkConstants.EVENT_COLUMN_CREATOR_ID IN Options.EVENT_FILTER_CREATORS
• FdkConstants.EVENT_COLUMN_OPERATION_TYPE IN Options.EVENT_FILTER_OPERATION_TYPES
• FdkConstants.EVENT_COLUMN_TARGET_ID IN Options.EVENT_FILTER_TARGETS
• FdkConstants.EVENT_COLUMN_OPERATION_SUCCESSFUL = Options.EVENT_FILTER_SUCCESS
• FdkConstants.EVENT_COLUMN_AUXILIARY_STRING = Options.EVENT_FILTER_AUXILIARY_STRING
• FdkConstants.EVENT_COLUMN_AUXILIARY_NUMBER = Options.EVENT_FILTER_AUXILIARY_NUMBER
• FdkConstants.EVENT_COLUMN_APPLICATION_CONTEXT = Options.EVENT_FILTER_APPLICATION_CONTEXT
• FdkConstants.EVENT_COLUMN_APPLICATION_USER = Options.EVENT_FILTER_APPLICATION_USER

Finally, specify the result size limit for the search, using the Options.EVENT_FILTER_RESULT_SIZE_LIMIT option. If this option is not set or has a value of null, there will not be a limit on the size of the result returned by this method.

Parameters:

searchOptions -

Options specifying the Audit History from which to search. A NamedValue[] of the form {String option-name, Datatype value}. Valid option-names and Datatypes:

• {Options.AUDIT_HISTORY_TYPE, Integer}
• {Options.AUDIT_HISTORY_ITEM_TARGET_ID, Long}
• {Options.AUDIT_HISTORY_CUSTOM_ID, Long}

Options to filter results; a NamedValue[] of the form {String option-name, Datatype value}. Valid option-names and Datatypes:

• {Options.EVENT_FILTER_START_ID, Long}
• {Options.EVENT_FILTER_END_ID, Long}
• {Options.EVENT_FILTER_START_DATE, Date}
• {Options.EVENT_FILTER_END_DATE, Date}
• {Options.EVENT_FILTER_CREATORS, long[]}
• {Options.EVENT_FILTER_OPERATION_TYPES, String[]}
• {Options.EVENT_FILTER_TARGETS, long[]}
• {Options.EVENT_FILTER_SUCCESS, Boolean}
• {Options.EVENT_FILTER_AUXILIARY_STRING, String}
• {Options.EVENT_FILTER_AUXILIARY_NUMBER, Long}
• {Options.EVENT_FILTER_APPLICATION_CONTEXT, String}
• {Options.EVENT_FILTER_APPLICATION_USER, String}
• {Options.EVENT_FILTER_RESULT_SIZE_LIMIT, Integer}

sortOptions -

Optional sort options (Event column-names and whether the columns should be sorted in ascending or descending order); may be null. A NamedValue[] of the form: {String column-name, Boolean ascending} . Valid column-names are:

• FdkConstants.EVENT_COLUMN_ID
• FdkConstants.EVENT_COLUMN_CREATE_DATE
• FdkConstants.EVENT_COLUMN_CREATOR_ID
• FdkConstants.EVENT_COLUMN_OPERATION_TYPE
• FdkConstants.EVENT_COLUMN_TARGET_ID
• FdkConstants.EVENT_COLUMN_OPERATION_SUCCESSFUL

Returns:

An array of Event instances that match the audit search specification.

Throws:

FdkException - if an error occurs.

listAggregateEventColumnValues

NamedValue[] listAggregateEventColumnValues(String aggFunction,
                                            String[] columnNames,
                                            NamedValue[] searchOptions,
                                            NamedValue[] sortOptions)
                                     throws FdkException

Returns an array of column values (each element of the array corresponds to a specific column). The values of each column contain the distinct values of the specified Event column names, as well as the value of the optional optional aggregate function.

See AuditManager.searchAuditHistory() for a description of the searchOptions method parameter.

There is one additional search option supported in this method:
{Options.AUDIT_EVENT_AGGREGATE_INNER_COLUMN_LIST, String[]}

The aggregate function name can be null, which is used for selecting distinct columns. Supported aggregate function names are "count(*)", or another SQL aggregate expression expressed in terms of one of the Event columns; for example "min(createdate)".

Parameters:

aggFunction - The aggregate function; can be null.

columnNames - Event column names for which to list distinct values.

sortOptions - Optional sort options results (Event column-names and whether that column should be sorted in ascending or descending order); may be null. A NamedValue[] of the form: {String column-name, Boolean ascending} . Column-names must be either the name of the specified aggFunction, or one of the columnNames.

Returns:

A NamedValue array corresponding to a list of column values of the specified aggregate function and the distinct values of the Event columns. The name of each NamedValue corresponds to the aggregate function or specified Event column name; the value of the NamedValue is an array of the appropriate datatype for the column or the result of the aggregate function. The value array may be of length one. Every element of the returned NamedValue[] are guaranteed to have value arrays of the same length. Note that for long[] and int[] arrays, -1 is used to represent null values, and for boolean[] arrays, null values are represented by a value of false.

Throws:

FdkException - if an error occurs.

createAuditReport

Item createAuditReport(NamedValue[] searchOptions,
                       NamedValue[] sortOptions,
                       NamedValue[] reportOptions,
                       AttributeRequest[] attrs)
                throws FdkException

Creates an audit report given a search specification as a DocumentDefinition that can be used to create a Document later.

Note that the name of the DocumentDefinition is always set to report-{date}.xml by default.

See AuditManager.searchAuditHistory() for a description of the searchOptions, and sortOptions method parameters.

Parameters:

reportOptions - The attributes or options for the DocumentDefinition:

• notation: {Attribute name, Attribute type}
• {Attributes.DESCRIPTION, String}
• {Options.DEFINITION_EXPIRATION_TIME, Long}

attrs - The requested attributes for the DocumentDefinition Item returned by this method.

Returns:

A DocumentDefinition Item that contains the audit report (in XML format) in its content.

Throws:

FdkException - if an error occurs.

getAuditTypeEntries

NamedValue[] getAuditTypeEntries(NamedValue[] options)
                          throws FdkException

Returns the AuditTypeEntries for an Item type or that are contained within an existing AuditTypeList.

This method can be used to fetch AuditTypeEntries for an Item type, or from an existing AuditTypeList, or a combination of both.

When fetching AuditTypeEntries for an Item type, it is possible to request only those AuditTypeEntries for that specific Item type, or to also include all Item types that can be contained by the specified Item type.

The containership (nesting) hierarchy is defined as follows:

   DOMAIN
     all Item types that are not contained in the folder hierarchy
     ARCHIVE
     CONTAINER
       WORKSPACE
         TRASH_FOLDER
         FOLDER
           DOCUMENT
           FAMILY
           LINK
           FOLDERLINK

Use Options.AUDIT_TYPE_ENTRY_INCLUDE_NESTED with a value of true to also fetch AuditTypeEntries for nested Item types.

When fetching AuditTypeEntries for an Item type without specifying an AuditTypeList ID, clients may also specify the default success mode value (using the AUDIT_TYPE_ENTRY_SUCCESS_MODE option) to be returned for each AuditTypeEntry NamedValue.

When fetching AuditTypeEntries when an AuditTypeList ID is specified, the only valid value for the AUDIT_TYPE_ENTRY_SUCCESS_MODE option is FdkConstants.AUDIT_TYPE_ENTRY_SUCCESS_MODE_NONE.

The AUDIT_TYPE_ENTRY_SUCCESS_MODE option has a default value of FdkConstants.AUDIT_TYPE_ENTRY_SUCCESS_MODE_NONE.

Parameters:

options - AuditTypeEntry options:

• notation: {Option name, Option type}
• {Options.AUDIT_TYPE_ENTRY_ITEM_TYPE, String}
• {Options.AUDIT_TYPE_ENTRY_SUCCESS_MODE, Integer}; allowed values:
  • FdkConstants.AUDIT_TYPE_ENTRY_SUCCESS_MODE_NONE
  • FdkConstants.AUDIT_TYPE_ENTRY_SUCCESS_MODE_SUCCESS_ONLY
  • FdkConstants.AUDIT_TYPE_ENTRY_SUCCESS_MODE_FAILURE_ONLY
  • FdkConstants.AUDIT_TYPE_ENTRY_SUCCESS_MODE_SUCCESS_OR_FAILURE
  default: FdkConstants.AUDIT_TYPE_ENTRY_SUCCESS_MODE_SUCCESS_ONLY
• {Options.AUDIT_TYPE_ENTRY_INCLUDE_NESTED, Boolean}; default: true
• {Options.AUDIT_TYPE_LIST_ID, Long}

Returns:

a NamedValue array representing each AuditTypeEntry, where each element is a NamedValue with its name set to the Event type and its value set to the success mode; the array is sorted by Event type

Throws:

FdkException - if the operation fails.

getAuditTypeList

Item getAuditTypeList(String name,
                      AttributeRequest[] attrs)
               throws FdkException

Returns the AuditTypeList corresponding to the specified name.

Parameters:

name - name of the AuditTypeList to return

attrs - requested attributes for the returned AuditTypeList

Returns:

AuditTypeList with the specified name, or null if no AuditTypeList with the specified name is found

Throws:

FdkException - if the operation fails

createAuditTypeList

Item createAuditTypeList(NamedValue[] def,
                         AttributeRequest[] attrs)
                  throws FdkException

Creates an AuditTypeList.

Once created, only the name or description of an AuditTypeList can be changed. AuditTypeLists are automatically deleted when they become unnamed and no longer referenced.

AuditTypeList Items are used in AuditingConfiguration instances and also to configure the global audit history for a Domain -- see DomainManager.updateDomain().

An AuditTypeList is made up of a set of AuditTypes, which are represented as NamedValue instances with operation type keys as names and operation success modes as values.

The AuditTypes in an AuditTypeList are used to filter the Events that are audited for:
- the item audit history (Items that have an AuditingConfiguration)
- the global audit history (all Items)

Valid Operation Type Keys are constants in the EventTypes class.

Valid Success Mode values are:

• FdkConstants.AUDIT_TYPE_ENTRY_SUCCESS_MODE_NONE
• FdkConstants.AUDIT_TYPE_ENTRY_SUCCESS_MODE_SUCCESS_ONLY
• FdkConstants.AUDIT_TYPE_ENTRY_SUCCESS_MODE_FAILURE_ONLY
• FdkConstants.AUDIT_TYPE_ENTRY_SUCCESS_MODE_SUCCESS_OR_FAILURE

Parameters:

def - array of attributes/options used to specify the characteritics of the AuditTypeList:

• notation: {Attribute name, Attribute type}
• {Attributes.NAME, String}
• {Attributes.DESCRIPTION, String}
• {Options.AUDIT_TYPES, NamedValue[]}
  • each element is a NamedValue where:
    • name = Operation Type Key (String)
    • value = Success Mode (Integer)

attrs - attributes to be returned for the returned Item

Returns:

an AuditTypeList Item

Throws:

FdkException - if the operation fails

updateAuditTypeList

Item updateAuditTypeList(long id,
                         NamedValue[] def,
                         AttributeRequest[] attrs)
                  throws FdkException

Updates the name or description of an existing AuditTypeList.

Parameters:

id - ID of the AuditTypeList to update

def - array of attributes/options used to specify the characteritics of the AuditTypeList:

• notation: {Attribute name, Attribute type}
• {Attributes.NAME, String}
• {Attributes.DESCRIPTION, String}

attrs - attributes to be returned on the return object

Returns:

an AuditTypeList Item

Throws:

FdkException - if the operation fails

getAuditTypeEntriesFromAuditTypesList

NamedValue[] getAuditTypeEntriesFromAuditTypesList(long id)
                                            throws FdkException

Returns the AuditTypes of an AuditTypeList.

The name of each AuditType is the operation type key and the value of each AuditType is an Integer reprsenting the operation success mode.

Parameters:

id - ID of the AuditTypeList

Returns:

NamedValue array representing a set of AuditTypes

Throws:

FdkException - if the operation fails

getItemCertificates

ItemCertificate[] getItemCertificates(long[] ids)
                               throws FdkException

Returns the ItemCertificates for the given Event IDs.

ItemCertificates are used to store the audit history of an Item beyond the life of the Item itself.

An ItemCertificate is created automatically when its corresponding Item is created, and it is updated one final time when its Item is freed, to record the fact that the Item was freed, and the deletor and freed date.

Parameters:

ids - Item IDs to use to lookup ItemCertificates

Returns:

ItemCertificate array with one element per Item ID

Throws:

FdkException - if the operation fails

findAuditHistory

long findAuditHistory(String name)
               throws FdkException

Returns the Audit History id associated with the specified name, or FDK_ITEM_NOT_FOUND exception, if no match can be found.

Parameters:

name - internal audit specification name for the history

Returns:

id value, or FdkException if no name match.

Throws:

FdkException - if the operation fails