Using the Inbound File Loader Utility

This chapter provides an overview of the Inbound File Loader utility processing and discusses how to:

• Set up processing rules.

• Initiate file processing.

• Test inbound flat file processing.

Understanding the Inbound File Loader Utility

When external systems send inbound transactions consisting of flat files, you can use the Inbound File Loader utility to translate the incoming files into service operations and process them.

The Inbound File Loader utility provides two options for translating and processing files:

• Use PeopleSoft Integration Broker to convert file data into service operations and publish them locally. Then, subscribe to the service operations and insert the data into the tables.

• Write an application class that will read the contents of files and insert the data directly into the tables

Note. You can only use one processing method at any given time. Application class processing always overrides PeopleSoft Integration Broker processing.

File Processing

This section discusses the processing flow for the Inbound File Loader utility.

Inbound File Loader utility processing flow

The flow for inbound file processing using the Inbound File Loader utility is:

1. The utility receives a flat file in the form of a file layout object from an external system.

   The flat file consists of either:

   • A data file that contains the relevant data.

   • An index file that contains pointers to the data.

     Each index file lists the names of a set of data files to be processed. Each line of the index file must be a plain text file that contains only one field: a file name with full directory path information.

   These files contain the application data, which is in one of the following formats: fixed record, Comma Separated Values (CSV), or XML.

   Note. The wildcards “*” and “?” may only be used in the filename and not in the directory path.

2. The utility reads the file that is submitted for processing:

   • If the file is an index file, the Inbound File Loader utility loads the list of data files that are associated with each index file to be processed into a parameter table.

   • If it is a single data file, the utility inserts the single data file into a parameter table.

     Note. If additional fields in the file layout are not in the message definition, the additional fields are ignored during the copying of the flat file data to the message and are not included in the message.

3. The utility loops through the list of data files to be processed and reads each data file.

4. The utility uses either PeopleSoft Integration Broker or application class processing logic to read the file contents and process the data.

   • PeopleSoft Integration Broker processing.

     When using Integration Broker processing logic, the Inbound File Loader utility copies the rowsets of the data files into the message, publishes the service operation locally, and then the receiving system receives the service operation and initiates normal inbound data processing.

   • Application class processing.

     You can build an application class to read the contents of the inbound file as rowsets and implement the necessary processing logic to write to the underlying tables.

5. To add file archiving, delete logic to prevent files from processing again, and so on, when defining processing rules, you can optionally specify an application engine program name and section. If specified, the utility calls the program and section as a final step to the inbound file process.

Understanding Development Activities

This section discusses development activities for using the Inbound File Loader utility and describes:

• General development activities

• Development activities for PeopleSoft Integration Broker processing.

• Creating file layout definitions.

• Development activities for application class processing.

General Development Activities

This section discusses general development activities for using the Inbound File Loader utility using either PeopleSoft Integration Broker processing or application class processing.

Determining the Format for Inbound Data

Determine the necessary format of the inbound data. If there is an industry standard, use it for your file definition. If there is no industry standard, create a file layout object.

Development Activities for PeopleSoft Integration Broker Processing

This section discusses development activities for using the PeopleSoft Integration Broker processing in conjunction with the Inbound File Loader utility.

1. Create a message definition in the PeopleSoft Pure Internet Architecture.

   The structure of the message definition must be similar to the structure of the file layout definition that you created.

2. Create a service.

3. Create an asynchronous one-way service operation for the service.

4. Create a local-to-local routing definition for the service operation.

5. Create an OnNotification handler and call the functional library IB_FILE_SUBCODE.

   PeopleTools delivers this functional library and it can be used for any generic notification.

   The following example shows code an OnNotification handler calling the functional library:

   import PS_PT:Integration:INotificationHandler;
    
   class QUSubscribe implements PS_PT:Integration:INotificationHandler
      method QUSubscribe();
      method OnNotify(&_MSG As Message);
   end-class;
    
   Declare Function Subscribe PeopleCode FUNCLIB_IBFILE.IB_FILE_SUBCODE FieldFormula;
    
   /* constructor */
   method QUSubscribe
   end-method;
    
   method OnNotify
      /+ &_MSG as Message +/
      /+ Extends/implements PS_PT:Integration:INotificationHandler.OnNotify +/
      /* Variable Declaration */
      
      Local Message &MSG;
      Local Rowset &MSG_ROWSET;
      
      &MSG = &_MSG;
      
      Subscribe(&MSG);
      
   end-method;
   

6. Define processing rules in the Inbound File Loader Rules page in the PeopleSoft Pure Internet Architecture.

7. Initiate flat file processing using the Inbound File Processing page.

8. Test the inbound flat file processing.

Creating File Layout Definitions

