Agency Interface Specifications

Table of Contents

  1. Introduction
  2. SAM II Data Structures

        2.1  Tables

        2.2  Documents

  3. Types of Conversions

        3.1  Consumable Inventory Conversion

        3.2  Fixed Asset Conversion

  4. SAM II Interface Transactions

        4.1  Accounts Receivable Documents

        4.2  Budget Documents

        4.3  Accounts Payable Documents

        4.4  Fixed Asset Documents

        4.5  Job Cost

        4.6  Performance Measurement

        4.7  Purchasing Documents

        4.8  Grants

        4.9  Projects

        4.10  Inventory Documents

        4.11  Other

1.    Introduction

The purpose of this document is to explain the interface process that agencies will use to supply information to be loaded to the SAM II Financial system.

All interface data will be received in the form of sequential electronic files. These files will be in the format of a SAM II table or a SAM II document and will use existing functionality to import them into the SAM II system. To ensure the accuracy of the data, the same edit programs that apply to on-line transactions will be applied to the interface files when loaded to SAM II.

New interfaces must be approved by the Office of Administration before test files are submitted. To request approval to submit a new interface, send an email to the OA-ITSD Financial Support help desk ( The help desk will coordinate with the other central approval agencies if their approvals are needed. If you have any question regarding this procedure, call the OA-ITSD Financial Support help desk at 573-522-1500, option 1.

Your request must include the agency name, agency number, and applicable document type(s). The Office of Administration will review the request and notify the agency when it is approved or denied.

The test data must be delivered via FTP or saved to an OA- State Data Center dataset which has been established by OA-ITSD Financial Support staff. Email dataset (s) to the OA-ITSD mailbox ( Contact the OA-ITSD Financial help desk if you have any questions regarding interface testing. (573-522-1500, Option 1).

Production ready interfaces should be written to an OA-State Data Center file established by OA-ITSD Financial Support. This can be accomplished through the FTP process or State Data Center customers may write directly to the file. The agency will be granted authority to update the dataset. The SAM II nightly cycle backs up the dataset contents at 6:00 p.m. and loads the data into SAM II. The dataset is then emptied out to ready it for the next day's business. The OA-ITSD Financial help desk can assist with data transmission questions or problems. Production loads cannot be delivered through email or on diskette.

Some interfaces require an accompanying "Detail Transaction Report" and a "Totals and Signature Line Report". Interface file and Transaction report layout information is available under the Document and Table Interface Information section of the SAM II Financial website.

2.     SAM II Data Structures

Within SAM II, there are two types of interface data structures: tables and documents. Each of these data structures are explained below, along with the conversion or interface layouts.

General guidelines when building a document or table interface include:

  • All alpha-numeric data elements must be uppercase only.
  • Numeric fields with a decimal value should be received without a decimal point inserted unless otherwise stated.
  • Alpha-numeric fields should be left-justified and space filled unless otherwise stated.

2.1     Tables

Tables are files that can be viewed on-line. They are used to maintain control settings, maintain reference information, and record information. Each table has a unique file layout and every record within the table has the same layout. Separate files should be created for each table type.

Interface files are loaded into the SAM II system using a database utility. This utility applies the same edits that would be applied if the information were entered on-line. Every record that has a severe error or would result in a duplicate record on the table will be reported by the utility and NOT loaded onto the table. This information will be disseminated back to the agencies.

2.2     Documents

Documents are maintained through the Document Suspense File table on-line. They are used to record actions that take place, whether it be an accounting action like a Payment Voucher or a creating action like establishing a Project. Documents may require a header and/or detail line, depending on the type of document. Every document will have a Detail Line (record type L). This records the information that is unique for each line of a document. The majority of documents will have a Document Header (record type D) to group the Detail Lines together. The header records contain information that is shared by all the lines in the document but is unique for the document itself. Document header numbers cannot be duplicated on the submitted interface or on any subsequent information. Interface document number information is subject to the same edits as other SAM II online documents. An interface file should contain only one document type.

The first Document Header record for the file must be the first record in the file. This header is followed by all the Detail Lines that are associated with that header. The next record is the second Document Header followed by its lines. This pattern continues for the entire file. This is how the file needs to be loaded into the SAM II system. The file can actually be created in an order that makes more sense to the programmer and be sorted to put it into the proper order before submitting it to OA for loading.

2.2.1     Creating a Document Interface

The record length for every document file will be 930 bytes with a block size of 27900. Each record in a document file must be prefixed by a group of fields that are used as the key identifier for a document. These are as follows:

Field Name COBOL Layout Start Pos End Pos
Record Type PIC X(01) 1 1
Filler PIC X(01) 2 2
Batch Document Type PIC X(04) 3 6
Batch Agency Code PIC X(04) 7 10
Batch Number (left blank) PIC X(06) 11 16
Document Type PIC X(04) 17 20
Document Agency PIC X(04) 21 24
Document Number PIC X(12) 25 36

These fields are listed in the file layouts. When creating a document detail record (L), the batch and document information in the prefix section must match the document header record this line is grouped under.

As the layout specifies, the document records for document header and document line each start in position one. This results in a file that may look like this:

[D][ rest of prefix ][ document header data portion of record ]
[L][ rest of prefix ][ document detail data portion of record ]
[D][ rest of prefix ][ document header data portion of record ]
[L][ rest of prefix ][ document detail data portion of record ]
[L][ rest of prefix ][ document detail data portion of record ]

This method of creating a document is the same for each document type.

3.     Types of Conversions

Below is a listing of the types of conversions that may be necessary from an Agency. If an agency has this type of legacy data, then the conversion listed below is necessary

3.1     Consumable Inventory Conversion

The inventory conversion will be handled by a series of table loads. The tables that need to be loaded are:

  • ABC Parameter (ABCP)
  • Warehouse Management (WHS2)
  • Inventory Inquiry (INV3)
  • Inventory by Keyword (INKY)

These tables control the parameters and balances for the inventory sub-system.

3.2     Fixed Assets Conversion

Fixed Assets are established through the use of the Fixed Asset Acquisition (FA) document. Every asset that is to be tracked through the SAM II system must be set up with a FA document. The Fixed Asset Conversion section on the SAM II Financial website provides additional information regarding conversions.

4.     SAM II Interface Transactions