Import Event Handlers

Import Specification Event Handlers

The Kourier Import Event Handlers are used while processing Import Specifications to provide a method for adding specific logic, data manipulation, and invocation of application programming interfaces (APIs) while preparing to write incoming data to a U2 file. Each Event Handler has a specific timing and usage during an import, with access to the Kourier Import variables to manage the data.

The table below describes each event and a summary of how it is used within the import processing:

Field Name	Description - Usage - Notes
Before Read	The Before Read event happens before Kourier reads a record from the incoming file. This event always happens regardless of the Support Operations setting on the Import Specification. Use this event to override the read instead of having Kourier doing the read. Typically, this event will be used to assign the item-id (RID$) to be read or to initialize other variables prior to Kourier attempting to read a record (RECORD$) from the file (FILENAME$) specified in the import specification.
After Read	The After Read event happens after Kourier has read the record from the incoming file. This event always happens regardless of the Support Operations setting on the Import Specification. This event can be used to set variables prior to Kourier processing the fields specified in the Import Specification. Typically, this event will be used to assign default values in the RECORD$ variable.
Before Update	The Before Update event happens before Kourier is about to write a record to the Target File specified on the Import Specification. This event only happens if the Supported Operations includes either an "Insert" or "Update" operation. This event is used to handle any logic or additional file/record updates that must take place when the current record is inserted or updated. It is typically used to prepare the data and assign other variables or values before calling the API (Application Programming Interface) for a target U2 application. For example, before creating a CUSTOMER or ORDER record in an ERP system, you would call the API that manages the complexities of creating or updating those records.
Before Delete	The Before Delete event happens before Kourier is about the delete a record from the Target File specified on the Import Specification. This event only happens if the Supported Operations includes a "Delete" operation. This event is used to handle any logic or additional file/record updates or deletes that must take place when the current record is deleted. It is typically used to prepare the data and assign other variables or values before calling the API (Application Programming Interface) for deleting a record in the target U2 application. For example, before deleting a ORDER record in an ERP system, you would call the API that manages deleting the record (and perhaps any associated records such as line items) and handles any other complexities involved.

Before Read Handler

The Before Read event happens before Kourier reads a record from the incoming file. Use this handler to set variables prior to Kourier attempting to read a record (RECORD$).

note

WidgetNote

The Before Read event always happens regardless of the Supported Operations setting on the Import Specification.

Use this event to override the read of the record instead of having Kourier doing the read. Typically, this event will be used to assign the item-id (RID$) to be read or to initialize other variables prior to Kourier attempting to read a record (RECORD$) from the file (FILENAME$) specified in the import specification.

This event can also be used to read the record directly. In this case, the programmer must indicate to Kourier that it should not read the record by setting the variable SKIP$ to 1 and then the programmer is required to set the following Kourier Import variables:

FILENAME$ (if different from design time value of Target File Name)
F.FILENAME$ (if different from the design time value of Target File Name)
RID$
RECORD$
RECISNEW$
RECISLOCKED$

Before Read Example

This is an example of reading the record directly from one of two files.

The Target File Name in the Import has been specified as NS.PRODUCT. Records to be updated will either exist in the NS.PRODUCT file or the PRODUCT file. If the record can’t be read from either file an application exception will be raised.

READU RECORD$ FROM F.FILENAME$, RID$ ELSE
  RELEASE F.FILENAME$, RID$
  FILENAME$ = 'PRODUCT'
  OPEN FILENAME$ TO F.FILENAME$ THEN
    READU RECORD$ FROM F.FILENAME$,RID$ ELSE
      RELEASE F.FILENAME$, RID$
      APP.ERR$ = \Could not read record \:RID$:\ from either NS.PRODUCT or PRODUCT files.\
      RETURN
    END
  END
END
SKIP$ = 1;        * Tell Kourier To Not Read Record
RECISNEW$ = 0
RECISLOCKED$ = 1

Before Read Example Notes

Upon entry into the Before Read event, the FILENAME$ variable will contain the value of the Target File Name, in this case NS.PRODUCT and the F.FILENAME$ variable is a file-pointer to that file. The RID$ variable will contain the item-id of the record to be read.

