Technical Specification
TABLE OF CONTENTS
- Introduction
- Data Input
- Operation
- Data Processing
- Data Files Structure and Format
- Attachments
Introduction
Cintra’s Standard Inbound Interface provides functionality to allow for a convenient and secure way to connect and import new starters or update existing employee-related information into your Cintra IQ application.
The Standard Interface module consists of five connectors, each to support the input and processing of employee-related information, such as:
- Base data
- Fixed payments data
- Variable payments data
- Pensions and Benefits data
- Absences data
Please Note: All the processing of the input data will be based on the build and configuration of your system, including any additional rules or calculation methods, defined in your Cintra IQ application.
Data Input
Each connector requires a defined comma-separated values (csv) file as an input source, to process the data within the interface module. File structure, data format and field validation rules for each data file are defined under the Data Files Structure and Format section.
Operation
Providing and processing the data files to each of the connectors could be done manually, through a semi-automated or fully automated process.
Manual file loading and processing
The Standard Interface would allow for manual data file loading and processing, giving a Cintra IQ operator complete control over the process.
File Loading
Each of the connectors within the Standard Interface would be available and accessible through the Cintra IQ UI, allowing for a Cintra IQ operator to select the files they want to import. Upon loading a file, it will be put into a processing queue, visible within the Interface UI.
Processing
The files will remain under a processing queue until manually processed. A Cintra IQ operator would be able to trigger the operation when they require, upon which, the interface will process all pending (unprocessed) files in the queue, in chronological order, beginning with the oldest file first.
Note: The files uploaded manually for each of the connectors would be expected to be standard CSV files, still following the expected structure in alignment with the specification.
Automated file loading and processing
The Standard Interface supports file transfers over SFTP. This method allows for an automated streamlined process with direct data file input over a secure channel. This is an additional option which can be enabled under the interface configuration.
Setup and Connection Details
The interface establishes an SFTP connection, using a basic authentication method. In order for the connection to be established, the following parameters need to be provided: “Hostname or IP address of the SFTP server”, “Connection Port Number”, “Username” and “Password”.
SFTP Hosting
If customers have their own SFTP server, the above connection and authentication details need to be provided to Cintra in order to configure the option within the Standard Interface.
If customers do not have their own SFTP server or would not like to use it for this purpose, Cintra can provide an SFTP site, hosted on a Cintra server and will do all the setup and configuration needed to establish the link between the SFTP site and the interface. In order to request this service, please fill in, sign and submit the Cintra SFTP Service Agreement and Request for Access document to Cintra.
Note: The Cintra SFTP Service Agreement and Request for Access document required for this service can be downloaded from the Attachments section located at the end of this article.
File Loading
The interface will be configured to automatically connect and look for files at the given SFTP location at a defined polling interval. It will pull the files from the location and load them into a queue within the Interface module. Upon a successful operation, the files will be deleted from the SFTP server.
Processing
The files will remain within the queue until being processed. There’s an option within the Interface which would allow for either manual or automated processing of the files.
If the option is set for manual processing - the files will remain under a processing queue until manually processed. A Cintra IQ operator would be able to trigger the operation when they require, upon which, the interface will process all pending (unprocessed) files in the queue, in chronological order, beginning with the oldest file first.
If the option is set for automated processing, the system will automatically pick up and process the files within the queue sequentially in chronological order, beginning with the oldest file first. It is possible to additionally define the automated file processing frequency as well.
Encryption Support
One of the benefits, using the automated file loading process through SFTP, is that it also supports PGP file encryption. This is an additional option which can be enabled under the interface configuration, which is adding an extra layer of security over the data that gets submitted. If enabled on the interface, the files uploaded to the SFTP site would need to be encrypted with a PGP encryption key, which Cintra would issue and provide separately.
Data Processing
Any of the supported data files can be provided at any time through the interface to perform an operation against one or more records, still the following needs to be considered:
- For any new starter:
- The Base Data file is required to be submitted with all relevant required information provided;
- Any additional information can be provided through the rest of the files, as defined;
- For amendments to existing employee information:
- Any file can be submitted, as long as it contain a valid existing Employee Number reference;
- Only employee records, containing amendments need to be provided for each respective file;
- For each file submitted, the information for any record provided will be considered the most recent information and all field values will be updated with the provided information (full record replacement, not just delta changes).
Specifics around each data file processing are defined under each file’s structure and definition specification noted under the Data Files Structure and Format section.
Data Files Structure and Format
The Standard Interface supports 5 types of data input files, in the format of CSV.
- Base Data File
- Fixed Payments File
- Variable Payments File
- Pensions and Benefits File
- Absence File
A ZIP archive named "Sample Input Files.zip" - containing sample CSV templates for all input file types - is available for download in the Attachments section at the end of this article.
Upon processing each of the files, a validation against the rules and expected format of the data will be performed. If the validation criteria are not met, the data file import may fail, respectively some or all records within the file may not be processed.
Each of the data files must start with a header row, as their first row, using the names of each field. The data processing will always start from the second row within the CSV file, so if a header row is not present, the first row of data in the import file will not be processed.
All fields defined under each of the file definitions must be present on the file and passed in the defined order. If for any of the fields there’s no data or the value is empty, please simply pass an empty string.
Fields marked as “Required” will always be expecting value, thus cannot be empty.
Fields marked as “Optional” may be left empty.
If while processing any of the files, there are any issues which would cause a warning or an error, they will be written to a “File Processing Log”, accessible via the interface UI section within Cintra IQ. Depending on the severity of the issue, the interface will determine whether it’s able to process the data within the current record, skip the record, or stop the processing if a severe problem is found.
1. Base Data File
The Base Data file is used to import employees’ personal information, contact information, bank details, employment details and base payroll-related information.
Provided data within this file will either add new or modify existing employee records. The file must contain only one record per employee with an unique Employee Number defined for each employee.
Filename
File must be in the format of a comma-separated values (csv) file with values encapsulated in double quotes. The name of the file must be defined in the following format - {YYYYMMDD}_{HHMMSS}_BAS.csv (for example: 20210918_161559_BAS.csv).
Adding a new record
If a record with the defined Employee Number is not present in the system, a new employee record with the defined information will be created.
Modifying existing record
If a record with the defined Employee Number is already in the system, the related information will be updated, based on all field values defined under the record in the file. Please make sure you are providing full record information for all fields defined below and not only the modified fields.
Please Note: Processing this file will not perform any deletion of existing records, so it can’t be used for the purpose of that operation. If such an operation is required, a separate process is to be used.
Fields structure
Field Name | Format & Validation Rules | Additional Information | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Employee Number | Max length: 10 characters Accepts: letters (A-z), numbers (0-9). Unique per each employee. | Required Represents an Employee Identifier. | ||||||||||||||||||||||||
Title | Max length: 4 characters Accepts: letters (A-z), dash (“-”), space (“ “), dot (“.”) Must start with a letter. | Optional | ||||||||||||||||||||||||
First Name | Max length: 30 characters Accepts: letters (A-z), dash (“-”), space (“ “), single quote ( ‘ ). Must start with a letter. | Required | ||||||||||||||||||||||||
Middle Name | Max length: 30 characters Accepts: letters (A-z), dash (“-”), space (“ “), single quote ( ‘ ). Must start with a letter. | Optional | ||||||||||||||||||||||||
Surname | Max length: 35 characters Accepts: letters (A-z), dash (“-”), space (“ “), single quote ( ‘ ). Must start with a letter. | Required | ||||||||||||||||||||||||
NI Number | 9 characters string Accepts: letters (A-z), numbers (0-9). Must be a valid National Insurance Number in the format of 2 letters, followed by 6 numbers and 1 letter | Represents employee’s National Insurance Number. Not mandatory when setting up a new employee, but will be required for HMRC (FPS) submission. | ||||||||||||||||||||||||
Date of Birth | Date in the format of “YYYY-MM-DD” | Not mandatory when setting up a new employee, but will be required for HMRC (FPS) submission. | ||||||||||||||||||||||||
Gender | Accepted values are “Male” or “Female” | Required | ||||||||||||||||||||||||
Marital Status | Single character code
| Optional Please send the single-character letter, referring to the correct status, based on the defined table of accepted values, as defined on the left. | ||||||||||||||||||||||||
Address Line 1 | Max length: 35 characters | Not mandatory, but for HMRC (FPS) | ||||||||||||||||||||||||
|
| |||||||||||||||||||||||||
Address Line 2 | Max length: 35 characters | submission at least 2 address lines must be provided. | ||||||||||||||||||||||||
|
| |||||||||||||||||||||||||
Address Line 3 | Max length: 35 characters |
| ||||||||||||||||||||||||
Address Line 4 | Max length: 35 characters |
| ||||||||||||||||||||||||
Postcode | Max length: 8 characters Must be a valid UK postcode. | Is required for HMRC (FPS) submission. | ||||||||||||||||||||||||
Country | Max length: 35 characters | Optional | ||||||||||||||||||||||||
Home Telephone | Max length: 50 characters | Optional | ||||||||||||||||||||||||
Mobile | Max length: 20 characters | Optional | ||||||||||||||||||||||||
Primary Email Address | Max length: 250 characters Must be a valid email address format. | Optional | ||||||||||||||||||||||||
Secondary Email Address | Max length: 250 characters Must be a valid email address format. | Optional | ||||||||||||||||||||||||
Date Joined | Date in the format of “YYYY-MM-DD” | Required | ||||||||||||||||||||||||
Continuous Service Date | Date in the format of “YYYY-MM-DD” | Optional | ||||||||||||||||||||||||
Date Left | Date in the format of “YYYY-MM-DD” | Optional | ||||||||||||||||||||||||
Employment Status | Accepted values are “Casual”, “Permanent”, “Temporary” | Optional | ||||||||||||||||||||||||
Bank Account Holder Name | Max length: 60 characters | Optional If left blank, the system will automatically generate it by using the Title, First Name and Surname provided. | ||||||||||||||||||||||||
Bank Sort Code | 6 or 8 characters string Accepts: numbers (0-9), dash (“-”). Accepted formats: “000000” or “00-00-00”. | Required | ||||||||||||||||||||||||
Bank Account Number | 8 characters string Accepts: numbers (0-9). Represents an 8-digit number. | Required | ||||||||||||||||||||||||
Building Society Roll Number | Max length: 18 characters | Optional To be defined if payment needs to be made to a Building Society. | ||||||||||||||||||||||||
Payroll Name | Max length: 48 characters Needs to match an existing Payroll within Cintra IQ. * | Required | ||||||||||||||||||||||||
Employer Name | Max length: 50 characters Needs to match an existing Employer within Cintra IQ. * | Required | ||||||||||||||||||||||||
Post Effective Date | Date in the format of “YYYY-MM-DD” | Optional Used to define the start date of when the employee would be assigned to a Post. Please Note: This field will be Mandatory if a Post Reference field value is passed. | ||||||||||||||||||||||||
Post Reference | Max length: 50 characters Needs to match an existing Post Reference, defined in Cintra IQ. * | Optional Used to assign a Post to an employee. | ||||||||||||||||||||||||
Work Pattern Effective Date | Date in the format of “YYYY-MM-DD” | Optional Used to define the date of when the Work Pattern information would be applied. Please Note: This field will be Mandatory if any of the related Work Pattern information (“Name”, “Contract Hours per Week” or “FTE Factor”) is defined. | ||||||||||||||||||||||||
Work Pattern Name | Max length: 20 characters Needs to match an existing Work Pattern, defined in Cintra IQ. | Optional Used to assign a Work Pattern to an employee. | ||||||||||||||||||||||||
Work Pattern Contract Hours per Week | Decimal(5,2) | Optional Defines how many hours an employee works per week. | ||||||||||||||||||||||||
Work Pattern FTE Factor | Decimal(7,6) | Optional Full Time Equivalent represents the work model factor (for example - 0.5 for 4 hours based on 8 hour work day) | ||||||||||||||||||||||||
Cost Code 1 | Varchar(50) | Optional Represents default Standing Cost Allocation definition, where by default the cost code would be allocated to the “Account”. ** | ||||||||||||||||||||||||
Cost Code 2 | Varchar(50) | Optional Represents default Standing Cost Allocation definition, where by default the cost code would be allocated to the “Department”. ** | ||||||||||||||||||||||||
Pay Point | Varchar(50) | Optional |
* Important: As the values for the following fields: “Payroll Name”, “Employer Name”, “Post Reference” and “Work Pattern Name” need to match with how these have been set up within Cintra IQ, please refer to the Cintra team to set and confirm the respective reference values and ensure correct mapping.
** Please Note: Allocation percentage for the Standing Cost Allocations will be set as 100%. Allocations for Cost Code 1 and Cost Code 2 can be mapped differently based on your system setup, so please feel free to refer to the Cintra team to get a confirmation on these two fields' exact mapping structure.
2. Fixed Payments File
Summary
The Fixed Payments file is used to define and import information about recurring employee additions or deductions, commencing at a defined Start Date and potentially ceasing at a defined End Date.
Provided data within this file will either add new or modify existing employees’ fixed payment records. The file may contain more than one record per employee, as long as the Employee Number defined is a valid number of an already existing employee within the system.
Filename
File must be in the format of a comma-separated values (csv) file with values encapsulated in double quotes. The name of the file must be defined in the following format - {YYYYMMDD}_{HHMMSS}_FIX.csv (for example: 20210918_162305_FIX.csv).
Adding a new record
If a record for a combination of Employee Number and Payment Code is not present in the system, a new fixed payment record for this employee, with the defined information, will be created.
Modifying existing record
If a record for a combination of Employee Number and Payment Code is already in the system, the related information will be updated, based on all field values defined under the record in the file. Please make sure you are providing full record information for all fields defined below and not only the modified fields.
Please Note: Processing this file will not perform any deletion of existing records, so it can’t be used for the purpose of that operation. If such an operation is required, a separate process is to be used.
Fields structure
Field Name | Format & Validation Rules | Additional Information |
|---|---|---|
Employee Number | Max length: 10 characters Accepts: letters (A-z), numbers (0-9). | Required Represents an Employee Identifier. |
Payment Code | Max length: 3 characters | Required Needs to match an Import Code reference of an existing Payment Heading (addition or deduction), defined in Cintra IQ. * |
Payment Name | Max length: 30 characters | Optional |
Start Date | Date in the format of “YYYY-MM-DD” | Required |
End Date | Date in the format of “YYYY-MM-DD” | Optional |
Annual Amount | Decimal (18,2) | Required Represents annual payment amount, based on which an actual pro rata payment would be calculated for the defined period |
Period Amount | Decimal (18,2) | Optional Represents the amount which will be paid for the defined period |
* Important: As the Payment Code field needs to match an existing reference value within Cintra IQ, please refer to the Cintra team to set and confirm the respective reference values and ensure correct mapping.
3. Variable Payments File
Summary
The Variable Payments file is used to define and import information about one-off payments or deductions to employees for a defined period between a Start Date and End Date. Values presented in this file will be paid during the current open period in Cintra IQ.
Provided data within this file will result in adding new variable payment records for an employee. The file may contain more than one record per employee, as long as the Employee Number defined is a valid number of an already existing employee within the system.
Filename
File must be in the format of a comma-separated values (csv) file with values encapsulated in double quotes. The name of the file must be defined in the following format - {YYYYMMDD}_{HHMMSS}_VAR.csv (for example: 20210919_091545_VAR.csv).
Fields structure
Field Name | Format & Validation Rules | Additional Information |
|---|---|---|
Employee Number | Max length: 10 characters Accepts: letters (A-z), numbers (0-9). | Required Represents an Employee Identifier. |
Payment Code | Max length: 3 characters | Required Needs to match an Import Code reference of an existing Payment Heading in Cintra IQ. * |
Payment Name | Max length: 30 characters | Optional |
Start Date | Date in the format of “YYYY-MM-DD” | Required |
End Date | Date in the format of “YYYY-MM-DD” | Required |
Amount | Decimal (18,2) | If Payment type is set up as Monetary, then Amount is mandatory. |
Units | Decimal (18,2) | If Payment type is set up as Units * Rate, then Units are mandatory. |
Rate | Decimal (18,2) | Optional If passed, it will override the default Rate defined in Cintra IQ. |
* Important: As the Payment Code field needs to match an existing reference value within Cintra IQ, please refer to the Cintra team to set and confirm the respective reference values and ensure correct mapping.
4. Pensions and Benefits File
Summary
The Pensions and Benefits file is used to define and import and define employees’ pensions and benefits-related information such as contribution amounts and opt-in and opt-out dates.
Provided data within this file will either add new or modify existing employees’ pension and benefits records. The file may contain more than one record per employee, as long as the Employee Number defined is a valid number of an already existing employee within the system.
Filename
File must be in the format of a comma-separated values (csv) file with values encapsulated in double quotes. The name of the file must be defined in the following format - {YYYYMMDD}_{HHMMSS}_PEN.csv (for example: 20210918_195510_PEN.csv).
Adding a new record
If a record for a combination of Employee Number and Scheme Contribution Name is not present in the system, a new fixed payment record for this employee, with the defined information, will be created.
Modifying existing record
If a record for a combination of Employee Number and Scheme Contribution Name is already in the system, the related information will be updated, based on all field values defined under the record in the file. Please make sure you are providing full record information for all fields defined below and not only the modified fields.
Please Note: Processing this file will not perform any deletion of existing records, so it can’t be used for the purpose of that operation. If such an operation is required, a separate process is to be used.
Fields structure
Field Name | Format & Validation Rules | Additional Information |
|---|---|---|
Employee Number | Max length: 10 characters Accepts: letters (A-z), numbers (0-9). | Required Represents an Employee Identifier. |
Scheme Contribution Name | Max length: 30 characters | Required Needs to match an existing Scheme Contribution name, defined in Cintra IQ. * |
Start Date | Date in the format of “YYYY-MM-DD” | Required |
End Date | Date in the format of “YYYY-MM-DD” | Optional |
Is Percentage | Accepted values are “Y” or “N” | Required Represents whether the contributions are defined as Percentage (value is “Y”) or Amount (value is “N”). |
Employee Contribution Amount | Decimal (18,2) | Required if “Default Employee Contribution Amount” is not used (sent as “N”). Represents the Employee’s contribution amount (in set amount or percentage, depending on the above setting). |
Employer Contribution Amount | Decimal (18,2) | Required if “Default Employer Contribution Amount” is not used (sent as “N”). Represents the Employer’s contribution amount (in set amount or percentage, depending on the above setting). |
Use Default Employee Contribution Amount | Accepted values are “Y” or “N” | Required Yes / No |
Use Default Employer Contribution Amount | Accepted values are “Y” or “N” | Required Yes / No |
* Important: As the Scheme Contribution Name field needs to match an existing record within Cintra IQ, please refer to the Cintra technical support team to get an up-to-date list of reference values.
5. Absence File
The Absence file is used to define and import information about employees’ absence for a defined period of time. Hourly and daily absence are supported, including half-day and full day absence definitions.
Provided data within this file will either add new or modify existing employees’ absence records. The file may contain more than one record per employee, as long as the Employee Number defined is a valid number of an already existing employee within the system.
Filename
File must be in the format of a comma-separated values (csv) file with values encapsulated in double quotes. The name of the file must be defined in the following format - {YYYYMMDD}_{HHMMSS}_ABS.csv (for example: 20210910_122308_ABS.csv)
Adding a new record
An “Absence Record” within the system is defined by the Employee Number, Absence Code and period of absence defined by the Start Date and Start Date Half.
If an already existing absence record, with the given information about the above listed fields is found within the system, the End Date and End Date Half information will be updated, based on the data provided.
Note: The result of a new absence record entry will be presented as a calendar entry within the system. Some types of absences, such as parental leave or adoption leave for example, may still require additional specific information, which would still require to be provided and inserted into Cintra IQ separately.
Modifying existing record
An “Absence Record” within the system is defined by the Employee Number, Absence Code and period of absence defined by the Start Date and Start Date Half.
If no absence record, with the given information about the above listed fields is found within the system, a new absence record with the defined information, will be created.
Please Note: Processing this file will not perform any deletion of existing records, so it can’t be used for the purpose of that operation. If such an operation is required, a separate process is to be used.
Fields structure
Field Name | Format & Validation Rules | Additional Information |
|---|---|---|
Employee Number | Max length: 10 characters Accepts: letters (A-z), numbers (0-9). Unique per each employee. | Required Represents an Employee Identifier. |
Absence Code | Max length: 3 characters | Required Needs to match an Import Code reference of an existing Absence Record, defined in Cintra IQ. * |
Start Date | Date in the format of “YYYY-MM-DD” | Required |
End Date | Date in the format of “YYYY-MM-DD” | Required |
Start Date Half | Accepted values are “am”, “pm”, “full” | Required if absence is set up in Days |
End Date Half | Accepted values are “am”, “pm”, “full” | Required if absence is set up in Days |
Start Time | Time in the format of “HH:MM” | Required if absence is set up in Hours |
End Time | Time in the format of “HH:MM” | Required if absence is set up in Hours |
Duration | Time in the format of “HH:MM” | Optional Will be applied only if absence is set up in Hours Duration of absence is calculated based on the difference between the from time and end times. With this option the duration can be overridden. For example: If we have 5 hours of absence where 1 hour is lunch break, the default duration will be calculated as 4 hours, but with this we can override it to a specific defined amount of time. |
Absence Reason | Max length: 30 characters | Optional |
Notes | Max length: 1000 characters | Optional |
* Important: As the Absence Code field needs to match an existing reference value within Cintra IQ, please refer to the Cintra team to set and confirm the respective reference values and ensure correct mapping.
Attachments
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article