Oracle Assets Adjustments API Documentation Supplement (Doc ID 206474.1)

Applies to:

Oracle Assets - Version 11.5.10.2 and later
Information in this document applies to any platform.

Purpose

Oracle Assets Adjustments API

You can use the Adjustments API to adjust assets directly via PL/SQL rather than using the Oracle Assets interfaces listed above. The Adjustments API uses the FA_ADJUSTMENT_PUB.DO_ADJUSTMENT procedure. You can use this API if you have a custom interface that makes it difficult to use with the existing Oracle Assets interfaces for adjusting assets.

The Adjustments API allows you to automatically adjust the asset to the corporate book, as well as to the dependent tax books.

Oracle Assets also allows you to adjust assets using the following methods: You can adjust assets using the Asset Workbench (using the Source Lines and Books windows), Mass Additions, Mass Change, Mass Copy, and Tax Upload Interface user interfaces.

• Mass Additions: You use the Mass Additions process to make cost adjustments to existing assets.
• Mass Change: You use the Mass Change process to change financial information for existing assets.
• Mass Copy: You use the Mass Copy process to add existing assets to tax books.
• Cost Adjustments: You use the Upload Tax Book Interface to adjust cost and financial information in both Corp and Tax Books.  Note that reserve can only be modified in period of addition.
• Asset Workbench: You use the Asset Workbench to make changes to individual assets.

The Adjustment API will create new lines in fa_asset_invoices in all cases.  This is true even if the intent of the adjustment is to modify an existing adjustment.

You cannot adjust the Depreciate Flag of an asset as an adjustment that also adjusts other features.  Accordingly, if you wish to adjust Depreciate Flag you will need to submit the API twice to also adjust other values.  It should also be noted that an adjustment involving only the Depreciate Flag does not follow standard expensed or amortized logic, and will not trigger catchup depreciation.  This is standard behavior of the application.

The Adjustment API will force a rollback of periodic depreciation if the adjustment is done after preliminary depreciation is complete for a period in R12.  This is standard behavior in R12.  In 11i, however, the Adjustment API will not complete normally if periodic depreciation has been taken already, and users will need to rollback the book before using the API.

Alternate Ledger Currencies / Secondary Ledgers

If you have set up Reporting Currencies on your Corporate book(s) or Tax book(s) or have attached a Secondary Ledger to your Tax book(s), when you adjust assets using the Adjustments API, the API automatically adds these adjustments to the relevant books.  You will need to supply a rate for Cost Adjustments.

Scope

This document covers use of the Adjustment API for basic adjustments with and without invoice information attached.

See Note 456064.1 for a discussion of use of this API for Group Asset Member Reclasses; a sample script for that is available there as well.

Details

Adjustments API Description

You call the FA_ADJUSTMENT_PUB.DO_ADJUSTMENT () API to perform adjustment transactions. The following table provides the arguments, types, value, and descriptions of the elements in the FA_ADJUSTMENT_PUB.DO_ADJUSTMENT procedure.

Each argument has a prefix of P, X, or PX. These prefixes mean the following:

• P - indicates an In argument
• X - indicates an Out argument
• PX - indicates an argument that is both In and Out

TRANS_REC_TYPE Transaction Structure

The TRANS_REC_TYPE transaction structure contains information about the transaction, such as the transaction header ID and the transaction type code. The following table shows type and value information for each argument.

ASSET_HDR_REC_TYPE Asset Structure

The ASSET_HDR_REC_TYPE asset structure contains unique identification information for a given asset, such as the asset ID and book type code. The following table shows type and value information for each argument.

ASSET_FIN_REC_TYPE Asset Structure

The ASSET_FIN_REC_TYPE asset structure contains financial information for a given asset. The following table shows type and value information for each argument.

PCT -- PERCENT_SALVAGE_VALUE field determines the Salvage Value.  SUM -- Salvage Value is determined by sum of member assets' salvage value

amounts (available only for Group Assets).  Defaults to PCT for Group Assets.

|   |
| PRORATE_CONVENTION_ CODE | Optional | VARCHAR2(10) | Depreciation prorate convention.  Defaults to value in category |   |
| DEPRECIATE_FLAG | Optional |  
VARCHAR2(3) | Indicates whether the asset is depreciating.YES - Asset is depreciating
NO - Asset is not depreciating |   |
| ITC_AMOUNT_ID | Optional | NUMBER(15) |

Identifies the ITC rate. Defaults from previous

