HR Agency Interface Specifications

Table of Contents

1. Introduction
2. SAM II Data Structures

       2.1  Tables

       2.2  Documents

       2.2  Transactions

3. Types of Conversions

       3.1  School

       3.2  Course

       3.2  Course Grade

4. SAM II Interface Documents, Transactions and Tables

       4.1  Employee Training Profile

       4.2  Current Period Timesheet

       4.3  Prior Period Timesheet

       4.4  Work Day Schedule

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 HR 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, document, or transaction 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 HR_SUPPORT@oa.mo.gov.

Your request must include the agency name, agency number, applicable document type(s) or transaction type(s) and justification for interface. 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 HR Support staff. Email dataset(s) to HR_SUPPORT@oa.mo.gov. Contact the OA-ITSD HR help desk if you have any questions regarding interface testing. (522-1500, Option 2).

Production ready interfaces should be written to an OA-State Data Center file established by OA-ITSD HR 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 HR nightly cycle backs up the dataset contents at 7:00 p.m. and loads the data into SAM II HR. The dataset is then emptied out to ready it for the next day's business. The OA-ITSD HR help desk can assist with data transmission questions or problems. Production loads cannot be delivered through email or on diskette.

2.     SAM II Data Structures

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

General guidelines when building a document, transaction or table interface include:

• All alpha-numeric data elements must be uppercase only.
• Numeric fields with a decimal value should be received with 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:

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.

2.3     Transactions

• Transactions have a file length of 2011 and are variable block.
• The first four characters of the file specify the transaction type. MTI-TRANS-TYPE on the layouts.
• If they have lines they can have more than one line per header. The lines are numbered, MTI-TRANS-SCREEN-SEQ-NO on the layouts.
• The next character on the layouts is the SEQ-INPUT-RECORD-TYPE. It should specify (H) for headers or (L) for lines. They must have headers (H) but not all of them have lines (L). The layout specifies whether they do or not.
• They are, like documents, subject to the same edits as on online transaction.
• Transactions are maintained through the Suspense File tables on-line, SUSE and SUSP.

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     School

The School (SCHL) window is used to define the codes which identify any educational institutions employees or applicants have attended or are attending.

3.2     Course

The Course (CRSE) window is used to define the codes which identify educational or training courses employees can participate in and accumulate towards a degree or career advancement.

3.3     Course Grade

The Course Grade (CGRD) window is used to identify possible grades employees can receive for courses given at a particular school. This window also defines the percentage employees are reimbursed for course costs when they earn each grade entered on this window.

4.     SAM II Interface Documents, Transactions and Tables

This section indicates which transactions, documents and tables will be allowed to be input via an interface file from the agencies. OA-SAM II System Administration must pre-approve an interface and will coordinate with other central approval agencies if their approvals are needed.

4.1     Employee Training Profile

The Employee Training Profile (ETRP) transaction is used to record training courses taken either in-house or externally by an employee. The employee's participation in courses can either precede or occur during the time of the employee's appointment. This window is also used to reimburse employees for tuition costs.

4.2     Current Period Timesheet

This document is used to record time worked and leave taken during the current pay period.

4.3     Prior Period Timesheet

This document is used to record time worked and leave taken during a prior pay period.

4.4     Work Day Schedule

This table is used to define normal work days, off days (i.e. weekends), holidays, and contract work days for each work cycle.