How to upload your HR data using our Console app

The console app is a small windows command line application that takes a CSV file containing your employee data and syncs it with our system. We built it for customers who do not have the in-house developer resources to pull the data from their HR system, format it in the required file format (XML) and post it to our REST API.

The app is designed to be automated and therefore does not have a desktop user interface. It relies on commands being entered on the command line and is not recommended for non technical users to operate.

We highly recommend that the app is installed onto a server and scheduled to run automatically at a pre-determined time with a specified file (e.g. “C:\path_to_file\employees.csv”). Ideally, you would schedule a file export process to save the file in the required folder and then run the ‘upload’ command.

How does it work?

1. You first create a CSV file containing data for all Active employees
2. You then run the app (providing the path to your file)
3. The app converts your CSV into an XML file
4. The XML file is validated
5. The file is posted to our system using our REST API
6. The file is processed by our system

How to get started?

1. Download and install the console app - see Download & Installation
2. Create a CSV file containing your data - see File Requirements
3. Setup the console app (including mapping your columns to our fields) - see Setup & Configuration
4. Run the app manually using the ‘validate’ function to check your mappings and data are correct - see How to run the app manually
5. Fix any issues and re-run the validation step
6. Run the app manually using the ‘upload’ function - see How to run the app manually
7. Login to the administration portal and check the file has processed
8. Fix any data issues and re-run the upload

You can repeat the above steps every time you want to update your data but we recommend that you schedule a task to export your CSV file and another task to run the app using the ‘upload’ function.

Download & Installation

Download the installer using the below link:

https://downloads.workstars.com/consoleapp/1.0.2/WorkstarsSyncInstaller(1.0.2).exe

If your security settings prevent the direct download of .exe files, please use the below link to download a .zip file which contains the installer:

https://downloads.workstars.com/consoleapp/1.0.2/WorkstarsSyncInstaller(1.0.2).zip

Verify Digital Signature

The installer (and all the application files) are signed using our Code Signing certificate issued by Sectigo (formerly Comodo CA).

To verify the digital signature, make sure you have the .exe file. If you have downloaded the .zip you must extract the .exe file first (e.g. to your desktop)

1. Right click the installer .exe file and select Properties
2. Select the Digital Signatures tab
3. Click the entry in the list and click the Details button
4. You should see “The digital signature is OK” at the top
5. Click the View Certificate button
6. The certificate should be issued to “Workstars Global Ltd.” and be issued by “Sectigo RSA Code Signing CA”
7. You can also check the Certification Path tab to ensure all certificates are valid and report up the the “Sectigo (AAA)” root certificate.

Verify File Hash

To ensure the file you have downloaded has not been tampered with, you should check it matches the appropriate SHA256 hashes listed below.

The easiest way to generate a hash is to use the “certutil” app that is part of Windows:

1. Open the windows command line interface. To do this you can either click the magnifying glass (search) icon next to the windows start button or hold down the windows key and press “S”. In the search box type “cmd.exe” and press the enter key on your keyboard. Please note that your company security policy may prevent this, please check with your IT Team if you are having issues opening the command line.
2. Find the path and filename. Right click on the file and select Properties (you can do this on either the .zip or the .exe file, if you want to do it on the .exe. file you must extract it from the zip first). Find the Location field and make a note of the path (e.g. it will look something like “C:\Users\workstars\Downloads”).
3. In the command window type the following and press “Enter”:

certutil -hashfile {file_name} SHA256

Where {file_name} is the path from Step 2, with the filename on the end.

For example, if it is something like “C:\Users\workstars\Downloads\WorkstarsSyncInstaller(1.0.2).exe”, you would type:

certutil -hashfile C:\Users\workstars\Downloads\WorkstarsSyncInstaller(1.0.2).exe SHA256

4. Compare the hash it generates to one of the following:

File Type	SHA 256 Hash
.exe	0aa96e97c04e7ea89f27691d104fd9db06124e835bcb61814ef91d1ccb9040ec
.zip	a9c93eb97441ef19613d6be750efcd007c0b24ae18e5997987b4f3aafd23aebe

 

File Requirements

• The file must be a CSV file, we do not support XLS or XLSX files (i.e. it must be viewable in a text editor, like notepad)
• The file must include your entire HRIS roster of Active employees; Any employee excluded from the file will be automatically deleted from the recognition platform
• The file should be saved with UTF-8 encoding in case you have (or will have) any employees with diacritic characters in their name (e.g. “é”)
• It can contain more than the required data, any non-mapped columns will be ignored
• It can contain the columns in any order, you must map each column to one of our fields in the config file

Required Data

The required data depends on how your program is configured (hierarchy is either managed by your managers or via the company). If you do not know, please contact your account manager.

Field	Managers	Company	Notes
Employee ID	Y	Y	This is the employee’s unique ID
Reports To	N	Y	For company managed programs this is the Employee ID of the person the employee reports to (usually their manager). Not required for manager managed programs.
Is Manager?	Y	N	For manager managed programs this indicates who is a manager and can build their own team. Not required for company managed programs.
First Name	Y	Y	This is the employee’s first name
Last Name	Y	Y	This is the employee’s last name
Email Address	Y	Y	This is the email address of the employee
Department	Y	Y	This is the department where the employee works
Job Title	Y	Y	This is the job title of the employee
Is Contractor?	Y	Y	This indicates if the employee is a contractor
Start Date	Y	Y	This is the date the employee joined your organisation
Country	Y	Y	This is the country the employee works in
Is Manager?	Y	N	For manager managed programs this indicates who is a manager and can build their own team

Please see the individual field notes below for details:

Employee ID

• Must be alphanumeric (lowercase only)
• Max 30 characters
• Must be unique

First Name

• Must be alphanumeric
• Max 50 characters

Last Name

• Must be alphanumeric
• Max 50 characters

Email Address

If you are running offline invites (e.g. some employees don’t have a company email and you are going to send them their login details manually), this can be blank. Otherwise:

• Max 50 characters
• Must be a valid email format
• The domain must be functional (we will check its DNS MX record)

Department

• Max 100 characters

Job Title

• Max 100 characters

Is Contractor?

This should contain one of the following valid values, depending on the employment type:

Are they a contractor?	Valid Values
Yes	1, true, “yes” or “y”
no	0, false, “no” or “n”

Note

Start Date

• Must be in the format YYYY-MM-DD (e.g. 2017-12-13)

Country