|   |
| BASIC_RATE | Optional | NUMBER | Base rate used to calculate depreciation amount for flat rate methods. Defaults from previous |   |
| ADJUSTED_RATE | Optional | NUMBER | Actual rate used to calculate depreciation for flat rate methods. Defaults from previous |   |
| BONUS_RULE | Optional | NUMBER | Bonus rule for an asset. Defaults from previous |   |
| CEILING_NAME | Optional | VARCHAR2(30) | Identifies a depreciation ceiling to be used in calculating depreciation. .Defaults from previous |   |
| RECOVERABLE_COST | Optional | NUMBER | Cost minus salvage value, or depreciation ceiling, whichever is lower.  Alterable only for extended life and assets using deprn limits. |   |
| DEPRN_LIMIT_TYPE | Optional | VARCHAR2(30) |

Indicates how depreciation limit is determined.  AMT -- Manually enter the Depreciation Limit (not available for Group Assets).  PCT --

ALLOWED_DEPRN_LIMIT field determines the depreciation limit amount.  SUM -- Depreciation limit amount is determined using the sum of member

assets' depreciation limit amounts  (available only for Group Assets).  NONE -- Depreciation limit is not used.  Defaults to PCT for Group Assets.

|   |
| ALLOWED_DEPRN_LIMIT | Optional | NUMBER | The default depreciation limit as a percentage of cost. |   |
| ALLOWED_DEPRN_LIMIT_AMOUNT | Optional | NUMBER | Cost without regard to any revaluations |
| PRODUCTION_CAPACITY | Optional | NUMBER | Capacity of a units of production asset. |   |
| REVAL_AMORTIZATION_ BASIS | Optional | NUMBER | Revaluation reserve used in calculating amortization of revaluation reserve. Updated only when the asset is revalued or has an amortized adjustment. |   |
| REVAL_CEILING | Optional | NUMBER | Upper limit for revaluing asset cost .0 (delta) |   |
| UNIT_OF_MEASURE | Optional | VARCHAR2(25) | Unit of measure of an units of production asset. Defaults from previous |   |
| UNREVALUED_COST | Optional | NUMBER | Cost without regard to any revaluations. Cost Value (delta)/ Calculated |   |
| SHORT_FISCAL_YEAR_ FLAG | Optional |  
VARCHAR2(3) | Indicates if asset is added in a short fiscal year
YES - Asset is in a short fiscal year
NO - Asset is not in a short fiscal year
Defaults from previous |   |
| CONVERSION_DATE | Optional | DATE | Date short tax year asset added to the acquiring company .Defaults from previous |   |
| ORIG_DEPRN_START_DATE | Optional | DATE | Date short tax year asset begin deprecating in the acquired company's books. Defaults from previous |   |
| GROUP_ASSET_ID | Optional | NUMBER(15) | Group asset's asset_id. Defaults from previous |   |
| OVER_DEPRECIATE_OPTION | Optional | VARCHAR2(30) |

Indicates whether a Group Assets should stop depreciating beyond its depreciation limit (recoverable cost if there is no depreciation limit defined).

NO -- Stop depreciating when the depreciation reserve reaches its depreciable limit.  YES -- Stop depreciating if depreciation reserve reaches its depreciable

limit because of an increase in depreciation expense.  DEPRN -- Group Asset will not stop depreciating.  Defaults to NO.

|   |
| REDUCTION_RATE | Optional | NUMBER |

Relevant for depreciable basis rule that is assigned to a depreciation method which uses reduction rate.

|   |
| REDUCE_ADDITION_FLAG | Optional | VARCHAR2(1) |

Indicates whether reduction rate should be applied for member asset additions.  This value is relevant for Group Assets only.  Y -- reduction rate should be

used.  N -- reduction rate should not be used.  Defaults to N.

|   |
| REDUCE_ADJUSTMENT_FLAG | Optional | VARCHAR2(1) |

Indicates whether reduction rate should be applied for member asset adjustments.  This value is relevant for Group Assets only.  Y -- reduction rate should be

used.  N -- reduction rate should not be used.  Defaults to N.

|   |
| REDUCE_RETIREMENT_FLAG | Optional | VARCHAR2(1) |

Indicates whether reduction rate should be applied for member asset retirements.  This value is relevant for Group Assets only.  Y -- reduction rate should be

used.  N -- reduction rate should not be used.  Defaults to N.

|   |
| RECOGNIZE_GAIN_LOSS | Optional | VARCHAR2(30) |

Indicates whether a member asset retirement should result in recognizing gain and loss amount.  YES -- Recognize gain and loss amount.  NO -- Do not