When you use the Inbound File Loader utility, you use file layout definitions to read and write data from flat files. Use the following guidelines when creating file layout definitions:

• Create a file layout definition with the same structure as the message definition to support the vendor file format.

• The hierarchical structure of the data in the file layout definition must match that of the message definition. For example, suppose a message has three levels:

  • Level 0, containing record A.

  • Level 1, containing records B and C.

  • Level 2, containing record D.

  All file layouts that are associated with this message must also have record A in level 0, record B and C in level 1, and record D in level 2.

  Note. The file layout does not need to contain the exact same fields as the message definition

• For every record in a file layout definition, add a new file field, AUDIT_ACTN, as the first field in the record (except when the field already exists in the application table).

• You can associate more than one file layout to a single message. For example, vendor A may have a different number of fields than vendor B, so you may have two file layouts: one for vendor A and one for vendor B.

• Specify the file ID uniquely to include a row in a file, which is necessary in mapping the data to its proper record. Include start and end points when dealing with more than one record in a file layout.

• Each record in the file layout has a file record ID attribute. Do not confuse this with the file layout ID. The file layout ID determines whether a new layout is encountered for multiple file layout processing.

Development Activities for Application Class Processing

This section discusses development activities for application class processing using the Inbound File Loader utility. This section discusses how to:

1. Create an application class.

2. Specify processing rules.

Creating Application Classes

This section discusses creating an application class for processing flat files in conjunction with the Inbound File Loader utility.

The application class you create must implement the IProcessFile interface. The signature of the interface is shown here:

interface IProcessFile
   /* Any initialization is done in this function*/
method Init (&fldDefName As string, &msgName As string) Returns boolean;
   
/* Contains processing logic that stores the Rowset data into the respective⇒
 tables */
method Process(&fldDefName As string, &msgName As string, &rs As Rowset) Returns⇒
 boolean;
   
/* This method shall contain logic for cleanup operations */
method Finish(&fldDefName As string, &msgName As string) Returns boolean;
end-interface;

The application class you create must implement the following three methods:

• Init

• Process

• Finish

If the Replace Data check box is selected in the Inbound File Loader Rule page, the Init method will be called. The Finish method is the last method to be invoked by the utility. Any post-processing clean up code can be implemented with this function.

The logic in the Process method stores the file contents in staging tables. You can add logic in the Finish method to move the data from staging tables to the actual transaction tables as a final process.

The Init, Process and Finish methods must return a boolean value of True for successful completion of the file processing. If methods Init and Finish are not used, return a default value of True.

The following example shows an application class implementing the IProcessFile interface:

import PTIB:Interfaces:IProcessFile;

class InboundFileProcess implements PTIB:Interfaces:IProcessFile

method Init(&fldDefName As string, &msgName As string) Returns boolean;

method Process(&fldDefName As string, &msgName As string, &rs As Rowset) Returns⇒
 boolean;

method Finish(&fldDefName As string, &msgName As string) Returns boolean;

end-class;

method Init
   /+ &fldDefName as String, +/
   /+ &msgName as String +/
   /+ Returns Boolean +/
/+ Extends/implements PTIB:Interfaces:IProcessFile.Init +/

//This function will be called when the Replace Data flag is     
//enabled
//add initialization code, such as cleaning up the table before   
//reading in the data from the file



   Return True;
end-method;

method Process
   /+ &fldDefName as String, +/
   /+ &msgName as String, +/
   /+ &rs as Rowset +/
   /+ Returns Boolean +/
/+ Extends/implements PTIB:Interfaces:IProcessFile.Process +/

//Add the code that inserts/updates/delete data in the table

   Return True;
end-method;

method Finish
   /+ &fldDefName as String, +/
   /+ &msgName as String +/
   /+ Returns Boolean +/
   /+ Extends/implements PTIB:Interfaces:IProcessFile.Finish +/

	//This function will be called when the Replace Data flag is     
//enabled
// Clean up logic goes here (if any)

   Return True;
end-method;

Specifying Processing Rules

After you create an application class, you must access the Inbound File Loader Rules page and specify the following information:

• Root Package ID.

• Path.

• Class name.

Prerequisites for Using the Inbound File Loader Utility

The prerequisites for using the Inbound File Loader utility are:

• PeopleSoft Integration Broker must be configured and running.

• PeopleSoft Process Scheduler must be configured in PSAdmin.

• Create a file definition layout as described previously in this chapter.

  See Creating File Layout Definitions.

• If using PeopleSoft Integration Broker processing, complete the development activities for PeopleSoft Integration Broker processing described previously in this chapter.

  See Development Activities for PeopleSoft Integration Broker Processing.

• If using application class processing develop an application class that implements the IProcessFile interface and specify the processing rules as described previously in this chapter.

  See Development Activities for Application Class Processing.