• Must be the ISO 2 digit country code (see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
• Must be a country that has been setup in your program

Is Manager?

This should contain one of the following valid values:

Are they a manager?	Valid Values
Yes	1, true, “yes” or “y”
no	0, false, “no” or “n”

Reports To

• Must be alphanumeric (lowercase only)
• Max 50 characters
• For the employee at the top of your hierarchy (i.e. MD, CEO, etc.) this should be left blank.

Example Files

Below are some example files, depending on how your program is configured:

Manager Managed

First Name,Last Name,Email Address,Department,Employee ID,Job Title,Start Date,Country,Is Manager?,Is Contractor?
Ian,Ratcliffe,ian.ratcliffe@example.com,smt,md,MD,2019-01-01,GB,1,0
Brian,Halsey,brian.halsey@example.com,sales,2,Sales Manager,2019-01-03,GB,1,0
Eric,Bay,eric.bay@example.com,sales,4,Sales,2019-01-04,GB,0,0
Dave,Michaels,dave.michaels@example.com,it,3,IT Manager,2019-01-05,GB,1,0
Wesley,Ephron,wesley.ephron@example.com,it,c1,IT Support,2019-01-23,GB,0,1

Company Managed

First Name,Last Name,Email Address,Department,Employee ID,Job Title,Start Date,Country,Reports To,Is Contractor?
Ian,Ratcliffe,ian.ratcliffe@example.com,smt,md,MD,2019-01-01,GB,,0
Brian,Halsey,brian.halsey@example.com,sales,2,Sales Manager,2019-01-03,GB,md,0
Eric,Bay,eric.bay@example.com,sales,4,Sales,2019-01-04,GB,2,0
Dave,Michaels,dave.michaels@example.com,it,3,IT Manager,2019-01-05,GB,md,0
Wesley,Ephron,welsey.ephron@example.com,it,5,IT Support,2019-01-23,GB,2,1

Setup & Configuration

Before you can use the app you must configure the settings and tell it which columns relate to each data field. The config file is called “WorkstarsSync.exe.config” and is in the same folder as the app. To edit it you should open it in a text editor (e.g. Notepad).

App Settings

First, you should configure the app settings, this section is at the bottom of the config file.

<appSettings>
  <add key="subdomain" value="" />
  <add key="api_key" value="" />
  <add key="csv_header" value="false" />
  <add key="hierarchy_type" value="" />
  <add key="smtp_enabled" value="false" />
  <add key="smtp_host" value="" />
  <add key="smtp_port" value="" />
  <add key="smtp_username" value="" />
  <add key="smtp_password" value="" />
  <add key="smtp_from_address" value="" />
  <add key="smtp_to_address" value="" />
</appSettings>

subdomain

The subdomain is the part before “workstars.com” in the URL you use to access the administration portal. For example, if the URL is https://your-company.workstars.com/admin then your subdomain is “your-company”.

api_key

To generate an API key:

1. Login to your Administrator account (must be Primary Administrator)
2. Click Add-ons and select HR Data Sync
3. Click Learn More
4. Click Sync via API or Console App
5. Click Enable
6. Click the Settings & configuration cog
7. Click generate a new key Key
8. Click Confirm

csv_header

If your CSV file contains a header row, set this to “true”, else it should be set to “false”.

hierarchy_type

If you program is configured for manager managed hierarchy, set this to “manager”. If its set to company managed hierarchy, set this to “company”.

smtp_enabled (optional)

The app can use an SMTP mail server to send emails (errors, etc.). Your IT team can either provide the details of an internal server or you can use an external provider (e.g. Mailgun, Sendgrid, etc.) By default this is disabled, if you want to enable it, set this to “true”.

smtp_host & smtp_port

If you have enabled SMTP email, enter the hostname and port of the server. Your IT team will provide these.

smtp_username & smtp_password

If you have enabled SMTP email, enter the username and password. Your IT team will provide the required login details.

smtp_from_address

Enter the email you want the email to come from. Your IT team will provide this.

smtp_to_address

Enter your email address. If you want to add multiple addresses, you should separate them using a comma.

Field Mapping

The configuration file contains two sections and which one you should edit depends on how your program is configured:

Manager Managed

If your program is configured for a manager managed hierarchy then you should edit the mappings in the “<ManagerManagedCsvColumns>” section of the config file.

<ManagerManagedCsvColumns>
  <columns>
    <column field="EmployeeID" index="0" />
    <column field="FirstName" index="1" />
    <column field="LastName" index="2" />
    <column field="EmailAddress" index="3" />
    <column field="JobTitle" index="4" />
    <column field="IsContractor" index="5" />
    <column field="Department" index="6" />
    <column field="StartDate" index="7" />
    <column field="Country" index="8" />
    <column field="IsManager" index="9" />
  </columns>
</ManagerManagedCsvColumns>

The “index” next to each field represents which column in your CSV it should use. Please note that the first column in the CSV file is “0” and not “1”. If we use the example file in the previous section, the mapping would look like this:

<ManagerManagedCsvColumns>
  <columns>
    <column field="EmployeeID" index="4" />
    <column field="FirstName" index="0" />
    <column field="LastName" index="1" />
    <column field="EmailAddress" index="2" />
    <column field="JobTitle" index="5" />
    <column field="IsContractor" index="9" />
    <column field="Department" index="3" />
    <column field="StartDate" index="6" />
    <column field="Country" index="7" />
    <column field="IsManager" index="8" />
  </columns>
</ManagerManagedCsvColumns>

Company Managed

If your program is configured for a company managed hierarchy then you should edit the mappings in the “<CompanyManagedCsvColumns>” section of the configuration file.

<CompanyManagedCsvColumns>
  <columns>
    <column field="EmployeeID" index="0" />
    <column field="FirstName" index="1" />
    <column field="LastName" index="2" />
    <column field="EmailAddress" index="3" />
    <column field="JobTitle" index="4" />
    <column field="IsContractor" index="5" />
    <column field="Department" index="6" />
    <column field="StartDate" index="7" />
    <column field="Country" index="8" />
    <column field="ReportsTo" index="9" />
  </columns>
</CompanyManagedCsvColumns>

The “index” next to each field represents which column in your CSV it should use. Please note that the first column in the CSV file is “0” and not “1”. If we use the example file in the previous section, the mapping would look like this:

<CompanyManagedCsvColumns>
  <columns>
    <column field="EmployeeID" index="4" />
    <column field="FirstName" index="0" />
    <column field="LastName" index="1" />
    <column field="EmailAddress" index="2" />
    <column field="JobTitle" index="5" />
    <column field="IsContractor" index="9" />
    <column field="Department" index="3" />
    <column field="StartDate" index="6" />
    <column field="Country" index="7" />
    <column field="ReportsTo" index="8" />
  </columns>
</CompanyManagedCsvColumns>

Advanced Settings

Below are some advanced settings that you can use if the data from your HR system is in a non-standard format or doesn’t contain some of the data required.

Defaults

The following fields allow you to set a default value if you cannot provide them:

• Country
• IsContractor
• Is Manager

To set a default, you should not specify an “index” and instead specify a “default” value.

For example, if you want to set the Country field to GB, you should change the “country” field mapping to be:

<column field="Country" default="GB" />

Filters

The following fields allow you to filter the data using a regular expression:

• ReportsTo
• EmployeeID
• JobTitle

To define a regex, you should not specify an “index” and instead specify a “filter” value.

For example, if your “ReportsTo” field contains more than just the managers employee ID e.g. Bob Jones (1234), you would need to extract just the numerical employeeID. To do this we can use “\d+” where “\d” means a digit (a character in the range 0-9), and “+” means 1 or more times (so “\d+” means 1 or more digits):

<column field="ReportsTo" filter="\d+" />

This will return “1234” instead of “Bob Jones (1234)”.

How to run the app

You have 2 choices:

• run the app manually
• run the app automatically

How to run the app manually

This is recommended for testing and if you want to run it manually on an employee's PC.

1. Open the windows command line interface. To do this you can either click the magnifying glass (search) icon in Windows or hold down the windows key and press “S”.
2. In the search box, type “cmd.exe” and press the enter key on your keyboard. Please note that your company security policy may prevent this, please check with your IT Team if you are having issues opening the command line.
3. Make sure you are on your local drive (usually C). Type the following and press the enter key:

C:

3. Change to the folder where the app is installed (by default the app is installed in “C:\WorkstarsSync”). Type the following and press the enter key:

cd C:\WorkstarsSync

4. Run the app (see Supported Functions section). Type the following and press the enter key:

WorkstarsSync.exe <function_name>

How to run the app automatically

This is recommended if you want to run the app on a server.

Once you have tested the file manually you can then implement the following:

• schedule your employee CSV file to be exported to a folder
• schedule the app to run (with the appropriate function) using the above file

Supported Functions

Function Name	Description
about	Show the version of the app
test-connection	Test if you can connect using the api-key
test-email	Test you email settings
validate	Validate your file
upload	Upload your file

Please see the individual function notes below for details:

about

This function returns the version of the app. We recommend updating when a new version of the app is released. See the “Versions” section below.

WorkstarsSync.exe about

test-connection

This function tests to see if you can connect to our servers. It can be used to check that the api-key is correct and that the app can access the internet.

WorkstarsSync.exe test-connection

"Success" will be returned if the connection details are correct.

test-email

This function will send a test email using the smtp settings provided in the config. It is used to check the smtp details provided work.

WorkstarsSync.exe test-email

validate

This function will convert the CSV file provided to XML and validate the XML. It will return a success or it will put an error file in the same location as the CSV.

This should only be used for testing your file during setup.

WorkstarsSync.exe validate "files\employees.csv"

upload

This function will convert the CSV file provided to XML and validate the XML. If it fails validation, it will put an error file in the same location as the CSV.). If the file passes validation, it will upload the file to our servers (you should always check in the administration portal to determine if it has processed successfully or if there are any errors). 

