File Map

Circulation has many programs that import and export text (ASCII) files. Different newspapers will have varying format requirements, depending on the software applications being interfaced. To allow users more flexibility in export and import formats, many formats can be user-defined using this option. For a list of list of options that can be used with file map, see File Mapping Data Elements in Appendix B of the Circulation User Manual.

The following table indicates which format options are available with each File Map usage.

File Map Usage	Delimited	Fixed Width	Progress	Quoted
1099 Form Export	X	X	X	X
1099 Forms Printing Export	X	X	X	X
Account Lockbox	X	X	X	X
Account Statement Export	X	X
Address Export and Address Import	X	X	X	X
Alternate Format for Draw Adjustments	X	X	X	X
Alternate Single Copy Draw Change Import	X	X	X	X
Audit GL Transactions	X	X	X	X
Authentication Import	X	X	X	X
Balance Forward Billing Export	X	X
BAS Reconciliation (Detail)	X	X
BAS Reconciliation (Summary)	X	X
Bundle Top Export	X	X	X	X
Campaign Import	X	X	X	X
Carrier Mail Export	X	X
Cleanse Flag Export	X	X
Cleanse Flag Import	X	X	X	X
Communication History Import	X	X	X	X
Complaint Export (Detail)	X	X
Complaint Export (Summary)	X	X
Credit Card Expire Data Export	X	X	X	X
Dispatch Export	X	X	X	X
Do Not Call Import	X	X	X	X
Do Not Call List	X	X	X	X
Draw Adjustments and Returns Import	X	X	X	X
Draw Change Import	X	X	X	X
Draw Forecast Export	X	X	X	X
Drop Credit Audit	X	X
Drop Time Import	X	X	X	X
GL Audit	X	X
GL Export	X	X	X	X
GL Interface Journal	X	X	X	X
Misc Chg/Credit Import	X	X	X	X
Merchandise Report	X	X
Office Pay Audit Report	X	X
Past Due Letter	X	X
Payment Authorization	X	X	X	X
Postal Billing Export	X	X	X	X
Postal Subscriber Audit	X	X	X	X
Postal Subscriber Full Audit	X	X	X	X
Proof of Sale	X	X	X	X
Returns Acknowledgment Export	X	X	X	X
Returns Journal	X	X
Route Address Label Export	X	X	X	X
Route Data (Route Delivery List Export)	X	X	X	X
Router Import	X	X	X	X
Single Copy By Day Report	X	X	X	X
Sold Import	X	X	X	X
Status/Collect Cards	X	X
Subscriber Activity Import	X	X	X	X
Subscriber Billing	X	X	X	X
Subscriber Export	X	X	X	X
Subscriber Lockbox	X	X	X	X
Subscriber Tax Export	X	X
Subscriber Transaction Export	X	X
Subscriber Transaction Import	X	X	X	X
Targeted Marketing	X	X	X	X
TM Draw Change Import	X	X	X	X
Truck Sequence Export	X	X
Truck Sequence Import	X	X	X	X

Note: A standard lockbox format will be predefined in File Map; you need only set up a new lockbox format if yours differs from the standard. Likewise, a payment authorization file will be predefined for credit card cancels, in the standard credit card cancel format, and Do Not Call files will be predefined based on the Federal DNC formats.

To define a file format:

1. In character Circulation, select File Map from the System menu to display the File Map Setup screen.

   
2. Select Add and enter basic information about the format in the fields described below.

   Field	Type	What to enter
   FILE NAME	open (12)	Enter a name for this import or export format. For example, if you are interfacing to a BillServ system, you might want to name the format “BillServ”.
   DESCRIPTION	open (30)	Enter a description of this format.
   USAGE	predefined	Specify the type of import or export (for example, enter “SubLockbox” if defining a subscriber lockbox format). Press F2 for a list of valid types, or refer to the User Manual.
   DEFAULT FILE NAME	open (30)	Enter the default file name for the format in the /dti/exchange/cm directory. This will be the file name that defaults during the import or export in Circulation. This field is required for the “SubBilling” usage but optional for all other usages. Note: You are able to use tokens within the default file name to add information such as the date or a sequence number. The available tokens are: <p>—User’s default product ID (from User Profile CR) <d>—Current day name (e.g., MON if the export is run on Monday) <t>—Type of run (actual, advance, or TM) <s>—Sequence number indicating the number of times the export has been run on the current day <c>—Calendar date See Tokens for a complete list of tokens that can be used at run-time when using a file map.
   FILE FORMAT	predefined	Indicate the format: Delimited formats have a symbol such as “,” or “|” to separate fields. You could also use a tab (enter \t in the Delimiter field). Fixed Width formats have a fixed number of characters for each field. Progress formats have character fields that are enclosed in double quotes and all data elements are separated by a delimiter (usually a space). Quoted formats include double quotation marks surrounding each data element. These elements are also separated by a delimiter.
   DELIMITER	open (4)	If the file format is delimited, enter the delimiter here. For example, a popular delimiter is the pipe (|) symbol. Enter \t for a Tab delimiter.
   LINE TERMINATOR	predefined	This field controls how line feeds are exported (both the Line Feed data element and the automatic line feed at the end of every record). The options are CRLF (carriage return/line feed), LF (line feed), and None (data is exported on one line). Note: Currently, this field is valid only for the “SubBilling” file mapping usage, and LF will be used for all other usages.

