Wiki: DATA LOADER IDIF FORMAT

The following reviews what should be defined in IDIF when creating an interface format to be used to load an external file using LMTD.

Unless explicitly noted, IDIF fields are not used/referenced by the LMTD based functions (LBEN, LPTS, etc)

Define Interface Format (IDIF)#

Code: This field displays the user-defined Interface code.

Interface Type: Please select Not Specified; this is not used for LMTD. Selecting any other value will give a false sense of what variables are available.

Description: This is a user-defined description.

File Name: This field specifies the default file name.

Record Number: This field identifies the different record layouts. Numbers must be sequential without gap. Header records must be defined first, with a record type of "Header". Trailer records must be defined after the data record, with a record type of "Trailer"

Field Number: This field identifies the order of the fields and must be sequential, without a gap. For delimited fields, every column must be defined as there is no mechanism to skip fields.

Name: This field is composed of two parts: a table alias and a column name. For example, DCO.COUNTRY_CODE is a valid field name for a DIF Data Loader interface format. The table alias must be a valid table alias for a Business Class in the HL system. The column name does not need to be valid. For fields that are linked via ID, you must construct the sequence of tables to get to the value on the file. For example, BEL.EEM_ID.EID_ID.PERSON_CODE is used when loading the P2K_BE_ELECTIONS table (BEL) to identify the employee by PERSON_CODE which comes from the Employment record link (EEM_ID) to the Identity record link (EID_ID)

Beginning Position: If the source file data is 'Character Delimited', you must specify the Beginning position as '-1'. If the source file data is fixed position, this would indicate the starting character from the left for this field.

Ending Position: If the source file data is 'Character Delimited', you must specify the Ending position as '-1'. If the source file data is fixed position, this would indicate the ending character from the left for this field.

Field Type: This field is not used for LMTD; defaults to Char.

Record Type: Qualify Record, Header Record and Trailer Record are the only options available for LMTD purposes.

Constant Value: This field allows you to load a constant value for a specified field.

Derivation Expression: Derivation expressions may be used to reference the current field or other fields on the same record. Any PL/SQL built-in function or data base function may be used.

Record Skipping#

If a source file has header or trailer records, these must all be defined in the interface in IDIF. They must be defined with a record type of 'Header Record' or 'Trailer Record'. Each of the header and or trailer records must be defined so the LMTD knows how many records it must bypass before it tries to read and interpret the detail records. It is suggested that these Header and Trailer records be given a different record number so the interface is easier for users to read.

Virtual Columns#

Virtual columns could be columns that are required fields for the table but that are not included in the source file (may be derived or set to constant values as a result) or they could be used to help fill a unique key identifier. They may also be used for qualification of the records, as needed.

In a fixed-position IDIF, we can add virtual columns, by setting the Beg Posn and End Posn values to '-1'.

In a delimited IDIF, we can add virtual columns by setting the Beg Posn and End Posn values to '0'. Virtual columns can also be added to a comma delimited format by specifying -1 in the Beg Posn and End Posn. However, when using this type of virtual column in a comma delimited format, there must be a stub value provided in the file.

If there are virtual columns defined using either of the above set up and there is no value defined in the file there must be some sort of stub value defined in the Constant field or Derivation Expression.

The 'Constant Value' attribute allows you to load a constant value for a specified field. This value will override any value mapped to the field in the source file. You could enter a space in the Constant field to represent a blank value. or the word NULL in the derivation expression field to represent a NULL value.

For example, we have the following fields in the IDIF:
EID.PERSON_CODE, EID.GOVT_CODE_VERIFIED and we want to set a constant value for the EID.GOVT_CODE_VERIFIED field to 'Y'.

In the source file, we must have a "stub" value representing the field value for EID.GOVT_CODE_VERIFIED. This could look something like: 12345, or 12346,N or 12347,Y or , ,

It does not matter what the stub value is as it will be overridden with the constant value in the IDIF. It is only required that the stub value be there.

Each line of the source file is separated into field names and field values. Field names, as described in the previous section identify the base table and the column to load the field value into.

Foreign Columns#

Column names do not need to exist in the table and can be used to represent field names/values from a non-Wiki database. The values for these non-Wiki fields can be used to derive the values for Wiki columns before inserting/updating. The naming convention for non-Wiki columns is to prefix the column names with "F_". An example is PSL.F_TRANSACTION_CODE, where PSL determines the base table to load into (Sundries), F_ indicates it is a foreign column, and Transaction_Code is the foreign column name.

The LMTD function does support populating user-defined fields in a table. They are to be named the same as if they were a true database column.

To load a constant value of NULL, the user will need to set a string value of ' ' (2 consecutive single quotes) in the constant value field. This value avoids ambiguity between a string value of "NULL" and an actual NULL reference.

Business Logic#

You can now add fields to the IDIF to directly execute business logic before/during/after load process. These action type fields are similar in appearance to the regular fields in that they begin with the table alias of the EntityModel class in which the business logic resides followed by the name of the action column.

For example, to call the business logic in the action column of the TimeExceptions business class ACT_DIF_POST_INSERT_BUILD_SCHED, we specify a field name of TTX.ACT_DIF_POST_INSERT_BUILD_SCHED with beginning and ending positions of 0 since this is not an actual field in the load file. Using this in IDIF for a time exception load would cause the schedule to rebuild after time exceptions have been loaded in.

The name of the action columns also specifies the point at which the business logic is invoked during the load process. The action columns must begin with the following:

ACT_DIF_PRE_LOAD
ACT_DIF_POST_LOAD
ACT_DIF_PRE_UPDATE
ACT_DIF_POST_UPDATE
ACT_DIF_PRE_INSERT
ACT_DIF_POST_INSERT

When defining the interface it is very important that the correct data is provided for the column names. It is also important to define the correct Unique Keys (UKs) for a particular table so the system can correctly focus on the right record to update/insert. You can override with more UKs columns but if not all of the default ones are provided, the system will assume the values for the ones not provided are null.

You can also manually add columns to the destination tables' UK column set by toggling the 'Add to UK set' check box. This will only add the column as a UK column to the existing UK set for the destination table. It will not act as a UK set override.

An example of where this would be used is for loading into the Sundries table as there is no defined UK column set for that table. Fields which could be used to define a UK set for this table could be, PSL.START_DATE, PSL.PPC_ID.PC_CODE, PSLD.PPC_ID.PC_CODE, PSL.EEM_ID.EID_ID.PERSON_CODE.

Qualification#

You can now manually define record qualification using the IDIF. To do so, you must set the Record Type of the interface field to 'Qualify Record' and define a qualifying value for the field in the Constant Value field.

Derivation Expressions#

If the field value (before the application of derivation expression, if one exists) matches the value defined in the Constant Value field, then the record is qualified and permitted to be loaded. If the values do not match, the entire record is skipped. By default (if Record Type is not set) all records are qualified.

You can use an existing field to use as a record qualifier or you may create a foreign field to use a qualifier and reference another field using a derivation expression. The above example uses a foreign field as a qualifier record. In the example, if value in the time entered field in the file does not equal 00000000 then the value passes the case when scenario (true) and the record qualifies. If the value did equal 0000000 then the value would fail the case when clause (false) and the record would be bypassed.

To load derived values for columns, the 'Beg Posn' and 'End Posn' values for the interface field must be set to '-1'.

Value derivation or manipulation is respected by the LMTD using the IDIF screen. You populate the 'Derivation Expression' field on the IDIF screen for the field needed to manipulate or derive.