Once you have the correct file format, this is the function you will use on a regular basis (there is no need to run the validate function separately as the upload also validates your file).

WorkstarsSync.exe upload "files\employees.csv"

Troubleshooting

Below are some possible errors and how to resolve them:

I get a blank error file and there are one or more XML files created

This is usually because the console app could not connect to our system. Check the "subdomain" and "api_key" values in your config file contain the correct values. TIP: Use the "test-connection" command to verify them.

You are getting an error about incorrect data but when you look at your file, you cant work out why.

The app validates your data using the rules at the start of this document (for example, the “Is Contractor?” must be either 1, true, yes, y or 0, false, no or n).

Usually, this error is because you have incorrectly mapped your columns in the config file. For example, if you have set the index for the “Is Contractor?” field to 9 but that column contains something else, it will not pass the validation.

You should check that the mappings have been setup correctly in your config file. Please remember that the first column in a CSV is number “0” and not “1” (i.e. index “0” is Column “A” in Excel).

ERROR: “A CSV file should have the same number of columns on every row, please check your file and try again.”

This is telling you that some rows in your file, contain different numbers of columns. This can be caused by several possible issues:

• Check that you dont have the file open in Excel, etc.
• A row actually has more/less columns.
  • Check there aren't any fields that contain a comma (either remove the comma or the field should be surrounded by quotes).
  • If you are using hierarchy, check the row for the employee at the top of your hierarchy (i.e. the field you have mapped to "ReportsTo" should be blank). If that column is the last column in your file, that row should end in a comma.