recognize gain and loss amount.

|   |
| RECAPTURE_RESERVE_FLAG | Optional | VARCHAR2(1) | Defaults to N. |   |
| LIMIT_PROCEEDS_FLAG | Optional | VARCHAR2(1) | Defaults to N. |   |
| TERMINAL_GAIN_LOSS | Optional | VARCHAR2(30) |

Indicates whether to recognize gain and loss when last member in a group asset is retired out of the group.  YES -- Recognize gain and loss amount

immediately.  NO -- Do not recognize gain and loss amount.  END_OF_YEAR -- Defer recognition of gain and loss amount until end of current fiscal year.

Defaults to YES.

|   |
| TRACKING_METHOD | Optional | VARCHAR2(30) |

Member Assets tracking option value.  ALLOCATE -- Allocate Group depreciation amount across the group's member assets.  CALCULATE -- Uses member

assets depreciation instead of group asset's depreciation.  Defaults to null.

|   |
| EXCESS_ALLOCATION_OPTION | Optional | VARCHAR2(30) |

Indicates whether excess from allocation of group depreciation expense across its member assets is reduced from group depreciation expense or reallocated to

its member assets.  DISTRIBUTE -- Reallocate the excess depreciation expense to member assets.  REDUCE -- Reduce the excess from the Group's

depreciation expense.

|   |
| ALLOCATE_TO_FULLY_RSV_FLAG | Optional | VARCHAR2(1) |

Indicates whether to allocate a group asset's depreciation amount to a fully reserved member asset.  Y -- Group Depreciation is allocated to a reserved

member asset.  N -- Group Depreciation is not allocated to fully reserved member assets.  Defaults to N if TRACKING_METHOD is ALLOCATE, else

defaults to null.  Only applicable if TRACKING_METHOD is ALLOCATE.

|   |
| DEPRECIATION_OPTION | Optional | VARCHAR2(30) |

Indicates whether member asset's depreciation expense should be calculated using group or member depreciation information.  GROUP -- Use Group Asset

depreciation information to calculate member asset depreciation expense.  MEMBER -- Use Member Asset depreciation information to calculate member

asset depreciation expense. Only applicable if TRACKING_METHOD is CALCULATE, defaults to GROUP in that case, otherwise to null.

|   |
| MEMBER_ROLLUP_FLAG | Optional | VARCHAR2(1) |

Indicates whether group asset depreciation amount is sum of member asset depreciation amounts.  This value is only relevant if TRACKING_METHOD is

CALCULATE and RECOGNIZE_GAIN_LOSS is enabled and TERMINAL_GAIN_LOSS is YES.  Y -- Sum Member Asset Depreciation to Group.  N -- Group

Depreciation amount is calculated using the Group's information.  Defauls to N if TRACKING_METHOD is CALCULATE, otherwise defaults to null.

|   |
| DISABLED_FLAG | Optional | VARCHAR2(1) | Indicates whether a Group Asset is disabled.  Y -- Group Asset is disabled.  N -- Group Assets is enabled.  Defaults to No. |   |
| GLOBAL_ATTRIBUTE1-30 | Optional | VARCHAR2(150) | Reserved for country-specific functionality. Defaults from previous |   |
| GLOBAL_ATTRIBUTE_ CATEGORY | Optional | VARCHAR2(30) | Reserved for country-specific functionality. Defaults from previous |   |
| Table 1 - 2. (Page 3 of 3) |

ASSET_DEPRN_REC_TYPE Asset Structure

The ASSET_DEPRN_REC_TYPE asset structure contains depreciation information for a given asset. The following table shows type and value information for each argument.

INV_TRANS_REC_TYPE Invoice Structure

The INV_TRANS_REC_TYPE invoice structure contains invoice transaction information for a given invoice. The following table shows type and value information for each argument.

INV_REC_TYPE Invoice Structure

The INV_REC_TYPE invoice structure contains invoice information for a single invoice associated with an asset. The INV_TBL is a table of INV_REC_TYPE records. These records contain all invoices that have been applied to the asset. The following table shows type and value information for each argument.

INV_RATE_REC_TYPE Invoice Structure

The INV_RATE_REC_TYPE invoice structure contains rate information for an invoice. Each INV_RATE_REC_TYPE record contains one conversion rate. The INV_RATE_TBL is a table of INV_RATE_REC_TYPE records. This table is used by MRC reporting books to determine the conversion rates for an asset. The following table shows type and value information for each argument.

