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 programming skills 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 suitable 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 your file export 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 your data
  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
  5. Fix any data issues and re-run the validation
  6. Run the app manually using the ‘upload’ function to check the file uploads and is processed - see How to run the app
  7. Fix any final data issues and re-run the upload
  8. Schedule a task to export your file and run the ‘upload’ function (RECOMMENDED) or have someone do it manually

Download & Installation

Download one of the following files. If your security settings prevent the direct download of .exe files, please choose the .zip file.

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

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

Warning

Due to the sensitive data the application is handling, we highly recommend that you do the following security checks before running the installer. If either fail, please contact support immediately.

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:

  • Right click the installer and select Properties
  • Select the Digital Signatures tab
  • Click the entry in the list and click the Details button
  • You shiould see “The digital signature is OK” at the top
  • Click the View Certificate button
  • The certificate should be issued to “Workstars Global Ltd.” and be issued by “Sectigo RSA Code Signing CA”
  • 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:

certutil -hashfile {file_name} SHA256

For example:

certutil -hashfile WorkstarsSyncInstaller(1.0.0).exe SHA256

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 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

Warning

If you are opening and editing the file in Excel, please be aware that it makes changes to the data that can cause issues e.g. it will change date formats, it will remove leading zero’s from employee numbers, etc.).

Required Data

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

Field Manager Company Notes
Employee ID Y Y This is the employee’s unique ID
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 schemes this indicates who is a manager and can build their own team
Reports To N Y For company managed schemes this is the Employee ID of the person the employee reports to (usually their manager)

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

If you do not have this data in your HR System or you don’t employ any contractors, you don’t need to provide it in your file but you must set a default value in the configuration file (see Advanced Settings section)

Start Date

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

Country

Note

If you do not have this data in your HR System, you don’t need to provide it in your file but you must set a default value in the configuration file (see Advanced Settings section)

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 scheme is configured:

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

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

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 access the site on. For example, if the URL is https://your-company.workstars.com then the subdomain is “your-company”.

api_key

You can generate an API key by logging into the administration portal, clicking “Settings” and then “API”.

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 scheme 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 scheme is configured:

Company Managed

If your scheme 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>

Manager Managed

If your scheme 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>

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

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 you can then entering “cmd.exe”. 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.

  1. Type the following in the box to change to the folder where the app is installed (defaut “C:\WorkstarsSync”)

cd C:\WorkstarsSync

  1. Type the following in the box to run the app (see below for supported functions)

WorkstarsSync.exe <function_name>

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

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. It is usually used for testing you 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 the file passes validation, it will upload the file to our servers for processing. If it fails validation, it will put an error file in the same location as the CSV. This is the function you will use on a regular basis.

WorkstarsSync.exe upload "files\employees.csv"

Troubleshooting

Below are some possible errors and how to resolve 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 called “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:

  • A row actually has more/less columns. This is usually because the field contains a comma and the field is not surrounded by quotes.
  • 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 thats 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 but this should not be possible as the console app builds the XML file for you. However, it is also seen 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.

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