3. Select Specifics | Record Type to define the format records and fields (see below).

4. Select Accept to create the file format. You can then define additional formats, or select Exit to return to the Setup menu.

Specifics, Record Type

Some file formats have multiple record types, with each record being separated by a carriage return or line feed. For example, the format might have a batch header record, followed by one or more detail records, and finally a trailer record. A format must have at least one record defined. The records and their identifiers are defined in the Record Type Setup screen.

To define record types:

1. Select Specifics | Record Type from the File Map Setup screen to display the Record Type Setup screen.

   
2. Select Add and enter information about a record in the fields described below. Note: In formats with multiple records, you can use a Record Identifier data element to identify different types of records.

   Field	Type	What to enter
   RECORD TYPE	open (16)	Enter the name of the record, for example “batch header” or “detail”.
   DESCRIPTION	open (30)	Enter a description of this record.
   EXPORT LEVEL / EXPORT WHEN	predefined	These fields open only for certain export file map types, and only certain values are available, depending on the file map. They allow you to define how often records export. For example, if “Route” is selected in Export Level, one record will export for each route processed. A record type defined with a “Process” export level will export data only once, either at the Start or End of the process (as determined by the Export When value).
   EXPORT ORDER	integer (6)	If an export format is being defined, enter the order in which this record should be exported, as related to the other records of the same record type. For example, an “Address” detail record might have an export order of 10, and a “Subscription” detail record might have an order of 20. In this case the Address record would export before the subscription record. Other record types, such as a header or footer record, would export before or after the detail records, based on whether Export When was set to “Start” or “End.”

3. Select Specifics | Data Element to define the record’s fields (see below).

4. Select Accept to accept the record. Define other records, or select Exit to return to the File Map Setup screen.

Note: Some data elements are required for certain formats. For example, the Subscription ID is a required field in the subscriber lockbox format. Users may not exit from the Record Type Setup screen until all required fields are part of the record. The F2 lookup in the Data Element field on the Data Element setup screen indicates whether a data element is required.

Specifics, Data Element

The last step in defining an import or export format is mapping the content of the fields to Circulation data elements. If a format contains more than one record, each record must be mapped separately.

Note: Data elements that can be used for each file map are listed in the User Manual.

To define fields for a record:

1. Select Specifics | Data Element from the Record Type Setup screen to display the Data Element Setup screen.

   

   
2. Select Add and map the first field (the fields are described in the table below).

   Field	Type	What to enter
   SEQ	integer (4)	Enter the sequence order of this field as it related to other fields in the record. We recommend giving the first field a sequence of 10, the second field 20, and so on, so that additional fields can be inserted later on if needed.
   DATA ELEMENT	predefined	Specify the data element that maps to this field in the format. Press F2 for a list of valid elements (shown in the figure below) or see Appendix B in the User Manual. If the field should be ignored by Circulation, enter “Filler” here. Note: For the “Adjustment” data element in subscriber lockbox formats, a Code Map prompt will appear after the data element is selected. This is where you define the subscriber payment adjustment code that should be used with adjustments imported via this lockbox format. Code Map also appears for phone number fields in export formats, allowing you to select a phone type (or “<primary>”). The occupant phone with this phone type (or the primary phone number) will be exported.
   LENGTH	integer (3)	If this is a fixed length format, enter the character length of this field.
   FORMAT/VALUE	predefined	Some data elements have a variety of possible formats. For example, dates could have the format “dmy” (day, month, year), “mdy”, etc. Logical (yes no) fields should have a format that includes a slash, such as “Y/N” if the file will be receiving the logical value as a Y or N. If this field is open, press F2 and select the correct format for the data element.
   CONVERT	predefined	Leave this field blank unless you are converting the import/export value of this field. If converting the value using a conversion program, select “Program” here and specify the path and file name of the conversion program in the Conversion Program prompt that displays. For example, you may have demographic information instead of a subscription ID in your input file. By writing a conversion program you could take the demographic information and, through your conversion program, output a subscription ID. Your conversion program must have one input-output parameter of a character type. Contact Newscycle Support for more information before writing your conversion program. If you are defining a file map for the Subscriber Activity Import, another option, “Setup,” is also available here, as described below.