Setting Up Inbound File Loader Processing Rules

This section discusses how to set up inbound flat file processing rules.

Understanding Setting Up Inbound File Loader Processing Rules

The Inbound File Loader utility uses information you define in the Inbound File Loader Rules page to determine the file layout and message combination, as well as other file attributes necessary for processing files.

Setting Up Inbound File Loader Processing Rules

Use the Inbound File Loader Rules page (PSIBINFILERULE) to specify the file layout and message to process, as well as define the parameters for processing. To access the page, select PeopleTools, Integration Broker, File Utilities, Inbound File Loader Rules. The following examples shows the page:

Note. You can process multiple inbound flat files at one time. By specifying an inbound index file as part of the Inbound File Loader utility parameters. The system reads all input files within the index file and uses the associated file layout object and message to convert the data. Similarly, specify a wildcard in the filename in the inbound file rule component, but make sure that all files that meet the wildcard criteria correspond to the file layout and message mapping that are defined.

Note. Use the wildcards “*” and “?” for the file name but not for the directory path. The file layout and service operation must be valid for all files that meet the wildcard criteria.

Initiating File Processing

This section discusses how to initiate inbound flat file processing.

Understanding Initiating File Processing

The Inbound File Processing page runs the Application Engine process PTIB_INFILE that initiates the file-to-message processing. The file-to-message processing function reads the file rowset and publishes it as a message.

If an index file exists when the inbound conversion process runs, the application engine program loads the list of files to be converted into a parameter table and completes a commit. The application engine program uses the list of files within the parameter table to restart the processing if a particular flat file fails. If a single data file is provided, then the rowset processing immediately begins.

The file publish process goes through each of the rowsets of the file layout and copies them into the message row sets.

If the audit action (AUDIT_ACTN) exists in the file, it is copied to the PSCAMA record. If the audit action does not exist in the file, the publishing process uses the default value that is specified in the file layout field property.

The Inbound File Loader utility publishes a new message when one of the following exists:

• The size of the data in the service operation exceeds the value of the Maximum Message Size field set in the PeopleTools Options page.

  To view the value in the field, select PeopleTools, Utilities, Administration, PeopleTools Options.

• A new file layout is detected.

• End of file is reached.

The application engine program completes a commit every time a message is published from a file. After conversion, the flat file remains in the parameter table with a status of Processed.

Note. The file layout should exactly match the message layout (excluding the PSCAMA record) and should use the same character set as that used by the file: either American National Standards Institute or Unicode.

Initiating Inbound Flat File Processing

Use the Inbound File Processing page (PSIBFILERUNCNTL) to initiate flat file processing. Select PeopleTools, Integration Broker, File Utilities, Inbound File Processing. The Inbound File Processing page, shown in the following example, appears:

Request ID	Enter a unique identifier to track the request.
Process Frequency	Select the frequency for processing the file. The options are: Process Once. Always. Don't Run.
File Identifier	Select or enter the name of the file identifier that you set up in the Inbound File Loader Rules. page. The file identifier is tied to the publish rules.
Index Flag	A read-only field that indicates if the file being processed is an index file or a data file. When checked, the Inbound File Loader utility is processing an index file.
File Layout ID	A read-only field that displays the file layout ID associated with the file in the Inbound File Loader Rules page.
Inbound File	A read-only field that displays the name of the file being processed.

Testing Inbound Flat File Processing

To test inbound files:

1. Create a sample flat file, or ask the third-party vendor for a sample flat file.

2. Set up processing rules for the test.

   Select PeopleTools, Integration Broker, File Utilities, Inbound File Loader Rules to access the Inbound File Loader Rules page.

   See Setting Up Inbound File Loader Processing Rules.

3. Initiate file processing.

   Select PeopleTools, Integration Broker, File Utilities, Inbound File Processing to access the Inbound File Processing page.

   See Initiating Inbound Flat File Processing.

4. Verify the inbound processing created a message that contains the sample flat file data.

   1. If you used application class processing, verify if the production or staging tables are loaded with the correct field values. For production tables, look in the PeopleSoft application pages. For staging tables, use either the PeopleSoft application pages or run a query by using PeopleSoft Query.

   2. If you used PeopleSoft Integration Broker for file processing, use the Service Operations Monitor to ensure the inbound file processing created a service operation that contains the sample flat file data.

      Verify that the standard inbound notification process received the message and processed it into the application tables.

      Determine whether the values become the inherited values (if you used the inherited value feature in file layout).

      Validate that the production or staging tables loaded with the correct field values. For production tables, look in the PeopleSoft application pages. For staging tables, use either the PeopleSoft application pages or run a query by using PeopleSoft Query.

      Ensure that the date formats conform.