EXCHANGE_RATE is not

specified.

| NUMBER | Provide converted cost directly rather than an exchange rate. |
| SET_OF_BOOKS_ID | Required when using Alternate Ledger Currency. | NUMBER(15) | Ledger identification number. |
| EXCHANGE_RATE | Optional (Required if COST is not specified). | NUMBER | Exchange rate for this currency. |
| Table 1 - 6. (Page 1 of 1) |

GROUP_RECLASS_OPTIONS_REC_TYPE Reclassification Structure

The GROUP_RECLASS_OPTIONS_REC_TYPE reclassification structure contains any group reclass options that may be changed during a transaction performed on a group asset. The following table shows type and value information for each argument.

Adjustment API Usage

The following section gives an overview of how to use the adjustment API in various scenarios including invoice vs. non-invoice scenarios as well as MRC. The same principles apply for adjustments in the period of addition vs. those after depreciation has been run as well as for all three types of assets: capitalized, CIP, and expensed.

When calling the new adjustment API, there are four possible ways in which you would call it as shown below:

• Invoice used without MRC enabled
• No invoice used and without MRC enabled
• Invoice used with MRC enabled
• No invoice used with MRC enabled

If invoices are involved ,either a new invoice or an adjustment / transfer to an existing invoice, then the API will use the information in the invoice table to calculate the change in the asset's financial information. Hence, there is no need to populate the FIN_REC_TYPE. On the other hand, if invoices are not involved, then the change in financial information is passed by directly populating the FIN_REC_TYPE.

In the case of ALC, the INV_RATE table must be populated when performing invoice transactions involving a new invoice line, mass addition or invoice addition. For adjustments/transfers on the source asset, the amounts will be derived within the invoice engine. The rate table should not be populated in non-invoice scenarios as the rate will be derived based on the transaction date.

Note: Remember that the new transaction APIs will operate on the concept of delta/change. Thus, you only need to populate values in the structures that are changing in the case of the fin, deprn and invoice structures. This is especially crucial with the amount columns. If you are changing the cost from 50000 to 60000, the cost value in the structure will be 10000. The sign is also important in a change that results in a decrease in a value, you should use the negative sign. Thus, a cost change from 60000 to 50000 would mean that cost would be populated with - 1000. The following sections detail the two primary methods in which you can call the adjustment API.

The following sections detail the two primary methods by which you can call the adjustment API.

Cost Adjustments

In the case where invoices are involved as part of the transaction, the amounts in the fin and deprn structures should not be populated as the invoice engine will calculate the total change internally within the API.

Note: When populating structures, you only need to populate the values which are changing and populate financial amounts with the delta change only. You do not need to update the new total.

Note: The adjustments API will treat null values as meaning no change. For non-incremental or amount columns which are being changed from a populated value to null, you must pass either FND_API.G_MISS_NUM, G_MISS_DATE, or G_MISS_CHAR, depending on the data type, in order to tell the API to null out the current value.

Calling the Adjustment API without Invoice Information

This section details how to call the API without passing in any invoice related information. This would be used for manual cost changes as well as changes to values like the date placed in service or the depreciation method for the asset. The following are the structures that are available and include details regarding values. It also indicates if values are required.

ASSET_HDR_REC_TYPE

You must populate the ASSET_ID AND BOOK_TYPE_CODE for the transaction. If the book is a corporate book, then the API will automatically process tax books in which the asset already exists and either CIP-in-tax (for CIP assets) or autocopy (for capitalized assets) are enabled. You should NOT populate SET_OF_BOOKS_ID nor period of addition as these are internal values to be calculated by the API itself.

TRANS_REC_TYPE

The TRANSACTION_SUBTYPE will default to EXPENSED so you should populate the TRANSACTION_SUBTYPE with AMORTIZED if you wish to instead amortize the adjustment. If TRANSACTION_SUBTYPE is AMORTIZED, you may optionally provide an amortization start date otherwise the adjustment will be amortized from the open period. TRANSACTION_TYPE_CODE, TRANSACTION_HEADER_ID and TRANSACTION_DATE_ENTERED will be derived within the API as will any other needed values. For expensed adjustments, the transaction date will be the last day of the open period. For amortized adjustments, it will be the amortization start date.

ASSET_FIN_REC_TYPE

When performing an adjustment without any invoice information, you should populate only the fields that are changing in the ASSET_FIN_REC_ADJ structure (such as COST, SALVAGE_VALUE, PRORATE_CONVENTION, etc). You should not populate system derived values such as RATE_ADJUSTMENT_FACTOR, ADJUSTED_COST, RECOVERABLE_COST, DEPRN_START_DATE, OR PRORATE_DATE. All such fields will be calculated internally.

