The Web Service process will utilize a SOAP (1.1 or 1.2) based Web Service in order to allow for electronic submission of properly formatted wage files. In order to use this service, clients will have to download
the (Web Service Description Language) WSDL and build a custom client.
Method: SubmitTestFile()
The input parameter(s) are as follows:
| Parameter |
Type |
Required |
Length min/max |
Description |
| FileContent |
ByteArray |
Yes |
N/A |
Binary representation of a file. |
| FileType |
Enumeration |
Yes |
N/A |
Identifies the type of file submitted. The four valid file types are MMREF, NASWA, Payment and Rate. |
| FileName |
String |
Yes |
5 / 75 |
The file name and extension used for the data file. This is used to ID the file on the server as well as extension for the compression used. |
The Return value(s) are as follows:
| Type |
Length min/max |
Description |
| String |
1 - 120 |
Unique transaction identifier |
If all of the above parameters pass the validation processes this method will return a unique transaction identifier (UTID), which is a unique string. This UTID will be used in subsequent calls. If a failure occurs
the Web service will generate a SOAP Fault with a descriptive error message and will need to be handled by your SOAP client. In the case of submitting a test file, the file will be validated but will not be processed.
In order to actually submit your data to the Kansas Department of Labor, you must use the SubmitFile() method.
Method: SubmitFile()
The input parameter(s) are as follows:
| Parameter |
Type |
Required |
Length min/max |
Description |
| FileContent |
Byte |
Yes |
N/A |
Binary representation of file. |
| FileType |
Enumeration |
Yes |
N/A |
Identifies the type of file submitted. The four valid file types are MMREF, NASWA, Payment and Rate. |
| FileName |
String |
Yes |
5 / 75 |
The file name and extension used for the data file. This is used to ID the file on the server as well as extension for the compression used. |
The Return value(s) are as follows:
| Type |
Length min/max |
Description |
| String |
1 - 120 |
Unique transaction identifier |
If all the above parameters pass the validation processes this method will return a unique transaction identifier (UTID), which is a unique string. This UTID will be used in subsequent calls. If a failure occurs
the Web service will generate a SOAP Fault with a descriptive error message and will need to be handled by your SOAP client.
Method: GetStatus()
The input parameter(s) are as follows:
| Parameter |
Type |
Required |
Length min/max |
Descriptio |
| UTID |
String |
Yes |
N/A |
This Unique transaction identifier that was returned by the SubmitFile() or SubmitTestFile() method. The UTID used to identify the file that was submitted. |
The Return value(s) are as follows:
| Type |
Length min/max |
Description |
| String |
1 - 30 |
Status value describing what state the current transaction is in. |
If a valid UTID is passed in, the status of the submission will be returned. If an invalid UTID is passed, status of "InvalidUTID" is returned. If for some reason something failed the web service will
generate a SOAP Fault with an error message that will need to be handled by your SOAP client.
| Status |
Description |
MMREF/NASWA |
Payment |
Rate |
| DataTransferError |
Indicates there was an error transferring the file from the client machine the Kansas Department of Labor server. |
|
X |
X |
| InvalidUTID |
Indicates that the UTID passed does not exist in our system. |
X |
X |
X |
| InvalidFileType |
Indicates an incorrect action on a given file type. Only MMREF, NASWA and Payment files may be committed. A Rate file may only be used for a RateRequest. |
X |
X |
X |
| DataContentError |
Indicates there was an unknown/unexpected error with the submitted file. |
X |
X |
X |
| DataContentErrorSize* |
Indicates the submitted file was too large. |
X |
X |
X |
| DataContentErrorInv* |
Indicates the submitted file was unreadable, used an incorrect character set, was found to contain malicious content or had too long of a filename. |
X |
X |
X |
| DataContentErrorComp* |
Indicates the submitted file uses an unsupported compression type. |
X |
X |
X |
| DataContentErrorFTP* |
Indicates the submitted file was unable to be saved in the KDOL file repository. |
X |
X |
X |
| Validating |
Indicates the file submission has been received and the KDOL system is currently validating the data submitted. |
X |
X |
X |
| DataValidationFailed |
Indicates that all of the data contained in the file submission was not valid. Use the GetUploadDetail() method for more details. |
X |
X |
X |
| DataLoadFailed |
Indicates there was an error loading the file information into the Kansas Department of Labor system. If this error occurs you are encouraged to try resubmitting the file. |
X |
X |
X |
| Submitted |
Indicates the file submission was a success and the Kansas Department of Labor has successfully received the wage information and at least one employer record is valid. You can use GetUploadDetail()
method to view invalid employer records. If you would like to go ahead and submit employer records that were valid, use the CommitValidRecords() method. |
X |
X |
X |
| Committing |
Indicates data from the file submission is currently being committed and loaded into the KDOL system. |
X |
X |
|
| Committed |
Indicates the records have been committed and will be processed shortly. Nothing more is required by the client. |
X |
X |
|
| Processed |
Indicates the Kansas Department of Labor has successfully received and loaded the committed wage information. Uploads can not be cleared at this point. |
X |
X |
|
| ProcessedPDFFail* |
Indicates the Kansas Department of Labor has successfully received and loaded the committed wage information, but PDFs were not successfully generated (only relevant for wage files). Uploads can not be cleared at this point. |
X |
|
|
| Cleared |
Indicates the submitted data has been cleared. |
X |
X |
|
* and statuses in green = New statuses coming in September 2017
Method: GetUploadDetail()
The input parameter(s) are as follows:
| Parameter |
Type |
Required |
Length min/max |
Description |
| UTID |
String |
Yes |
N/A |
This Unique transaction identifier that was returned by the SubmitFile() or SubmitTestFile() method. The UTID used to identify the file that was submitted. |
| CompressionType |
String |
Yes |
N/A |
Indicates the compression type used to return the detail file. Options are none, zip, gz (gzip) and bz2 (bzip2). |
| NumValid |
Integer |
No |
N/A |
Value is passed in by reference. An integer (can be any integer) will be passed in and the number of valid employers will be returned. |
| NumInvalid |
Integer |
No |
N/A |
Value is passed in by reference. An integer (can be any integer) will be passed in and the number of invalid employers will be returned. |
| FileContent |
ByteArray |
No |
N/A |
File (to be filled) containing a detailed analysis of the submitted file invalid lines. |
The Return value(s) are as follows:
| Type |
Length min/max |
Description |
| String |
1 - 100 |
Returns "True" on success. Returns an error message on failure. |
If a valid UTID is passed in, "True" is returned and the number of valid and invalid employers will be returned. In addition, a detailed file analysis will be returned of invalid records. If an invalid UTID is passed, an
error message will be returned. If a failure occurs the Web service will generate a SOAP Fault with an error message that will need to be handled by your SOAP client.
Method: CommitValidRecords()
The input parameter(s) are as follows:
| Parameter |
Type |
Required |
Length min/max |
Description |
| UTID |
String |
Yes |
N/A |
This Unique transaction identifier that was returned by the SubmitFile() method. The UTID is used to identify the file that was submitted. |
The Return value(s) are as follows:
| Type |
Length min/max |
Description |
| String |
1 - 100 |
Returns "True" on success. Returns an error message on failure. |
Prerequisite: Must have submitted a valid MMREF, NASWA or Payment file.
If a valid UTID is passed in, "True" is returned and all the records that were returned as valid in the GetUploadDetail() method will be submitted. Records will not be processed by KDOL if this method is not called. If an
invalid UTID is passed, an error message will be returned. If a failure occurs the Web service will generate a SOAP Fault with a descriptive error message and will need to be handled by your SOAP client.
Method: GetRateData()
The input parameter(s) are as follows:
| Parameter |
Type |
Required |
Length min/max |
Description |
| UTID |
String |
Yes |
N/A |
This Unique transaction identifier that was returned by the SubmitFile() method. The UTID is used to identify the file that was submitted. |
| CompressionType |
Enumeration |
Yes |
N/A |
Indicates the compression type used to return the detail file. Options are none, zip, gz (gzip) and bz2 (bzip2). |
| FileContent |
ByteArray |
No |
N/A |
Passed by reference. File containing the requested rate information. |
The Return value(s) are as follows:
| Type |
Length min/max |
Description |
| String |
1 - 100 |
Returns "True" on success. Returns an error message on failure. |
Prerequisite: Must have submitted a valid file of type Rate.
If a valid UTID is passed in, "True" is returned and all the records that were submitted for a rate inquiry and are valid will be returned in the file containing the rate for each employer. An employer record
is deemed valid if two of the three required fields match our records. The three required fields are Name, FEIN and Serial Number. If an invalid UTID is passed, an error message will be returned. If a failure occurs the
Web service will generate a SOAP Fault with a descriptive error message and will need to be handled by your SOAP client.
Method: GetTransactionDetail()
The input parameter(s) are as follows:
| Parameter |
Type |
Required |
Length min/max |
Description |
| UTID |
String |
Yes |
N/A |
This Unique Transaction Identifier (UTID) that was returned by the SubmitFile() method. The UTID is used to identify the file that was submitted. |
| Confirmation |
String |
No |
N/A |
The confirmation number used to identify a committed file for processing. |
| CommitDate |
String |
No |
N/A |
The date you successfully committed your information to be processed as a string. |
| Totals |
Double |
No |
N/A |
The total number of accounts committed for processing, or the total number of dollars made for payments, depending on the file type you submitted. |
| Accounts |
Int Array |
No |
N/A |
A list of valid accounts that will be processed after a commit has been submitted. |
The Return value(s) are as follows:
| Type |
Length min/max |
Description |
| String |
1 - 100 |
Returns "True" on success. Returns an error message on failure. |
If a valid UTID is passed in, "True" will be returned and all the wage detail record or payment information totals committed will be returned. Upload must first be committed before this function can be called. If a failure
occurs the Web service will generate a SOAP Fault with a descriptive error message and will need to be handled by your SOAP client.
Method: ClearUpload()
The input parameter(s) are as follows:
| Parameter |
Type |
Required |
Length min/max |
Description |
| UTID |
String |
Yes |
N/A |
This Unique Transaction Identifier (UTID) that was returned by the SubmitFile() method. The UTID is used to identify the file that was submitted. |
The Return value(s) are as follows:
| Type |
Length min/max |
Description |
| String |
1 - 100 |
Returns "True" on success. Returns an error message on failure. |
If a valid UTID is passed in, "True" will be returned and all the wage detail records submitted will be cleared. Wage detail information that already has a status of "Processed" cannot be cleared.
Therefore if the status is "Processed" or an invalid UTID is passed, an error message will be returned. If a failure occurs, the Web service will generate a SOAP Fault with a descriptive error message and will
need to be handled by your SOAP client.