• There is a blank row on the bottom which you cannot see in Excel. Open the file in Notepad and scroll to the bottom. If there are lots of commas next to each other, then that's a blank row and you can delete it.
• You have opened and saved the file in Excel. Unfortunately, Excel adds a carriage return and this looks like a row with just 1 column. Open the file in Notepad and scroll to the bottom. If there is a blank entry on the bottom, then this is the problem and you should delete it.
• In the config, you have configured it NOT to have a header row but in the file you have used one. Update the config to match what has been sent in the file.

ERROR: “Line: x, Position y: “The element ‘employees’ has invalid child element ‘employee’.””

This is telling you there in an invalid <employee> element in the XML file on line x and at position y. It means there the syntax is incorrect or a sub-element is incorrectly named. Usually, this should not be possible as the console app builds the XML file for you. However, you may see it if you are testing on a demo account with more than 50 employees. If this is the case, reduce the number of your test employees. If you are seeing this error and have less than 50 employees, please contact support.

For more troubleshooting guidance, visit How to view your HR Data Sync files and troubleshoot any issues

Versions

Version	Notes
1.0.2	Fixed a bug which prevented a country default being set if the column was called “Country” Fixed a bug which created invalid XML when there are blank emails (i.e. offline invites enabled) The app now converts employeeID to lowercase automatically
1.0.1	Added “test-connection” command which can be used to check if the server can connect to our server (i.e. it can connect to the internet)
1.0.0	First stable version released
0.0.1	Beta version released