ASSET_DEPRN_REC_TYPE

When adjusting a capitalized asset in the period of addition, the DEPRN_REC_TYPE can be populated for manual transaction. If using invoices, the depreciation related columns in the INV_REC_TYPE should be populated instead. The fields which are available are the ytd / accumulates amounts (such as YTD_DEPRN and DEPRN_RESERVE) for core, bonus and reval historical information.

Calling the Adjustment API with Invoice Information

This section details how to call the API when the adjustment will be initiated by an addition or change to invoice related information. In addition to those structures noted above, the following structures are now needed for such an adjustment. Additionally, the fin and deprn structure will not be populated in this mode since the API will calculate the total delta based on the sum of all invoices.

INV_TRANS_REC_TYPE

If you are using invoices, you must populate the TRANSACTION_TYPE_CODE. The INVOICE_TRANSACTION_ID should not be populated and will be derived within the API except in cases where the API is being called for the destination asset involved in a source line transfer.

INV_TBL_TYPE (table of INV_REC_TYPE)

When using invoices in the adjustment, you should populate all desired column with values for new invoice lines, such as MASS ADDITION / INVOICE ADDITION. For adjustments involving existing invoices, including INVOICE ADJUSTMENTS, DELETES, REINSTATES and TRANSFERS. You only need to input the value change in FIXED_ASSETS_COST.

• For example, if a source line currently has $250000 of cost and you are changing it to 200000, you would populate the INV_REC with -50000
• If you are deleting a line or reinstating a previously deleted line, you should only populate the DELETED_FLAG with the associated value, and no other columns should be populated.
• For new lines, you should always leave the SOURCE_LINE_ID null.
• For adjustments on existing source lines, each row in the invoice table should have the SOURCE_LINE_ID populated with the value of the line being altered.
• If using MRC, for new lines you must also populate the INV_INDICATOR with an incrementing value in the order the records are loaded into the table whether they are new lines or not.

INV_RATE_TBL_TYPE (table of INV_RATE_REC_TYPE)

When sending new invoices in an ALC-enabled corporate book, the exchange rates should be provided in this table for each source line and for each associated reporting book. The unique identifier for each row is the combination of the SET_OF_BOOKS_ID and the INV_INDICATOR. Therefore, you must populate the INV_INDICATOR, THE SET_OF_BOOKS_ID, and the EXCHANGE RATE for each row. The INV_INDICATOR will allow rows in this table to be matched up with their respective rows in the INV_TBL in the invoice engine. This table does not need to be populated when altering existing lines as the invoice engine will derive the correct exchange rate(s) from the existing row(s).

When using invoices in the adjustment, you should populate all desired column with  values for new invoice lines, such as MASS ADDITION / INVOICE ADDITION. For adjustments involving existing invoices, including INVOICE ADJUSTMENTS,
DELETES, REINSTATES and TRANSFERS. You only need to input the value change in FIXED_ASSETS_COST.

• For example, if a source line currently has $250000 of cost and you are changing it to 200000, you would populate the INV_REC with -50000.

• If you are deleting a line or reinstating a previously deleted line, you should only populate the DELETED_FLAG with the associated value, and no other columns should be populated.

• For new lines, you should always leave the SOURCE_LINE_ID as null.  For adjustments on existing source lines, each row in the invoice table should havethe SOURCE_LINE_ID populated with the value of the line being altered.

Assets Adjustment API Sample Scripts

R12 Adjustment API Sample Script without Invoice Information

R12 Adjustment API Sample Script with Invoice Information

R12 Adjustment API Sample Script with Invoice Information and Alternate Ledger Currency

R11i Adjustment API Sample Script without Invoice Information

R11i Adjustment API Sample Script with Invoice Information

Still Have Questions?

To discuss this information further with Oracle experts and industry peers, we encourage you to review, join or start a discussion in the My Oracle Support Fixed Assets Community.

To provide feedback on this note, click on the 'Rate this document' icon (+/-) top right of this frame.

References

NOTE:456064.1 - Suggestions for Converting to the Group Asset Structure in R12
NOTE:2550163.1 - How To NULL Certain Columns Via Oracle Assets Asset Description API
NOTE:827556.1 - Checking Depreciate Flag Checkbox After It Has Been Unchecked Does Not Cause Catchup Depreciation