The Financial Services Accounting Hub provides a set of common APIs to capture accounting events. All event operations must be performed through these APIs. By ensuring that event operations are executed through generic APIs, the architecture meets the following needs of implementers:
Insulates implementers from changes in the implementation of an API
The presence of the API reduces dependencies between the Financial Services Accounting Hub and the subledger applications.
Implementers do not have to know the underlying Financial Services Accounting Hub data model to capture accounting events. In addition, any implementation changes made by the Financial Services Accounting Hub has minimum or no impact on implementers.
Provides consistency in API calls across applications
The common API performs all necessary validations and guarantees a consistent implementation across applications.
The capture and recording of accounting events is an essential task. Accounting events are usually captured and recorded when they occur. Additionally, application features allow transactions that have been recorded, but not yet accounted, to be modified, canceled, or deleted. The routines for capturing and recording accounting events must take into account all of these circumstances without reducing user functionality.
The Accounting Program selects accounting events based on criteria specified by users. The Accounting Program does not check for any functional dependencies between transactions or event types.
Note: For each eligible event, the Accounting Program retrieves source values from the transaction objects. Since these events are used to create subledger journal entries, a great deal of information must be reliably obtained from the transaction data model.
See: Transaction Objects Guidelines
Implementers must undertake the following steps to seed calls to event capture routines:
This is a prerequisite step. Define and register event entities, event classes, and event types in the Accounting Methods Builder (AMB) before events can be captured. The event APIs use event information to perform the necessary validations when creating events.
See:
Event APIs provided by the Financial Services Accounting Hub are generic public APIs available to all applications. These APIs have generic parameters to suit a common purpose. For example, each API has a security context parameter to capture the transaction security context for an application.
In order to reduce dependencies and facilitate maintenance, it is recommended that you write a wrapper routine on top of the Financial Services Accounting Hub APIs. Wrapper routines can encapsulate application-specific logic to perform necessary validations before creating new events. Instead of calling a generic API, call this wrapper from the subledger application to perform the necessary event operations. Map application-specific parameters to the API generic parameters.
For example, Receivables can have a package called AR_XLA_EVENTS_PKG, which contains all the APIs to implement accounting events in Receivables. The code for this package is shown below.
Assume that Receivables has two event classes Receipts and Transactions. To handle accounting events for Receipts transactions, create a procedure create_receipt_event() with p_receipt_id as an input parameter, instead of using a generic parameters like source_id_int_1. The procedure create_receipt_event() calls the appropriate Financial Services Accounting Hub API to create an event.
Similarly, create create_transaction_event() to handle accounting events for the event class Transactions.
AR_XLA_EVENTS_PKG
-- Procedure to create events for Receivables receipts
PROCEDURE create_receipt_event
(p_receipt_id
,p_event_type
,p_event_date
,p_event_status) IS
l_receipt_source_info XLA_EVENTS_PUB_PKG.t_event_source_info;
l_security_context XLA_EVENTS_PUB_PKG.t_security;
BEGIN
-- Perform Product specific checks
...
-- Map generic event API parameter to the product specific columns
l_receipt_source_info.application_id = 202;
l_receipt_source_info.legal_entity_id = l_legal_entity_id;
l_receipt_source_info.source_id_int_1 = p_receipt_id;
-- Call XLA API
XLA_EVENTS_PUB_PKG.create_event
(p_event_source_info => l_receipt_source_info
,p_event_type_code => p_event_type
,p_event_date => p_event_date
,p_event_status_code => p_event_status
,p_event_number => NULL
,p_referenece_info => NULL
,p_security_context => l_security_context); ...
...
EXCEPTIONS
.... END;
To capture accounting events, make the necessary changes to your module's base code to integrate with event APIs or subledger specific wrapper APIs. Wrapper APIs are written over the Financial Services Accounting Hub's event APIs.
This integration enables the application modules to create, update, and delete accounting events when there is a corresponding business event on the transaction.
The API's discussed in this chapter are listed below:
Event Information
Event Status
Event Exists
Single Event
Events in Bulk
Event Status
Event Type, Event Date, Event Number, Event Reference Information
Update transaction Information
Transaction Number
The following sections describe these APIs and provide guidelines for their use in capturing accounting events. The Event API Details section furnishes code details on the APIs.
You may need to perform certain checks with respect to events. For example, before creating a new accounting event, it is necessary to check whether there is an existing unprocessed event for the same transaction with the same event type and event date. You may also want to know the status of a particular event or query events already created for the transaction.
To perform these checks, obtain relevant event information.
To obtain all the events related to a transaction, do the following:
Determine the system transaction identifier and event class for the transaction.
Note: System transaction identifiers identify the transaction on which transactions and events are based. The Financial Services Accounting Hub uses these identifiers to search the events table and identify all events related to this transaction.
Call the function Get_Array_Event_Info() with the appropriate transaction parameters. The function returns an array of all events for a transaction.
To obtain all the events created for a particular event type within a transaction, do the following:
Determine the system transaction identifiers, event class, and event type of the transaction.
Call the function Get_Array_Event_Info() with the appropriate transaction and event type input parameters. The function returns an array of all accounting events for that transaction and event type. Optionally pass the event class, event date, and event status to further restrict the rows returned.
To get information about a specific event, do the following:
Determine the event_id.
Call the function Get_Event_Info() with the event_id parameter. This function returns a PL/SQL record containing all information pertaining to that particular event.
The Event API Details section in this chapter provides information on the following APIs:
The Get_Event_Status API returns the event status for a specified event.
The Event_Exists API checks if an event exists for the specified criteria.
This section describes the following guidelines on creating events using the create event APIs:
To create a new event:
Determine the event type, event date, and event status for the new event.
Call the Financial Services Accounting Hub function Create_Event() with the appropriate input parameters.
The Create_Event() API creates a single event at a time. The function returns the event_id of the created event.
Create events in bulk using the API Create_Bulk_Events().
Note: Do not use this API for existing transactions that already have events associated with them. For performance reasons, bulk event APIs do not perform checks as to whether events for the transaction already exist. Therefore, use this API only to create events for new transactions that do not have any prior events created.
Changes made to transactions can impact one or more events associated with the transaction. Update the event to keep the transaction data and related events synchronized.
Update an event as long as it is not processed. Once an event is processed, you cannot update the event or the data associated with it.
Use the following APIs to update your events:
Update Event
This is an overloaded API used to update the status, type, date, number, and reference information of a single event.
Update Event Status
This API updates multiple events to a given status.
An event status reflects precisely where a transaction is in its accounting life cycle and what subsequent actions can be performed on the transaction data. Changes made to a transaction typically impacts the event status associated with the transaction. The new state of the transaction is reflected in an updated event status.
For example, when validating an invoice in Payables, its invoice status becomes Validated. This change in status also has an impact on the event status associated with this transaction. In this case, if the event associated with the transaction has a status Incomplete, it needs to be updated to status Unprocessed to reflect the current state of the transaction.
See: Event Status
To change the status of a specific event:
Determine the event ID and event status to set.
Call the Financial Services Accounting Hub function Update_Event() with the appropriate input parameters.
This API updates the status of a specific event.
To update the status of more than one event:
Determine the system transaction identifiers, event class, and event status to set.
Call the Financial Services Accounting Hub function Update_Event_Status() with the appropriate input parameters to update the status of all unprocessed events for the transaction.
In some situations, it is necessary to change the event type of an event. For example, if changing an existing transaction results in a new event, either create the new event or change the event type of the existing event. Assume there are two event types defined in Payables: Invoice Validated and Invoice Adjusted. Note the following points:
Any change made to the transaction after validation is considered to be an adjustment.
There can be only one Invoice validated event per invoice.
The event with the earliest GL date is the Invoice Validated event. The table below lists details along with corresponding event data of an invoice that is entered into the system and validated.
| Line Num | Line Type | Amount | GL Date | Event # | Event Type | Event Status |
|---|---|---|---|---|---|---|
| 1 | Item | 100 | 10-Jan-06 | 101 | Invoice Validated | Unprocessed |
After validating the invoice, the user adds a distribution dated 12-Jan-06. A new event is created Invoice Adjusted. The table below lists details of the corrected invoice along with corresponding event information.
| Line Num | Line Type | Amount | GL Date | Event # | Event Type | Event Status |
|---|---|---|---|---|---|---|
| 1 | Item | 100 | 10-Jan-06 | 101 | Invoice Validated | Unprocessed |
| 2 | Item | 300 | 12-Jan-06 | 102 | Invoice Adjusted | Unprocessed |
Now assume that the user changes the GL date on this new distribution from 12-Jan-06 to 08-Jan-06. The Invoice Adjusted event is changed to Invoice Validated since it now has a GL date earlier than the first line dated 10-Jan-06. Also, the original Invoice Validated event is updated to Invoice Adjusted as shown in the table below.
| Line Num | Line Type | Amount | GL Date | Event # | Event Type | Event Status |
|---|---|---|---|---|---|---|
| 1 | Item | 100 | 10-Jan-06 | 101 | Invoice Adjusted | Unprocessed |
| 2 | Item | 300 | 08-Jan-06 | 102 | Invoice Validated | Unprocessed |
A transaction's GL date and the event date associated with it must always be the same. If the transaction date is changed, then you must update the event date to keep the event and transaction consistent. If the subledger application supports multiple GL dates, then depending on the transaction data, changing a transaction date can result in the creation, update, or deletion of an existing event.
Consider the following three examples to explain these scenarios. In all of these examples, there is a transaction with multiple distribution lines that is entered into the system and approved. The transaction results in events being created. The user then changes the date on one of the distribution lines.
Example 1
The table below lists details, along with corresponding event data, of an invoice that is entered into the system and validated.
| Line Num | Event # | GL Date | Event Type | Event Status |
|---|---|---|---|---|
| 1 | 101 | 10-Jan-06 | Invoice Validated | Unprocessed |
| 2 | 101 | 10-Jan-06 | Invoice Validated | Unprocessed |
| 3 | 101 | 10-Jan-06 | Invoice Validated | Unprocessed |
The user changes the GL date on line #3 from 10-Jan-06 to 11-Jan-06 and reapproves the invoice. In this example, note the following:
There are other distribution lines associated with event #101 that are of the same event type.
There are no events of the same type for the date 11-Jan-06. (Processed events are not considered.)
Since there is no event of the same event type for the new GL date with an event status of Unprocessed, create a new event for this transaction line. The table below lists details of the invoice with the new event.
| Line Num | Event # | GL Date | Event Type | Event Status |
|---|---|---|---|---|
| 1 | 101 | 10-Jan-06 | Invoice Validated | Unprocessed |
| 2 | 101 | 10-Jan-06 | Invoice Validated | Unprocessed |
| 3 | 102 | 11-Jan-06 | Invoice Adjusted | Unprocessed |
Example 2
The table below lists details along with corresponding event data of two invoices that are entered into the system and validated.
| Line Num | Event # | GL Date | Event Type | Event Status |
|---|---|---|---|---|
| 1 | 102 | 11-Jan-06 | Invoice Validated | Unprocessed |
The user changes the GL date on line #1 from 10-Jan-06 to 11-Jan-06 and revalidates the invoice. In this example, note the following.
There are no other distribution lines associated with event #101 that are of the same event type for 10-Jan-06.
There is another event 102 of the same type for the date 11-Jan-06 with status Unprocessed.
Since there is an event of the same event type for the new GL date and with event status Unprocessed, delete event #101. Event #102 now represents transaction data for both distribution lines.
The table below lists details on Event #102.
| Line Num | Event # | GL Date | Event Type | Event Status |
|---|---|---|---|---|
| 1 | 102 | 11-Jan-06 | Invoice Validated | Unprocessed |
Example 3
The table below lists details, along with corresponding event data, of an invoice that is entered into the system and validated.
| Line Num | Event # | GL Date | Event Type | Event Status |
|---|---|---|---|---|
| 1 | 101 | 10-Jan-06 | Invoice Validated | Unprocessed |
The user changes the GL date on line #1 from 10-Jan-06 to 11-Jan-06 and revalidates the invoice. In this example, note the following:
There are no other distribution lines associated with event #101 that are of the same event type.
There are no events of the same type for the date 11-Jan-06.
Since there is no event of the same event type for the new GL date having an event status Unprocessed, do one of the following.
Update Event #101 to the new date. The table below lists details on the updated event #101.
| Line Num | Event # | GL Date | Event Type | Event Status |
|---|---|---|---|---|
| 1 | 101 | 11-Jan-06 | Invoice Validated | Unprocessed |
Delete event #101 and create a new event #102 with date 11-Jan-06. The table below lists details on this new event #102.
| Line Num | Event # | GL Date | Event Type | Event Status |
|---|---|---|---|---|
| 1 | 102 | 11-Jan-06 | Invoice Validated | Unprocessed |
Within a transaction, the Accounting Program processes events by event number. Along with other event information, the event number must be passed to the API at the time the event is created. If the API does not receive the event number, then the Create_Event() API inputs the next maximum event number for the transaction.
Once an event is created, a need may arise to change the event number because of changes taking place in the transaction. You can use the API Update_Event() to change an event's number. The ability to update event number gives you more control of the order in which events for a transaction are accounted.
Consider the following example to explain the behavior in which events are processed depending on event number. A transaction has events E1, E2 and E3 with event numbers 1, 3 and 5 respectively. Events E1 and E2 are in status Processed while E3 is Unprocessed.
The table below lists the name, number, and status of the transaction's events.
| Event Name | Event Number | Event Status |
|---|---|---|
| E1 | 1 | Processed |
| E2 | 3 | Processed |
| E3 | 5 | Unprocessed |
Now, assume that two more events E4 and E5 are created with event numbers 2 and 6. The table below lists the name, number, and status of these new events.
| Event Name | Event Number | Event Status |
|---|---|---|
| E4 | 2 | Unprocessed |
| E5 | 6 | Unprocessed |
The Accounting Program does not examine any events that have already been processed. However, the next accounting cycle processes the events in the order E4, E3, and E5.
To avoid the confusion involved in cases like this, it is strongly recommended that applications do not create any events with an event number less than the maximum event number of processed events. In the above example, the maximum event number of the processed events was 3, so event E4 should not have received an event number of 2.
Note: Do not attempt to create duplicate event numbers within a transaction as the API raises an exception during processing.
An event must be deleted if there is no transaction associated with it as when a transaction is deleted. In some cases, changing a GL date on a transaction might require deleting an event. Consider the following example.
The table below lists details, along with corresponding event data, of an invoice that is entered into the system and validated.
| Line Num | Event # | GL Date | Event Type | Event Status |
|---|---|---|---|---|
| 1 | 101 | 10-Jan-06 | Invoice Validated | Unprocessed |
| 2 | 101 | 10-Jan-06 | Invoice Validated | Unprocessed |
| 3 | 102 | 11-Jan-06 | Invoice Validated | Unprocessed |
The user then changes the GL date on line #3 from 11-Jan-06 to 10-Jan-06 and revalidates the invoice. In this example, note the following:
There are other distribution lines associated with 10-Jan-06 that are of the same event type as event #102.
There are no other distribution lines for event #102 of the same event type for the date 11-Jan-06, excluding Processed events.
Event #102 should be deleted, since there are no remaining lines associated with it. The table below lists details on the updated invoice along with corresponding event information.
| Line Num | Event # | GL Date | Event Type | Event Status |
|---|---|---|---|---|
| 1 | 101 | 10-Jan-06 | Invoice Validated | Unprocessed |
| 2 | 101 | 10-Jan-06 | Invoice Validated | Unprocessed |
| 3 | 101 | 10-Jan-06 | Invoice Validated | Unprocessed |
Call the Delete_Event() API to delete this event.
To delete all Unprocessed events associated with a transaction:
Determine the transaction source information.
Call the Financial Services Accounting Hub function Delete_Events() with the transaction source information.
Optionally, specify the event type, event status, or event date, to restrict the events deleted.
If a transaction is deleted, the Delete_Entity() API must be called to delete the row in the XLA_TRANSACTIONS_ENTITY table.
In the case where the transaction number of the transaction has been changed, this API updates the transaction number on the events in the XLA_TRANSACTION_ENTITIES table so that they are consistent with the transaction number on the transaction.
The API checks the source information for a valid application, legal entity, event entity, and source identifiers. However, no validation is performed on the transaction number.
This section describes the event APIs accessible by implementers to perform event operations. The APIs described are generic and available to all applications.
Event APIs have the following characteristics:
Event APIs do not issue any commits.
If an API fails, any changes made are rolled back and a standard exception is raised.
All parameters are read only (IN parameters); there are not OUT parameters.
An event date is always truncated.
The Financial Services Accounting Hub does not store the timestamp for an event date.
All functions return a single value or record.
The exception to this rule are the functions prefixed with a Get_Array string. For example, the function Get_Array_Event_Info() returns an array.
Input parameters must be passed in a nonpositional notation, named notation.
All the APIs called in query mode locks the event record in NOWAIT mode.
Event APIs have the following types of input parameters:
System transaction identifiers
These parameters capture information such as invoice_id or receipt_id. This information is stored with each event to later identify the source transaction for the event. You need to pass the source identifiers when creating an event.
Transaction security identifiers
Accounting events are subject to the security of the corresponding transaction. Every accounting event is stamped with its related transaction's security context. Transaction security parameters capture application-specific transaction security information, such as operating unit or asset book.
Security information is required to perform any event operation. Event APIs ensure that security context information is passed for each event. It is your responsibility to pass the correct security context.
Transaction reference information
The reference parameters enable you to capture any miscellaneous reference or contextual information for an event. This information is optional and no validations are performed against any reference parameters.
The XLA_EVENT_PUB_PKG package is defined by the Financial Services Accounting Hub. This package contains the following items:
PL/SQL record and table structures for common parameters
CONSTANTS for event statuses
Use these constants and structures when passing and reading values to and from the APIs. This is done to keep implementers shielded from the implementation of events.
See:
This section provides details on the APIs that obtain event information.
Summary
FUNCTION XLA_EVENTS_PUB_PKG.get_event_info
(p_event_source_info IN xla_events_pub_pkg.t_event_source_info
,p_event_id IN INTEGER
,p_valuation_method IN VARCHAR2
,p_security_context IN xla_events_pub_pkg.t_security)
RETURN xla_events_pub_pkg.t_event_info;
Description
This API returns information for a particular event. The event is identified by specifying the transaction and event identifier. The API locks the specified event before returning any event information.
Validations
The API checks all source information for valid application, legal entity, event entity, and source identifiers (IDs). It ensures that the required parameters are not passed as null and that the event ID belongs to the same transaction, as the other transaction information being passed.
Parameters
See: Common Parameters
Return Value
The API returns a PL/SQL record containing event information.
See: PL/SQL Data Types
Summary
FUNCTION XLA_EVENTS_PUB_PKG.get_array_event_info
(p_event_source_info IN xla_events_pub_pkg.t_event_source_info
,p_event_class_code IN VARCHAR2 DEFAULT NULL
,p_event_type_code IN VARCHAR2 DEFAULT NULL
,p_event_date IN DATE DEFAULT NULL
,p_event_status_code IN VARCHAR2 DEFAULT NULL
,p_valuation_method IN VARCHAR2
,p_security_context IN xla_events_pub_pkg.t_security)
RETURN xla_events_pub_pkg.t_array_event_info;
Description
This routine returns information for one or more events within a transaction. The calling program specifies the transaction and event selection criteria. Return information contains data on all events that belong to the specified transaction and fall under the given criteria. The API locks the specified events before returning the event information.
Validations
The API checks all source information for valid application, legal entity, event entity, and source IDs. It ensures that the required parameters are not passed as null and also validates the event class, event type, and event status. Note that the API truncates the event date.
Parameters
See: Common Parameters
Return Value
The API returns an array of event information.
See: PL/SQL Data Types
Summary
FUNCTION XLA_EVENTS_PUB_PKG.get_event_status
(p_event_source_info IN xla_events_pub_pkg.t_event_source_info
,p_event_id IN INTEGER
,p_valuation_method IN VARCHAR2
,p_security_context IN xla_events_pub_pkg.t_security)
RETURN VARCHAR2;
Description
This API returns the event status for a specified event. The calling program needs to specify the transaction and event identifier. The API locks the specified event record before returning the status.
Validations
The API checks all source information for valid application, legal entity, event entity, and source IDs. It ensures that the required parameters are not null and the event belongs to the same transaction as the other transaction information being passed.
Parameters
See: Common Parameters
Return Value
This API returns an event status. The Financial Services Accounting Hub has defined all event statuses as Constants.
See: Constants
Summary
FUNCTION XLA_EVENTS_PUB_PKG.event_exists
(p_event_source_info IN xla_events_pub_pkg.t_event_source_info
,p_event_class_code IN VARCHAR2 DEFAULT NULL
,p_event_type_code IN VARCHAR2 DEFAULT NULL
,p_event_date IN DATE DEFAULT NULL
,p_event_status_code IN VARCHAR2 DEFAULT NULL
,p_event_number IN INTEGER DEFAULT NULL
,p_valuation_method IN VARCHAR2
,p_security_context IN xla_events_pub_pkg.t_security)
RETURN BOOLEAN;
Description
This API checks whether an event exists for the specified criteria. It returns True if it finds at least one event matching the criteria; otherwise, it returns False. The API locks the event rows before returning a value.
Validations
The API checks all source information for valid application, legal entity, event entity, and source IDs. It ensures that the required parameters are not null and also validates the event class, event type, and event status. The API truncates the event date.
Parameters
See: Common Parameters
Return Value
The API returns True if an event is found for the specified criteria; otherwise, it returns False.
This section provides details on the APIs that create events.
Summary
FUNCTION XLA_EVENTS_PUB_PKG.create_event
(p_source_event_info IN xla_events_pub_pkg.t_event_source_info
,p_event_type_code IN VARCHAR2
,p_event_date IN DATE
,p_event_status_code IN VARCHAR2
,p_event_number IN INTEGER DEFAULT NULL
,p_reference_info IN xla_events_pub_pkg.t_event_reference_info DEFAULT NULL
,p_valuation_method IN VARCHAR2
,p_transaction_date IN DATE DEFAULT NULL
,p_security_context IN xla_events_pub_pkg.t_security
,p_budgetary_control_flag IN VARCHAR2)
RETURN INTEGER;
FUNCTION XLA_EVENTS_PUB_PKG.create_event
(p_event_source_info IN xla_events_pub_pkg.t_event_source_info
,p_event_type_code IN VARCHAR2
,p_event_date IN DATE
,p_event_status_code IN VARCHAR2
,p_event_number IN INTEGER DEFAULT NULL
,p_transaction_date IN DATE DEFAULT NULL
,p_reference_info IN xla_events_pub_pkg.t_event_reference_info DEFAULT NULL
,p_valuation_method IN VARCHAR2
,p_security_context IN xla_events_pub_pkg.t_security)
RETURN INTEGER;
Description
This API creates a new event. This function has two specifications, one with the p_budgetary_control flag and another without it.
Validations
The API checks all source information for valid application, legal entity, event entity, and source IDs. It ensures that the required parameters are not null and also validates the event type and event status.
No validations are performed against the reference columns and event number. However, if no event number is passed, the routine populates the next highest event number for that transaction. The event date is truncated.
Parameters
See: Common Parameters
Return Value
If an event is created successfully, then the function returns its event ID.
Summary
Procedure XLA_EVENTS_PUB_PKG.create_bulk_events
(p_source_application_id IN INTEGER DEFAULT NULL
,p_application_id IN INTEGER
,p_legal_entity_id IN INTEGER DEFAULT NULL
,p_ledger_id IN INTEGER
,p_entity_type_code IN VARCHAR2);
Description
This API creates multiple events for multiple transactions. Information required for each event is inserted into the XLA_EVENTS_INT_GT table as described below, before the API is called.
| Column Name | Data Type | Size | Required |
|---|---|---|---|
| ENTITY_CODE | VARCHAR2 | 30 | Yes |
| APPLICATION_ID | NUMBER | 15 | Yes |
| LEDGER_ID | NUMBER | 15 | Yes |
| EVENT_STATUS_CODE | VARCHAR2 | 30 | Yes |
| EVENT_TYPE_CODE | VARCHAR2 | 30 | Yes |
| EVENT_DATE | DATE | - | Yes |
| TRANSACTION_DATE | DATE | - | No |
| VALUATION_METHOD | VARCHAR2 | 30 | No |
| TRANSACTION_NUMBER | VARCHAR2 | 240 | No |
| BUDGETARY_CONTROL_FLAG | VARCHAR2 | 1 | No |
| SOURCE_ID_INT_1 | NUMBER | 15 | No |
| SOURCE_ID_INT_2 | NUMBER | 15 | No |
| SOURCE_ID_INT_3 | NUMBER | 15 | No |
| SOURCE_ID_INT_4 | NUMBER | 15 | No |
| SOURCE_ID_CHAR_1 | VARCHAR2 | 30 | No |
| SOURCE_ID_CHAR_2 | VARCHAR2 | 30 | No |
| SOURCE_ID_CHAR_3 | VARCHAR2 | 30 | No |
| SOURCE_ID_CHAR_4 | VARCHAR2 | 30 | No |
| SECURITY_ID_INT_1 | NUMBER | 15 | No |
| SECURITY_ID_INT_2 | NUMBER | 15 | No |
| SECURITY_ID_INT_3 | NUMBER | 15 | No |
| SECURITY_ID_CHAR_1 | VARCHAR2 | 30 | No |
| SECURITY_ID_CHAR_2 | VARCHAR2 | 30 | No |
| SECURITY_ID_CHAR_3 | VARCHAR2 | 30 | No |
| REFERENCE_NUM_1/REFERENCE_NUM_4 | NUMBER | 15 | No |
| REFERENCE_CHAR_1/REFERENCE_CHAR_4 | VARCHAR2 | 30 | No |
| REFERENCE_DATE_1/REFERENCE_DATE_4 | DATE | - | No |
Validations
The API checks all source information for valid application, legal entity, event entity, event number, and source IDs. It ensures that the required parameters are not null and also validates the event type and event status.
No validations are performed against the reference columns and event number.
Parameters
See: Common Parameters
The Update_Event_Status() API updates the event statuses of more than one event of a transaction.
There is a set of overloaded APIs that can be used to update more than one attribute for an event. These APIs update event type, event date, event status, event number, and reference information for an event. All of these API's use the Update_Event() API.
Note: Though these update event APIs retain the same name Update_Event(), they use the PL/SQL feature of overloading to create unique procedures. In overloading, the input parameter names and types are distinct, resulting in unique procedures. Different columns are updated in the tables, depending on which procedure is called.
For information on using overloading to create different procedure signatures, refer to the PL/SQL User Guide.
As discussed earlier, an event can be updated as long as it is not processed. Once an event is processed, you cannot update the event or the data associated with it.
This section provides details on the APIs that update events.
Summary
PROCEDURE XLA_EVENTS_PUB_PKG.update_event_status
(p_event_source_info IN xla_events_pub_pkg.t_event_source_info
,p_event_class_code IN VARCHAR2 DEFAULT NULL
,p_event_type_code IN VARCHAR2 DEFAULT NULL
,p_event_date IN DATE DEFAULT NULL
,p_event_status_code IN VARCHAR2
,p_valuation_method IN VARCHAR2
,p_security_context IN xla_events_pub_pkg.t_security);
Description
This API updates the event status of one or more events within a transaction matching the specified criteria.
Validations
The API checks all source information for valid application, legal entity, event entity, and source IDs. It ensures that the required parameters are not null. The API also validates event status and if passed, event class and event type. The event date is truncated.
Parameters
See: Common Parameters
Summary
PROCEDURE XLA_EVENTS_PUB_PKG.update_event
(p_event_source_info IN xla_events_pub_pkg.t_event_source_info
,p_event_id IN INTEGER
,p_event_type_code IN VARCHAR2 DEFAULT NULL
,p_event_date IN DATE DEFAULT NULL
,p_event_status_code IN VARCHAR2 DEFAULT NULL
,p_event_number IN INTEGER
,p_reference_info IN
xla_events_pub_pkg.t_event_reference_info
,p_valuation_method IN VARCHAR2
,p_security_context IN xla_events_pub_pkg.t_security);
,p_transaction_date IN DATE DEFAULT NULL)
Description
This API updates multiple attributes of a single event. Using this API, the calling program can update event type, event date, and event status. An error code is returned if the update fails.
Validations
This API checks all source information for valid application, legal entity, event entity, and source IDs. The API ensures that the event ID is not null, that it belongs to the same transaction as the other transaction information being passed, and that the event has not already been accounted.
The parameters event type, event date, and event status are also validated if passed Not Null.
See: Common Parameters
Summary
PROCEDURE XLA_EVENTS_PUB_PKG.update_event
(p_event_source_info IN xla_events_pub_pkg.t_event_source_info
,p_event_id IN INTEGER
,p_event_type_code IN VARCHAR2 DEFAULT NULL
,p_event_date IN DATE DEFAULT NULL
,p_event_status_code IN VARCHAR2 DEFAULT NULL
,p_event_number IN INTEGER
,p_valuation_method IN VARCHAR2
,p_transaction_date IN DATE DEFAULT NULL
,p_security_context IN xla_events_pub_pkg.t_security);
Description
This API updates multiple attributes of a single event. Using this API, the calling program can update event type, event date, event status, and event number. An error code is returned if the update fails.
Validations
The API checks all source information for valid application, legal entity, event entity, and source IDs. No validations are performed against the event number but if no event number is passed, the routine populates the next highest event number for that transaction. The event date is truncated.
The API ensures that the event ID is not null, that it belongs to the same transaction as the other transaction information being passed, and that the event has not already been accounted. The parameters event type, event date, and event status are also validated if passed Not Null.
Parameters
See: Common Parameters
Summary
PROCEDURE XLA_EVENTS_PUB_PKG.update_event
(p_event_source_info IN xla_events_pub_pkg.t_event_source_info
,p_event_id IN INTEGER
,p_event_type_code IN VARCHAR2 DEFAULT NULL
,p_event_date IN DATE DEFAULT NULL
,p_event_status_code IN VARCHAR2 DEFAULT NULL
,p_reference_info IN xla_events_pub_pkg.t_event_reference_info
,p_valuation_method IN VARCHAR2
,p_transaction_date IN DATE DEFAULT NULL
,p_security_context IN xla_events_pub_pkg.t_security);
Description
This API updates multiple attributes of a single event. Using this API, the calling program can update event type, event date, event status, and the event's reference information. An error code is returned if the update fails.
Validations
The API checks all source information for valid application, legal entity, event entity, and source IDs. No validations are performed on the reference information.
The API ensures that the event ID is not null, that it belongs to the same transaction as the other transaction information being passed, and that the event has not already been accounted. The parameters event type, event date, and event status are also validated if passed Not Null.
Parameters
See: Common Parameters
Summary
PROCEDURE XLA_EVENTS_PUB_PKG.update_event
(p_event_source_info IN xla_events_pub_pkg.t_event_source_info
,p_event_id IN INTEGER
,p_event_type_code IN VARCHAR2 DEFAULT NULL
,p_event_date IN DATE DEFAULT NULL
,p_event_status_code IN VARCHAR2 DEFAULT NULL
,p_event_number IN INTEGER
,p_reference_info IN xla_events_pub_pkg.t_event_reference_info
,p_valuation_method IN VARCHAR2
,p_security_context IN xla_events_pub_pkg.t_security);
Description
This API updates multiple attributes of a single event. Using this API, the calling program can update event type, event date, event status, event number, and the event's reference information. An error code is returned if the update fails.
Note: This API updates both the event's event number and reference information.
Validations
The API checks all source information for valid application, legal entity, event entity, and source IDs. The API ensures that the event ID is not null, that it belongs to the same transaction as the other transaction information being passed, and that the event has not already been accounted.
The parameters event type, event date, and event status are also validated if passed Not Null. No validations are performed against the event number and reference information, but if no event number is passed, the routine populates the next highest event number for that transaction.
Parameters
See: Common Parameters
Summary
Procedure XLA_EVENTS_PUB_PKG.update_bulk_event_statuses
(p_application_id IN INTEGER);
Description
This API updates the event status of multiple events. Before calling this API, users must populate the XLA_EVENTS_INT_GT table with the following:
application_id
entity_code
ledger_id
event_id
event_status_code
The API updates the events in the XLA_EVENTS table to the new status.
Validations
This API validates the application ID, event entity, event ID, and event status. The status of both the new and old status cannot be Processed. The new status must be a valid event status.
Parameters
See: Common Parameters
This section provides details on the APIs that delete events.
Summary
PROCEDURE XLA_EVENTS_PUB_PKG.delete_event
(p_event_source_info IN xla_events_pub_pkg.t_event_source_info
,p_event_id IN INTEGER
,p_valuation_method IN VARCHAR2
,p_security_context IN xla_events_pub_pkg.t_security);
Description
This API deletes an unaccounted event based on its event identifier. The API returns an error code if the delete fails.
Validations
The API checks all source information for valid application, legal entity, event entity, and source IDs. The API also ensures that the mandatory parameters are not null, that the event ID belongs to the same transaction as the other transaction information being passed, and that the event has not been accounted.
Parameters
See: Common Parameters
Summary
FUNCTION XLA_EVENTS_PUB_PKG.delete_events
(p_event_source_info IN xla_events_pub_pkg.t_event_source_info
,p_event_class_code IN VARCHAR2 DEFAULT NULL
,p_event_type_code IN VARCHAR2 DEFAULT NULL
,p_event_date IN DATE DEFAULT NULL
,p_valuation_method IN VARCHAR2
,p_security_context IN xla_events_pub_pkg.t_security)
RETURN INTEGER;
Description
This API deletes all events for a transaction that meet the specified criteria. When called, events that belong to the given event class, event type, and event date are deleted.
Validations
The API checks all source information for valid application, legal entity, event entity, and source IDs. It ensures that the required parameters are not null and if passed, validates the event type and event status.
Parameters
See: Common Parameters
Return Value
The function returns the number of events deleted.
If a transaction is deleted, users must call the DELETE_ENTITY API to delete the row in the XLA_TRANSACTION_ENTITIES table.
Summary
Function XLA_EVENTS_PUB_PKG.delete_entity
(p_source_info IN xla_events_pub_pkg.t_event_source_info
,p_valuation_method IN VARCHAR2
,p_security_context IN xla_events_pub_pkg.t_security)
RETURN INTEGER;
Description
This API deletes a row from the XLA_TRANSACTION_ENTITIES table. The routine checks if there are still events associated with the transaction. If yes, the routine does nothing and returns 1; otherwise, it deletes the transaction in the XLA_TRANSACTION_ENTITIES table and returns 0.
Validations
There are no validations for this API.
Parameters
See: Common Parameters
Summary
Procedure XLA_EVENTS_PUB_PKG.delete_bulk_events
(p_application_id IN INTEGER);
Description
This API deletes multiple events. Before calling this API, users must populate the XLA_EVENTS_INT_GT table with the following:
application_id
entity_code
ledger_id
event_id
event_status_code
The API deletes events from the XLA_EVENTS table.
Validations
This API validates the application ID, event entity, and event ID. The status of the event to be deleted cannot be processed.
Parameters
See: Common Parameters
The tables below provide details on the parameters common to many event APIs.
See: PL/SQL Data Types
The table below describes transaction identifier attributes.
| Parameter Name | Type | Description |
|---|---|---|
| p_transaction_number | Varchar2(240) | Transaction number of the transaction that the events are based on. This is the user transaction identifier and serves as a reference for the transaction. |
| p_event_source_info | xla_events_pub_pkg.t_event_source_info | System transaction identifiers (transaction identifiers); for example, invoice ID |
The table below describes contextual information details.
See:Create Accounting Concurrent Request
The table below describes transaction security identifier attributes.
| Parameter Name | Type | Description |
|---|---|---|
| p_security_context | xla_events_pub_pkg.t_Security | Security context information for the transaction which has created the events |
The table below describes transaction reference parameter attributes.
| Parameter Name | Type | Description |
|---|---|---|
| p_array_reference_info | xla_events_pub_pkg.t_array_event_reference_info | Array of optional reference information for multiple events. These are stored with the events. |
| p_reference_info | xla_events_pub_pkg.t_event_reference_info | Optional reference information for a particular event |
The table below describes event information parameter attributes.
| Parameter Name | Type | Description |
|---|---|---|
| p_entity_type_code | Varchar2(30 | Entity type internal code |
| p_event_class_code | Varchar2(30) | Event class internal code |
| p_event_type_code | Varchar2(30) | Event type internal code |
| p_event_id | Integer | Event internal identifier |
| p_event_date | Date | Event GL date |
| p_event_status_code | Varchar2(1) | External status code for an event |
| p_event_number | Integer | Event sequence number within a transaction. Events are ordered by this sequence number for accounting. |
| p_array_entity_source_info | xla_events_pub_pkg.t_array_entity_source_info | Array of transaction source ID information as stamped on the Entity |
| p_array_event_type_code | xla_events_pub_pkg.t_array_event_type_code | Array of internal codes for the event type as defined by applications |
| p_array_event_date | xla_events_pub_pkg.t_array_event_date | Array of GL dates for events |
| p_array_event_status_code | xla_events_pub_pkg.t_array_event_status_code | Array of external status codes for events |
| p_array_event_number | xla_events_pub_pkg.t_array_event_number | Array of event sequence numbers within a transaction. Events are ordered by these sequence numbers for accounting. |
| p_array_entity_event_info | xla_events_pub_pkg.t_array_entity_event_info | Array of combined entity and event attributes |
See: Creating Subledger Journal Entries from Accounting Events
The following are the predefined PL/SQL data structures available in the XLA_EVENTS_PUB_PKG package.
Transaction Source Information
TYPE t_event_source_info IS RECORD (source_application_id PLS_INTEGER DEFAULT NULL ,application_id PLS_INTEGER ,legal_entity_id PLS_INTEGER ,ledger_id PLS_INTEGER ,entity_type_code VARCHAR2(30) ,transaction_number VARCHAR2(240) ,source_id_int_1 PLS_INTEGER ,source_id_int_2 PLS_INTEGER ,source_id_int_3 PLS_INTEGER ,source_id_int_4 PLS_INTEGER ,source_id_char_1 VARCHAR2(30) ,source_id_char_2 VARCHAR2(30) ,source_id_char_3 VARCHAR2(30) ,source_id_char_4 VARCHAR2(30));
The table below provides descriptions on select attributes listed above.
| Attribute | Description |
|---|---|
| source_application_id | See description for p_source_application_id |
| application_id | Application transaction owner identifier |
| legal_entity_id | Transaction legal entity identifier |
| ledger_id | Transaction ledger identifier |
| entity_type_code | Entity code as defined by applications during setup |
| transaction_number | Transaction number of the transaction that has created the events. The transaction number serves as a reference for the transaction. |
| source_id_xxx_n | Generic columns that store the identifier for the transaction in the transaction table |
Event Reference Information
TYPE t_event_reference_info IS RECORD
(reference_num_1 NUMBER
,reference_num_2 NUMBER
,reference_num_3 NUMBER
,reference_num_4 NUMBER
,reference_char_1 VARCHAR2(240)
,reference_char_2 VARCHAR2(240)
,reference_char_3 VARCHAR2(240)
,reference_char_4 VARCHAR2(240)
,reference_date_1 DATE
,reference_date_2 DATE
,reference_date_3 DATE
,reference_date_4 DATE);
See: Attribute Table #2
Event Information
TYPE t_event_info IS RECORD
(event_id PLS_INTEGER
,event_number NUMBER
,event_type_code VARCHAR2(30)
,event_date DATE
,event_status_code VARCHAR2(1)
,process_status_code VARCHAR2(1)
,reference_num_1 NUMBER
,reference_num_2 NUMBER
,reference_num_3 NUMBER
,reference_num_4 NUMBER
,reference_char_1 VARCHAR2(240)
,reference_char_2 VARCHAR2(240)
,reference_char_3 VARCHAR2(240)
,reference_char_4 VARCHAR2(240)
,reference_date_1 DATE
,reference_date_2 DATE
,reference_date_3 DATE
,reference_date_4 DATE);
See: Attribute Table #2
Entity and Event Information (including security contexts)
TYPE t_entity_event_info IS RECORD
(event_type_code VARCHAR2(30)
,event_date DATE
,event_id PLS_INTEGER
,event_number NUMBER
,event_status_code VARCHAR2(1)
,transaction_number VARCHAR2(240)
,source_id_int_1 PLS_INTEGER
,source_id_int_2 PLS_INTEGER
,source_id_int_3 PLS_INTEGER
,source_id_int_4 PLS_INTEGER
,source_id_char_1 VARCHAR2(30)
,source_id_char_2 VARCHAR2(30)
,source_id_char_3 VARCHAR2(30)
,source_id_char_4 VARCHAR2(30)
,reference_num_1 NUMBER
,reference_num_2 NUMBER
,reference_num_3 NUMBER
,reference_num_4 NUMBER
,reference_char_1 VARCHAR2(240)
,reference_char_2 VARCHAR2(240)
,reference_char_3 VARCHAR2(240)
,reference_char_4 VARCHAR2(240)
,reference_date_1 DATE
,reference_date_2 DATE
,reference_date_3 DATE
,reference_date_4 DATE
,valuation_method VARCHAR2(30)
,security_id_int_1 INTEGER
,security_id_int_2 INTEGER
,security_id_int_3 INTEGER
,security_id_char_1 VARCHAR2(30)
,security_id_char_2 VARCHAR2(30)
,security_id_char_3 VARCHAR2(30));
The table below provides descriptions on select attributes listed above.
| Attribute | Description |
|---|---|
| event_type_code | Code for the event type of the event, as defined during setup |
| event_date | Event GL date |
| event_id | Event internal identifier |
| event_number | Event sequence number for the event within a transaction. Events are processed in the order of their event number. |
| event_status_code | Status code for the event. This is the event's external status and is used by implementers. |
| transaction_number | Transaction number of the transaction that has created the events. The transaction number serves as a reference for the transaction. |
| source_id_xxx_n | Generic columns that store the identifier for the transaction in the transaction table |
| reference_xxx_n | Generic columns that store reference information for the event |
| valuation_method | Valuation method code used as a security context for applications that support the valuation method |
| security_id_xxx_n | Security contexts |
Security Context Information
Security Context Information restricts the results of drill-downs. For example, setting the profile option SLA: Enable Subledger Transaction Security in GL to Yes for a specific user limits the transactions that a user can query.
Use the following record structure to pass security context information through event APIs. This structure is defined in XLA_EVENTS_PUB_PKG package.
TYPE t_security IS RECORD
(security_id_int_1 INTEGER
,security_id_int_2 INTEGER
,security_id_int_3 INTEGER
,security_id_char_1 VARCHAR2(30)
,security_id_char_2 VARCHAR2(30)
,security_id_char_3 VARCHAR2(30));
The table below provides descriptions for the attributes listed above.
| Attribute | Description |
|---|---|
| security_id_int_n | Security context information in INTEGER type |
| security_id_char_n | Security context information in VARCHAR type |
Array of Information based on above Structures
TYPE t_array_event_reference_info IS TABLE OF t_event_reference_info
TYPE t_array_event_info IS TABLE OF t_event_info
TYPE t_array_event_source_info IS TABLE OF t_event_source_info
TYPE t_array_entity_event_info IS TABLE OF t_entity_event_info
Other Array Structures
TYPE t_array_event_type IS TABLE OF VARCHAR2(30)
TYPE t_array_event_date IS TABLE OF DATE
TYPE t_array_event_status_code IS TABLE OF VARCHAR2(1)
TYPE t_array_entity_id IS TABLE OF PLS_INTEGER
TYPE t_array_event_id IS TABLE OF PLS_INTEGER
TYPE t_array_event_number IS TABLE OF NUMBER
The Financial Services Accounting Hub uses predefined accounting event status Constants. These constants are defined in the XLA_EVENTS_PUB_PKG package.
The table below lists event statuses and the corresponding constants that must be used when employing event APIs.
| Event Status | Constant |
|---|---|
| Incomplete | XLA_EVENTS_PUB_PKG.C_EVENT_INCOMPLETE |
| Unprocessed | XLA_EVENTS_PUB_PKG.C_EVENT_UNPROCESSED |
| No Action | XLA_EVENTS_PUB_PKG.C_EVENT_NOACTION |
| Processed | XLA_EVENTS_PUB_PKG.C_EVENT_PROCESSED |