The Example Import Allocations App

The Solutions Framework contains an example Import Allocations app, that is always up to date with the latest changes. Use this app to create an initial Import Allocations app, or to compare an existing Import Allocations app to the latest example.

To start configuration of the Import Allocations app:

1. Select the Design module.
2. In the Apps category, expand Configuration.
3. Expand Free Form.
4. Expand Existing Apps.
5. Click on Import Allocations to open it.
6. Click the Customize button.
7. Click Save.

Modifying the Import Allocations app

Import Allocations allows the user to import allocations into the system from a .csv file. Allocations currently in the system can either be replaced by the contents of the .csv import file or they can be appended to. If time period specific allocations are being used, allocations can be imported to a selected time period. Import Allocations is implemented as a free form app and can be modified in the Apps category of the Design tab of the client.

Execute Procedure

This is the controlling procedure for importing allocations. The following steps are performed:

• The import initialization procedure is run.
• The view initialization procedure is run.
• The validations initialization procedure is run.
• The allocation initialization procedure is run.
• The C_CONTEXT variable is created if it does not already exist.
• The dtAllocations table is added to the VIEW_DataList variable.
• A form is displayed to select the file to import. If time period specific allocations are being used, a time period selection is also included in the form.
• The import procedure is run.

Note: The default contents of the execute procedure should not be modified as they are required for certain code library processing. Additional code can be added to the execute procedure as required.

Import Form

The Import form is used to allow the user to select a file to import. The form also contains a checkbox to select whether allocations are going to be replaced or appended to.  If time period specific allocations are being used, the SelectTimePeriod form is also included in the import form.

Import Specs - Script

The app contains an AllocationsH (Header), AllocationsF (Footer) and AllocationsSetDefine (for the Set and Define statements) of the allocation import spec. These are used in the Generate Documents procedure to build the import spec file that defines what will be imported to the allocations table. All allocation columns are imported except for the following:

• ID: This is auto generated by the app.
• Attachments: Attachments cannot be imported.
• Timeperiod: If using time period specific allocations, the timeperiod in the import file is ignored. It is replaced by the time period selected in the import form.

Import Procedure

The app contains an Import Procedure. The following steps are performed:

• The ALLOC\GetNextAllocID procedure is run to determine the next available allocation ID in the database.
• The Generate Documents procedure is run to create the import file and datatable definition file based on the columns in the APP_ALLOC table.
• The datatable dtAllocations is created and downloaded containing all the allocations stored in the APP_ALLOC database table. If time period specific allocations are being used, only the allocations related to the time period selected will be downloaded.
• If time period specific allocations are being used, a list of RELID’s from the dtAllocations table is stored in order to define the list of rows to delete from the dtAreas table if required.
• The datatable dtAreas is created and downloaded containing all the area information stored in the LVAPP_AREAS database table.
• If “Replace allocations” was selected from the Import form, the contents of the dtAllocations table is cleared. Any allocations cleared from the dtAllocations table will also be cleared from the dtAreas table.
• The import is run to import the .csv file contents to the dtAllocations datatable
• The dtAllocations table is than processed to:
• Determine the correct ID’s to assign to the new allocations.
• For each allocation area column, the ALLOC\Retrieve ToObjectFromString procedure is run to convert the semi colon delimited area lists to area records in the LVAPP_Areas table. The standard allocation area columns include:
• Source
• Source Exceptions
• Source Offset
• Target
• Target Exceptions
• Pattern
• The VIEW\OnSave procedure is run. This will call the following two procedures described below:
  • Validate
  • Save
• If there are any validation errors, a message will be displayed informing the user that no allocations have been imported.

Validate Procedure

The app contains a validate procedure that will run all the standard allocation validations and provide a datatable output of any validations that did not pass.  If there are any custom validations required, this procedure would need to be modified accordingly.

Save Procedure

The app contains a save procedure that will upload the allocations if all validations have passed.  A message will be displayed informing the user that allocations have been successfully imported.

Generate Documents Procedure

This procedure creates both the import file and datatable definition file based on the columns in the APP_ALLOC table.

Persistent Table Definition

The app contains the Areas data table definition. This queries the LVAPP_AREAS table and will not require any modification.

Table Definition - Script

The app contains the Allocations data table definition. This queries the APP_ALLOC table. The table definition will include a time period filter if time period specific allocations are being used.

Publishing the import allocations app

The import allocations app should be published to the Import and Export category.

To publish the import allocations app:

1. Select the Design module.
2. In the Administration category, select Apps Publisher.
3. From the list of Apps, select Import Allocations.
4. From the list of User Groups, select the user groups that will require access to the import allocations app.
5. From the list of Categories, select MTCEIMPEXP - Maintenance - Import and Export.
6. The app should now be accessible from the Administration category of the Tax, Close, Plan or Transfer Pricing modules.