3. Add the other fields in the record. Once the fields are defined, select press F4 and Exit to return to the Record Type Setup screen.

Data Element Mapping

If you are defining a file map for the Subscriber Activity Import, you can set up mappings for data elements. For example, the product ID “DlyTms” in the input file can be mapped to “DT” so that it can match product “DT” in Circulation.

To set up mapping, add the data element and set the Convert field to “Setup.” The Element Conversion Setup screen displays. Enter the low and high values to map, and the Circulation value. For most mappings, you will enter the same value in LOW VALUE and HIGH VALUE, so that the specific value will be mapped. After adding the mapping, press F4 and select Exit to return to the Data Element Setup screen.

Data Element Translation

File map elements can be translated into a different language as part of the export process. To translate a data element, set the Convert field to “P” (program) and in the Convert Program field enter “filemap/convert/translate”. The translated value in the Circulation database will then be exported. See Translation for more information on translation.

Tokens

All File Map exports allow tokens to be included in the file name when running the export option in Circulation. A list of valid tokens can be displayed by pressing F2 or clicking the lookup icon in the File Name field when running an export option.

The following table lists the generic tokens that can be used with any export File Map. The remaining tables list the tokens that can be used for more specific options.

Token	Description	Example
<c>	System date with 2-digit year	91708
<C>	System date with 4-digit year	9172008
<d>	System date day of week (lower)	wed
<D>	System date day of week (UPPER)	WED
<J>	System date Julian day	261
<m>	System date month (lower)	sep
<M>	System date month (UPPER)	SEP
<N>	System date day number	17
<O>	System date month number	9
<S>	Process sequence	0
<u>	User ID (lower)	mattm
<U>	User ID (UPPER)	MATTM
<W>	System date week number	38
<y>	System date 2-digit year	8
<Y>	System date 4-digit year	2008

Bill source tokens (used in Drop Credit Audit and Past Due Letter) are listed in the table below.

Token	Description	Example
<b>	Bill source ID (lower)	Carrier
<B>	Bill source ID (UPPER)	CARRIER

Product tokens are listed below. They can be used in Balance Forward Billing, BAS Reconciliation, Bundle Tops, Carrier Mail, Complaint Report, Draw Forecast, Merchandise Report, Status/Collection Cards, Subscriber Tax Export, Subscription Tran Export, TM, and Truck Sequence Export.

Token	Description	Example
<p>	Product ID (lower)	dm
<P>	Product ID (UPPER)	DM

Publishing group tokens, used in Bundle Tops, are listed below.

Token	Description	Example
<e>	Edition ID (lower)	early
<E>	Edition ID (UPPER)	Early
<g>	Publishing Group ID (lower)	circus
<G>	Publishing Group ID (LOWER)	Circus

Run date tokens are listed below. They can be used in Balance Forward Billing, Bundle Tops, Carrier Mail, Past Due Letter, TM, and Truck Sequence Export.

Token	Description	Example
<r>	Run date with 2-digit year	91708
<R>	Run date with 4-digit year	9172008
<rd>	Run date day of week (lower)	wed
<RD>	Run date day of week (UPPER)	WED
<RJ>	Run date Julian day	261
<rm>	Run date month (lower)	sep
<RM>	Run date month (UPPER)	SEP
<RN>	Run date day number	17
<RO>	Run date month number	9
<RW>	Run date week number	38
<ry>	Run date 2-digit year	8
<RY>	Run date 4-digit year	2008

Spool sequence tokens, used in Bundle Tops, are listed below.

Token	Description	Example
<s>	Spool sequence	0

Run type tokens, used in Bundle Tops, are listed below.

Token	Description	Example
<t>	Run type (lower)	actual
<T>	Run type (UPPER)	ACTUAL