ROE Web user requirements – Appendix D
- 1. Overview
- 2. General requirements
- 3. Functional requirements
- 4. System requirements
- 5. Appendix A - ROE Online Data Entry
- 6. Appendix B - Technical Specifications
- 7. Appendix C - Import XML file format
- 8. Appendix D - ROE payroll extract file transfer – XML Ver. 2.0
- 9. Appendix E - ROE payroll extract file transfer - XML file layout and edit – Fishing ROE Version 1.0
8. Appendix D - ROE payroll extract file transfer - XML file layout and edit - Version 2.0
December 3, 2017 Update: Block 16 (Code Z00), Block 17C (code U12) and Block 19 (Code MAT01) have been renamed to reflect the new Family Caregiver Benefits.
8.1 General format requirements
The following section outlines the general format specifications for completing Records of Employment (ROEs) using the XML ROE Web payroll extract file.
8.1.1 Prerequisites
To create the ROE Web payroll extract file, you must have the following:
- in-depth knowledge of XML (W3C)
- in-depth knowledge of XML schemas
To submit your information to Service Canada via an ROE payroll extract file, you must create an XML file formatted according to Service Canada's XML schema. The schema is a file that defines the rules you need to follow in order to construct your XML file. The schema specifies which fields are required and which are optional. To some extent, it constrains the makeup of the data that can be included in the XML file.
Service Canada will provide you with a schema file, which you can use to validate your XML payroll extract files prior to submitting them to Service Canada.
Service Canada recommends the following maximum for all XMLVersion 2.0 Payroll Extract files: 1MB of data or 1200 ROEs, whichever comes first. This also applies to files being submitted in the ROE Web Demo.
8.1.2 Character set
Service Canada uses a sub-set of the UTF-8 character set for the ROE Web payroll extract file. Here are the characters you can use on an ROE:
Description | Acceptable characters | Numeric character | Alphanumeric character |
---|---|---|---|
Uppercase letters | ABCDEFGHIJKLMNOPQRSTUVWXYZ | No | Yes |
Lowercase letters | abcdefghijklmnopqrstuvwxyz | No | Yes |
Uppercase letters with accent | Á À Â Ä Ç É È Ê Ë Í Ì Î Ï Ó Ò Ô Ö Ú Ù Û Ü | No | Yes |
Lowercase letters with accent | á à â ä ç é è ê ë í ì î ï ó ò ô ö ú ù û ü | No | Yes |
Numbers | 0 1 2 3 4 5 6 7 8 9 | Yes | Yes |
Special characters |
" ; % ! ) ( * # - + / $ & @ = ? : ' ~ | ` ^ _ [ { ] } | No | Yes |
. , | Yes | Yes |
8.1.3 Conventions used in XML specification document
The following conventions are used in Service Canada's ROE Web payroll extract file specification document:
Type | Description |
---|---|
Dates | CCYY-MM-DD (year-month-day) |
Postal codes | No embedded spaces or dashes (-) Canada: X9X9X9 US: 99999 or 999999999 |
Decimal place |
For an amount of money, the format requires a fixed decimal place, with two decimal places. Do not include currency indicator (e.g. £, € or $). Service Canada only accepts "." as a decimal place notation For example, 12345.00 represents the amount of $12,345.00 |
Numeric character | Numbers from 0 to 9 |
Alphanumeric character | Upper case and lower case letters (e.g., codes and types) |
Character | Any character accepted under the UTF-8 character set can be used except for the following five pre-declared entities that must be escaped:
|
Sequence number | The first sequence number for a particular element (e.g., block 17B where up to 10 statutory holidays can be provided) should begin at "1". Use "2" for the second sequence number, etc. |
8.1.4 File naming standard
Each file name must include a file prefix, a dot and an extension as follows (e.g. ACME_ROE200.BLK):
Component | Requirement |
---|---|
File prefix | Maximum of 256 alphanumeric characters |
<dot> | Period to separate the file name from the extension |
Extension | File extension is "BLK" |
Note:
File names are not case sensitive; that is, you may use upper or lower case letters.
8.2 ROE payroll extract file specifications
This section contains detailed specifications of the ROE Web payroll extract file. Each line required within the file is described and includes requirements specific to attributes and ROE blocks.
8.2.1 XML declaration tag format
The XML declaration must be the first line in the document. No other content or white space can precede it.
Attribute name | Description | Requirements |
---|---|---|
version | Version number | Mandatory The value must be "1.0" |
encoding | The encoding declaration must appear immediately after the version information in the XML declaration. | Mandatory The value should match the encoding of the file. Service Canada recommends UTF-8 |
Examples:
<?xml version="1.0" encoding="UTF-8" ?>
<?xml version="1.0" encoding="ISO-8859-1" ?>
8.2.2 Header tag format
The "ROEHEADER" tag is the header element. It occurs only once per file, contains four attributes and also contains all ROE tags (or elements) before being closed.
Attribute name | Description | Requirements |
---|---|---|
File version | Format version of the ROE payroll extract file. | Mandatory The value must be "W-2.0" |
Software vendor | Name of Software Vendor used by the employer. | Mandatory Up to 100 alphanumeric characters Minimum of 1 character required |
Product name | Name of Payroll Software used by employer. | Mandatory Up to 100 alphanumeric characters Minimum of 1 character required |
Product version | Version of the Payroll Software. | Optional Up to 10 alphanumeric characters |
Example:
<ROEHEADER FileVersion="W-2.0" SoftwareVendor="XYZ Software Vendor" ProductName="PS3000" ProductVersion="2.1.1">
8.2.3 Transaction tag format
The "ROE" tag occurs as many times as there are ROEs to be processed and must contain the following attributes.
Attribute name | Description | Requirements |
---|---|---|
Printing Language | The language the ROE was printed in. | Mandatory Must be one of the following codes:
|
Issue | Represents which processing method should be attempted on the ROE. | Mandatory Must be one of the following codes:
|
Example:
<ROE PrintingLanguage="E" Issue="D">
8.2.4 XML structure
This section shows the entire XML structure of the ROE Web payroll extract file used by employers to submit ROEs to Service Canada.
<?xml version="1.0" encoding="UTF-8" ?>
<ROEHEADER FileVersion="W-2.0" SoftwareVendor="XYZ Software Vendor" ProductName="PS5000" ProductVersion="2.1.1">
<ROE PrintingLanguage="E" Issue="D">
<B2></B2>
<B3></B3>
<B5></B5>
<B6></B6>
<B8></B8>
<B9>
<FN></FN>
<MN></MN>
<LN></LN>
<A1></A1>
<A2></A2>
<A3></A3>
<PC></PC>
</B9>
<B10></B10>
<B11></B11>
<B12></B12>
<B13></B13>
<B14>
<CD></CD>
<DT></DT>
</B14>
<B15A></B15A>
<B15C>
<PP nbr="1">
<AMT></AMT>
</PP>
<PP nbr="2">
<AMT></AMT>
</PP>
…
<PP nbr="53">
<AMT></AMT>
</PP>
</B15C>
<B16>
<CD></CD>
<FN></FN>
<LN></LN>
<AC></AC>
<TEL></TEL>
<EXT></EXT>
</B16>
<B17A>
<VP nbr="1">
<CD></CD>
<SDT></SDT>
<EDT></EDT>
<AMT></AMT>
</VP>
</B17A>
<B17B>
<SH nbr="1">
<DT></DT>
<AMT></AMT>
</SH>
<SH nbr="2">
<DT></DT>
<AMT></AMT>
</SH>
…
<SH nbr="10">
<DT></DT>
<AMT></AMT>
</SH>
</B17B>
<B17C>
<OM nbr="1">
<CD></CD>
<SDT></SDT>
<EDT></EDT>
<AMT></AMT>
</OM>
<OM nbr="2">
<CD></CD>
<SDT></SDT>
<EDT></EDT>
<AMT></AMT>
</OM>
<OM nbr="3">
<CD></CD>
<SDT></SDT>
<EDT></EDT>
<AMT></AMT>
</OM>
</B17C>
<B18></B18>
<B19>
<SP cd="">
<SDT></SDT>
<EDT></EDT>
<AMT></AMT>
<PRD></PRD>
</SP>
…
<SP cd="">
<SDT></SDT>
<EDT></EDT>
<AMT></AMT>
<PRD></PRD>
</SP>
</B19>
<B20></B20>
</ROE>
<ROE PrintingLanguage="F" Issue="S">
<B2></B2>
…
</ROE>
</ROEHEADER>
8.2.5 XML schema
You can use the following PayrollExtractXmlV2.xsd (20kb) file to validate the payroll extract file structure before transferring the file using ROE Web. To perform this kind of validation, you need a tool that is capable of validating an XML schema.
8.3 Transaction block elements format
This section includes the edit and business rules for each ROE block and field.
Notes
September 18, 2015: Employers are no longer required to provide an amount from Block 15B in Version 2.0 of the XMP Payroll Extract file as it is now automatically calculated by ROE Web.
When a ROE is opened using the ROE Web Online Form, a message will appear above the amount automatically calculated in Block 15B. This message is intended as a notice to ensure that users are aware (and can verify if required) the amount that the system has auto-calculated on their behalf.
March 23, 2016: The following changes have been made to Version 2.0 of the Payroll Extract file. Please note that these changes are ONLY for file validation. Individual ROE validation remains unchanged and employers still have to provide these values in order for their ROEs to be submitted successfully to Service Canada.
- B6 : can be blank
- B8: can be blank
- B10, B11 and B12: can be blank
- B14: can be blank and “Unknown” will be assumed
- B15A: can be blank or between 0-9999
- B15C: can be blank
- B16: area code can be blank
- B16: phone number can be blank
- B17B AMT: can be blank
- B17C CD: can be blank
- B19 CD: can be blank
ROE block no. /field name | Tag name | Tag level | Required tag (Y/N) | Requirements |
---|---|---|---|---|
2 – Serial Number of ROE amended or replaced | B2 | 2 | N | Optional, but if completed:
|
3 – Employer's Payroll Reference Number | B3 | 2 | N | Optional, but if completed:
|
5 – CRA Payroll Account Number (aka Business Number) | B5 | 2 | Y |
Examples: Mandatory
|
OrgNum | 2 | N | Optional, but if completed:
Note: If multiple BNs are used under one organization, you do not need to provide an OrgNum. |
|
FolderCD | 2 | N | Optional, but if completed:
|
|
6 – Pay Period Type | B6 | 2 | Y | Mandatory
|
8 – Social Insurance Number | B8 | 2 | Y | Mandatory
|
9 – Employee's Information (Parent Tag) | B9 | 2 | Y |
Must be present, it only contains other tags Example:
|
9 – Employee's First Name | FN | 3 | Y | Mandatory Up to 20 alphanumeric characters |
9 – Employee's Initial | MN | 3 | N | Optional, but if completed:
|
9 – Employee's Last Name | LN | 3 | Y | Mandatory
|
9 – Employee's Address line 1
(Number and street name) |
A1 | 3 | Y | Mandatory
|
9 – Employee's Address line 2
(Place, city and municipality) |
A2 | 3 | Y/N | Mandatory Up to 35 alphanumeric characters |
9 – Employee's Address line 3
(Province and country) |
A3 | 3 | N | Optional, but if completed:
|
9 – Employee's Postal Code | PC | 3 | Y | Mandatory
|
10 – First day worked | B10 | 2 | Y | Mandatory
Must pass the following overlapping ROE rule:
|
11 – Last day for which paid | B11 | 2 | Y | Mandatory
|
12 – Final Pay Period ending date | B12 | 2 | Y | Mandatory
|
13 – Employee Occupation | B13 | 2 | N | Optional, but if completed:
|
14 – Expected Recall Information (Parent Tag) | B14 | 2 | Y |
Must be present, it only contains other tags. Example:
|
14 – Expected recall – code | CD | 3 | Y | Must not be blank: Must be 1 character Must be one of the following codes:
U-is the default value Code "Y – Expected date of recall" is not allowed when Reason for Issuing this ROE is "E00 – Quit" (including all sub-codes), "G00 – Mandatory Retirement" (including all sub-codes) or "M00 – Dismissal" (including all sub-codes). |
14 – Expected recall – date | DT | 3 | N |
Mandatory only when Expected recall code 'Y' is selected Must be blank if code N or U is selected If completed:
|
15A – Total Insurable Hours | B15A | 2 | Y | Mandatory
|
15C - Insurable Earnings Information
(Parent Tag) |
B15C | 2 | Y |
Must be present, it only contains other tags Up to 53 Pay Periods The number of consecutive pay periods entered in block 15C must be equal to the period of employment up to the maximum number of Pay Periods possible according to table 15C.1 Examples:
|
15C – Pay Period Information | PP | 3 | Y |
Must be present, it only contains other tags The following attribute must be present to identify each Pay Period: nbr |
15C - Insurable Earnings - Amount | AMT | 4 | Y |
|
16 – Reason for issuing this ROE information (Parent Tag) | B16 | 2 | Y |
Must be present, it only contains other tags Example:
|
16 – Reason for issuing this ROE – Separation Code | CD | 3 | Y | Mandatory
|
16 – Reason for issuing this ROE – Contact's First Name | FN | 3 | Y | Mandatory.
|
16 – Reason for issuing this ROE – Contact's Last Name | LN | 3 | Y | Mandatory
|
16 – Reason for issuing this ROE – Contact's Area Code | AC | 3 | Y | Mandatory
|
16 – Reason for issuing this ROE – Contact's Phone Number | TEL | 3 | Y | Mandatory
|
16 – Reason for issuing this ROE – Contact's Phone Extension Number | EXT | 3 | N | Optional, but if completed:
|
17A – Vacation Pay information (Parent Tag) | B17A | 2 | N |
Must be present when Vacation Pay information is completed Up to 1 Vacation Pay type may be provided When block 17A is completed, Vacation Pay Code, Vacation Pay Start Date, Vacation Pay End Date and Vacation Pay Amount may be required according to table 17A.1 Example:
|
17A – Vacation Pay information | VP | 3 | N |
Must be present when Vacation Pay information is completed, it only contains other tags. The following attribute must be present to identify each Vacation Pay paid: nbr |
17A – Vacation Pay Code | CD | 4 | N | Mandatory:
|
17A – Vacation Pay Start Date | SDT | 4 | N | Refer to table 17A.1 for completion rules If completed:
|
17A – Vacation Pay End Date | EDT | 4 | N | Refer to table 17A.1 for completion rules If completed:
|
17A – Vacation Pay Amount | AMT | 4 | N | Refer to table 17A.1 for completion rules If completed:
|
17B – Statutory Holiday information (Parent Tag) | B17B | 2 | N |
Must be present when Statutory Holiday information is completed Up to 10 statutory holidays When block 17B is completed, Statutory Holiday Pay for Date may be provided (optional) and Statutory Holiday Pay for Amount must be provided (mandatory) for each statutory holiday pay completed. All amounts entered in block 17B are considered insurable and therefore must be added to Insurable Earnings in block 15B and block 15C, Pay Period 1 Example:
|
17B – Statutory Holiday information | SH | 3 | N |
Must be present when Statutory Holiday information is completed, it only contains other tags The following attribute must be present to identify each Statutory Holiday paid: nbr |
17B - Statutory Holiday Pay for Date | DT | 4 | N | Optional, but if completed:
|
17B - Statutory Holiday Pay for Amount | AMT | 4 | N | Mandatory:
|
17C – Other Monies information (Parent Tag) | B17C | 2 | N |
Must be present when Other Monies information is completed Up to 3 other monies may be reported When block 17C is completed, Other Monies Code, Other Monies Start Date, Other Monies End Date and Other Monies Amount may be required according to table 17C.1. Example:
|
17C – Other Monies information | OM | 3 | N |
Must be present when Other Monies information is completed, it only contains other tags. The following attribute must be present to identify each Other Monies paid: nbr |
17C – Other Monies Code | CD | 4 | N | Mandatory:
|
17C – Other Monies Start Date | SDT | 4 | N | Refer to table 17C.1 for completion rules Optional but if completed:
|
17C – Other Monies End Date | EDT | 4 | N | Refer to table 17C.1 for completion rules Optional but if:
|
17C – Other Monies Amount | AMT | 4 | N | Refer to table 17C.1 for completion rules Optional but if completed:
|
18 – Comments | B18 | 2 | N | Optional, but if completed:
|
19 – Special Payments information (Parent Tag) | B19 | 2 | N |
Must be present when Special Payments information is completed When block 19 is completed, Special Payment Type, Special Payments Start Date, Special Payments End Date, Special Payments Amount and Special Payment Period may be required according to table 19.1 One entry of each Special Payments Type may be provided. A ROE may have up to four Special Payment Type entries but only one of each type is permitted on a single ROE. Example:
|
19 – Special Payments information | SP | 3 | N |
Must be present when Special Payments information is completed, it only contains other tags. The following attribute must be present to identify each Special Payments paid: cd |
19 – Special Payments Start Date | SDT | 4 | N |
Refer to table 19.1 for completion rules Optional, but if completed:
|
19 – Special Payments End Date | EDT | 4 | N | Refer to table 19.1 for completion rules Optional, but if completed:
|
19 – Special Payments Amount | AMT | 4 | N | Refer to table 19.1 for completion rules Optional, but if completed:
|
19 – Special Payments Period | PRD | 4 | N |
Refer to table 19.1 for completion rules Optional, but if completed: Must be one of the following codes:
|
20 – Issuer's communication preferred in | B20 | 2 | N |
Optional, but if completed: Must be 1 character Must be one of the following code:
Note: The system defaults to "E" when left blank. |
8.3.1 Table 15A.1 – Total Insurable Hours
The following table shows the maximum number of Pay Periods used to calculate the Total Insurable Hours in block 15A (or less if the period of employment is shorter) based on the selected Pay Period type in block 6 and the period of employment.
Pay Period type code (Block 6) | Description | Maximum number of Pay Periods to include for Total Insurable Hours (Block 15A) |
---|---|---|
B | Bi-weekly | Last 27 |
M | Monthly | Last 13 |
O | Monthly non-standard | Last 13 |
S | Semi-monthly | Last 25 |
E | Semi-monthly non-standard | Last 25 |
H | 13 Pay Periods per year | Last 14 |
W | Weekly | Last 53 |
8.3.2 Table 15C.1 – Insurable Earnings by Pay Period
The following table shows the maximum number of Pay Periods to enter in block 15C based on the selected Pay Period type in block 6 and the period of employment.
The number of Pay Periods consecutively filled out in block 15C must represent the number of Pay Periods during the last full year (or shorter if the period of employment is shorter) or since the beginning of employment (i.e. since the last Record of Employment was issued). It is based on the Pay Period type (block 6), plus one more Pay Period.
The first entry should be the earnings for the final (most recent) insured Pay Period. Enter details by Pay Period according to the chart. Where there is a Pay Period with zero or no insurable earnings enter "0.00".
Pay Period type code (Block 6) | Description | Maximum number of Pay Periods to enter in Block 15C |
---|---|---|
B | Bi-weekly | Last 27 |
M | Monthly | Last 13 |
O | Monthly non-standard | Last 13 |
S | Semi-monthly | Last 25 |
E | Semi-monthly non-standard | Last 25 |
H | 13 Pay Periods per year | Last 14 |
W | Weekly | Last 53 |
8.3.3 Table 16.1 – Reason for issuing this ROE – Separation Codes
Code | Description |
---|---|
A00 | Shortage of work/End of contract or season |
A01 | Employer bankruptcy or receivership |
B00 | Strike or lockout |
D00 | Illness or injury |
E00 | Quit |
E02 | Quit/Follow spouse |
E03 | Quit/Return to school |
E04 | Quit/Health reasons |
E05 | Quit/Voluntary retirement |
E06 | Quit/Take another job |
E09 | Quit/Employer relocation |
E10 | Quit/Care for a dependant |
E11 | Quit/To become self-employed |
F00 | Maternity |
G00 | Mandatory retirement |
G07 | Retirement/Approved workforce reduction |
H00 | Work-Sharing |
J00 | Apprentice training |
K00 | Other |
K12 | Other/Change of payroll frequency |
K13 | Other/Change of ownership |
K14 | Other/Requested by Employment Insurance |
K15 | Other/Canadian Forces - Queen's Regulations/Orders |
K16 | Other/At the employee's request |
K17 | Other/Change of Service Provider |
M00 | Dismissal |
M08 | Dismissal/Terminated within probationary period |
N00 | Leave of absence |
P00 | Parental |
Z00 | Compassionate Care/Family Caregiver |
8.3.4 Table 17A.1 – Vacation Pay
The table below shows the Vacation Pay codes available. For each of the codes, it identifies which Start Date, End Date and Amount are mandatory when completed.
Code | Description | Start Date |
End Date |
Amount |
---|---|---|---|---|
1 | Included with each pay | Must be blank | Must be blank | Must be blank |
2 | Paid because no longer working | Must be blank | Must be blank | Mandatory |
3 | Paid for a vacation leave period | Optional | Optional | Mandatory |
4 | Anniversary (Paid on a specific date each year) | Optional | Must be blank | Mandatory |
For Vacation Pay code 2 – Paid because no longer working, ensure the Vacation Pay amount is included in block 15C Pay Period 1.
If the Vacation Pay is paid as a result of an anniversary date, the amount should be included in the Pay Period in which the date falls or, if the date is after the Last day for which paid include the amount in block 15C Pay Period 1.
8.3.5 Table 17C.1 – Other Monies
The table below shows the Other Monies codes available. For each of the codes, it identifies which Start Date, End Date and Amount are optional or mandatory when completed as well as whether or not the other monies type is an insurable amount.
Note:
All amounts entered in block 17C that are considered insurable must be added to Insurable Earnings in block 15B and block 15C, Pay Period 1.
Code | Description | Start Date | End Date | Amount | Insurable If yes, the amount must be included in block 15C PP1 and block 15B |
---|---|---|---|---|---|
B05 | Bonus (Holiday) | Optional | Must be blank | Mandatory | Yes |
B06 | Bonus (Production/Incentive) | Optional | Optional | Mandatory | Yes |
B07 | Bonus (Event) | Optional | Must be blank | Mandatory | Yes |
B08 | Bonus (Staying/Contract complete/End of season) | Must be blank | Must be blank | Mandatory | Yes |
B09 | Bonus (Separation or retirement) | Must be blank | Must be blank | Mandatory | Yes |
B10 | Bonus (Closure) | Must be blank | Must be blank | Mandatory | Yes |
B11 | Bonus (Other) | Must be blank | Must be blank | Mandatory | Yes |
E00 | Severance pay | Must be blank | Must be blank | Mandatory | No |
G00 | Gratuities | Must be blank | Must be blank | Mandatory | Yes |
H00 | Honorariums | Optional | Optional | Mandatory | No |
I00 | Sick leave credits | Optional | Must be blank | Mandatory | Yes |
J00 | Retroactive pay adjustment | Must be blank | Must be blank | Mandatory | Yes |
O00 | Other | Optional | Optional | Mandatory | Yes |
Q00 | Profit sharing | Must be blank | Must be blank | Mandatory | Yes |
R00 | Retiring allowance/Retirement leave credits | Must be blank | Must be blank | Mandatory | No |
S00 | Settlement pay | Optional | Optional | Mandatory | Yes |
T00 | Payout of banked overtime | Must be blank | Must be blank | Mandatory | Yes |
U12 | SUB Maternity/Parental/Compassionate Care/Family Caregiver | Must be blank | Must be blank | Optional | No |
U13 | SUB Layoff | Must be blank | Must be blank | Optional | No |
U14 | SUB Illness | Must be blank | Must be blank | Optional | No |
U15 | SUB Training | Must be blank | Must be blank | Optional | No |
Y00 | Pay in lieu of notice | Must be blank | Must be blank | Mandatory | Yes |
8.3.6 Table 19.1 – Special Payments
Code | Description | Start Date |
End Date |
Amount | Period |
---|---|---|---|---|---|
PSL01 | Paid sick leave (EI Insurable) | Optional | Optional | Mandatory | Optional |
WLI01 | Wage loss indemnity (Not EI insurable) | Optional | Optional | Optional | Optional |
WLI02 | Wage loss indemnity (EI Insurable) | Optional | Optional | Optional | Optional |
MAT01 | Paid Maternity/Parental/Compassionate Care/Family Caregiver leave (EI Insurable) | Optional | Optional | Mandatory | Optional |
Page details
- Date modified: