How do I create an import package?
Contents
A 'package' is a script file that contains a list of CSV file segments to be imported.
An import package is a text file. You can create it using a text editor (such as Notepad or WordPad) or a word processor, providing you save the document in text form. When Match-IT is installed a suitable text editor, called FoldIt, is placed in your ...\match_it\sys directory.
To be understood by the import system the content of the package file must conform to a syntax . The required syntax is defined here in BNF (Backus-Naur Form):
| PackageScript ::= | { CommentLine } IssueLine { CommentLine | ImportLine } EndLine |
| CommentLine ::= | any line that is not an issue or an import or an end |
| IssueLine ::= | 'ISSUE:' SystemIssueId |
| ImportLine ::= | 'IMPORT:' [ImportPath] ['FROM:' StartPattern] ['TO:' EndPattern] 'AS:' (FileId | DropId) Options |
| EndLine ::= | 'END:' |
| SystemIssueId ::= | this is just information, it defines the system issue when the package was built |
| ImportPath ::= | the path to the file containing the CSV records to be imported. If omitted the records are assumed to be encapsulated in the script file itself. |
| StartPattern ::= | a string used to mark the beginning of the section in the file to be imported. If omitted the first line in the file is assumed. If present the line immediately following the one containing this pattern is used. |
| EndPattern ::= | a string used to mark the end of the section in the file to be imported. If omitted the last line in the file is assumed. If present the import stops at the line immediately preceeding the one containing this. |
| FileId ::= | the TLA of a file being imported into |
| DropId ::= | the name of a DO operation to execute |
| Options ::= | [ IgnoreDuplicates ] [ UpdateDuplicates ] [ FieldListAtLine1 ] |
| IgnoreDuplicates ::= | '[DUPS]' |
| UpdateDuplicates ::= | '[OVER]' |
| FieldListAtLine1 ::= | '[USELINE1]' |
The meaning of each of these syntax elements is:
PackageScript: |
A package script consists of an ISSUE: line followed by any number of IMPORT: lines and an END: line. If the import CSV records are embedded in the package script, they follow the END: line. The script is interpreted in line by line order until the EndLine or the end of the file is reached. |
Comment Line: |
Comments can be placed almost anywhere to aid the readability. They are ignored by the import system. |
IssueLine: |
The issue line defines the issue of the Match-IT system when the import package was first created. The IssueLine must precede the first ImportLine. |
ImportLine: |
An import line defines a group of CSV records to import. The import path defines the file the records can be found in. If this is blank, the records are assumed to be in the script file itself (following the END line). The start and end pattern define which part of the file is to be imported. All records following the given start pattern and up to, but excluding, the end pattern are imported. The first line after the start pattern must be the field list unless the [USELINE1] option is given. If the AS: clause is a FileId, the records will be imported into that file. The field list must consist of field names in that file. If the AS: clause is a DropId each CSV record is passed to the named DO operation. In this case the CSV records must consist of the DO parameters in the appropriate order containing fields of the appropriate type. The field list must still be present, with one name per parameter, but the actual names are arbitrary. Any output fields of the DO operation must also be present but the output is ignored. The IMPORT lines are assumed to be presented in reverse dependence order. I.e. records with no dependants must be imported before the records that refer to them. |
EndLine: |
This marks the end of the IMPORT lines in the package. |
Options: |
If '[DUPS]' is present then the existence of a matching record is tolerated, no error is reported and the import proceeds as if it was added. A 'matching' record is one where all key fields are the same. NB: This does not necessarily mean the record is unique. This option is ignored when executing a DO operation. If '[OVER]' is present then any existing matching record is overwritten, no error is reported and the import proceeds as if it was added. A 'matching' record is one where all key fields are the same. NB: This does not necessarily mean the record is unique. This option is ignored when executing a DO operation. If '[USELINE1]' is present then the first line of the source is interpreted as containing the field name list. Otherwise, the line immediately following the start pattern is used. The field name list defines the order of the fields to expect for the file. Each FieldName must match the name of a field in the file unless it is preceded by a '!'. If the field name is preceded by an '!' the corresponding column in the import records is ignored. The FileId in the field name list must match the file being imported into. |
Note: Many of the initial system options are imported using these packages. Look in your ...\match_it\configs folder for files with a .PAK extension for examples.