If the locked read from the NS.PRODUCT file fails, the READU lock is released on the NS.PRODUCT file and the FILENAME$ and F.FILENAME$ variables are re-assigned to PRODUCT on lines 2-4.

Re-assigning these variables is important because Kourier will use these variables when writing the record to disk, releasing locks and when generating event log entries and messages.

If the locked read of the PRODUCT file fails, the READU lock is released on line 6 and an application error message is returned by setting the value of the APP.ERR$ variable on line 7 and exiting the event timing by specifying a RETURN statement on line 8.

If either locked read is successful on line 1 or 5 then the following variable are set to the correct values:

RECISNEW$ is set to 0 (False) - This is NOT a new record
RECISLOCKED$ is set to 1 (True) - Record IS locked
SKIP$ is set to 1 (True) - Tell Kourier NOT to read the record

After Read Handler

The After Read event happens after Kourier has read a record from the incoming import file. Use this handler to set variables prior to Kourier processing the fields specified in the Import Specification.

note

WidgetNote

The After Read event always happens regardless of the Supported Operations setting on the Import Specification.

Typically, this event will be used to assign default values in the RECORD$ variable.

After Read Example

This is a simple example of assigning default values if the record to be processed is new and does not exist on the Target File Name, then the original entry date/time fields will be updated.

 IF RECISNEW$ THEN
  RECORD$<20> = DATE();  * Original Entry Date
  RECORD$<21> = TIME();  * Original Entry Time
END

After Read Example Notes

Upon entry into the After Read event, the RECISNEW$ variable is checked. If the record is new (RECISNEW$ = 1), then set attribute 20 on the current record to the current date, and then set attribute 21 to the current time.

Before Update Handler

The Before Update event happens before Kourier is about to write a record to the Target File specified on the Import Specification. This event is used to handle any logic or additional file/record updates that must take place when the current record is inserted or updated.

note

WidgetNote

The Before Update event only happens if the Supported Operations on an Import Specification includes either an "Insert" or "Update" operation.

The Before Update event is typically used to prepare the data and assign other variables or values before calling the API (Application Programming Interface) for a target U2 application. For example, before creating a CUSTOMER or ORDER record in an ERP system, you would call the API that manages the complexities of creating or updating those records.

Before Update Example

This is an example of setting up the proper variables and then calling an external UniBASIC subroutine to update a CUSTOMER file in a U2 database.

SKIP$ = 1;                            * Tell Kourier To Skip Its File-Time Processing
IF NOT(ISATEST$) THEN
  CALL KS.CUST.IMPORT(RECORD$,IUD$,RID$,XID$,FATAL.PARMS$,APP.ERR$)
  IF FATAL.PARMS$ NE '' THEN  FATAL.ERR$ = 'KT-001'; RETURN
  IF APP.ERR$ = '' THEN
    XREF.FILE = 'KS_XREFS,':FILENAME$
    CALL KMK.SETXID(XREF.FILE,RID$,XID$,FATAL.ERR$,FATAL.PARMS$)
    IF FATAL.ERR$ NE '' THEN RETURN
  END ELSE
    FATAL.ERR$   = 'KT-001'    * Force Message To Stay In The Queue On Application Error
    FATAL.PARMS$ = 'Could not loaded KS order ':XID$:' because ':APP.ERR.CNT$:' application errors were detected.'
  END
END

Before Delete Handler

The Before Delete event happens before Kourier is about the delete a record from the Target File specified on the Import Specification. This event is used to handle any logic or additional file/record updates or deletes that must take place when the current record is deleted.

note

WidgetNote

The Before Delete event only happens if the Supported Operations on an Import Specification includes a "Delete" operation.

It is typically used to prepare the data and assign other variables or values before calling the API (Application Programming Interface) for deleting a record in the target U2 application. For example, before deleting a ORDER record in an ERP system, you would call the API that manages deleting the record (and perhaps any associated records such as line items) and handles any other complexities involved.

As with the other events, if you add any logic you should set the SKIP$ variable to 1 to tell Kourier to skip its normal processing.