API

GETTING STARTED

Register
bCrypt Encryption
Authentication
Requests
Modules
Response Codes
Sample Workflow
Optional Modules
Terms of Use

 

TimeWellScheduled API Documentation
 
For the most up to date API Documentation in PDF Click HERE. 
 
Overview

The TimeWellScheduled API allows you to call modules with the TimeWellScheduled service that respond in standard XML. Individual modules and their properties are detailed blow.

The API URL is located at https://api.timewellscheduled.com/response.asp

The TimeWellScheduled API isn’t your typical API in the way that it doesn’t rely on different HTTP request methods (GET/PUT/INSERT/DELETE). Instead, we’ve decided to KISS and use only GET HTTP Requests over HTTPS (at this time), and to simply pass the desired method along with the variables for the request itself in a standard, well-formatted URI.

This has a number of advantages and will make your live easier when working with our API as:

  • There is no need to switch between different HTTP request modes in your application
  • You can convert your data straight to URI-formatted text in whatever language you are using
  • Our ‘Method’ names are a bit more intuitive


Register


We are handling all registrations internally. To get started please provide us with:

Upon receiving this information we will setup an key for you, that can be used in the development of your application.

 


bCrypt Encryption


While you wait for your registration to be complete, you may want to also look into the bCrypt irreversible encryption algorithm. TimeWellScheduled utilizes bCrypt to store all passwords, and provide you with employee passwords in this encrypted format. Your application will need to verify passwords with these bCrypt hashes, meaning you will need to bCrypt-hash these on the client-end. To get comparable results, you will need the bCrypt Salt which is unique to each company; we will pass you this information when your application authenticates for the first time.

For more information about bCrypt, and links to the various implementations (including Objective-C, PHP, Python, Perl, .NET, Ruby, and even JavaScript!), please visit: http://codahale.com/how-to-safely-store-a-password/

The staff at TimeWellScheduled strongly believe in the power of bCrypt, and our clients trust in our choice of using this algorithm to prevent reverse-engineering of hashes, and prevent man-in-the-middle attacks of clear-text passwords being transmitted across the network. If bCrypt implementation proves to be difficult, we’re more than happy to help!

 


Authentication


You’ll need to register for an API Key first. Please contact [email protected] for registration and setup information.

Action 0:
Virtually all modules in our API require verification for access. This is the first module your application will call, upon launch. The Verification process purpose is to exchange an API Key for confirmation that your application will be accepted by our servers. Additionally, upon successful exchange, we will provide company information, and a company logo that the company has provided ahead of time, as well as a list of employees authorized to use your application and their data. Also, a bCrypt Salt Hash will be provided, which you can use for password verification processing.

Full details regarding modules can be found in Modules section; for now, bear with us as we discuss the procedure for authentication.

All request are made via HTTPS GET requests, and requires a series of variable and value pairs appended to the API URL. Here is the format of that URL, and we’ll discuss each option below:

 

Request:


 

Response:


Upon successful validation, you will receive in the Message portion of the XML a series of values: a list of employees enclosed within <employees>
tag, as well as a <branding> tag contains the name of hte company, and a logo url as an attribute. Finally, the bcrypt Salt to use for local verification of passwords is provided for this company; this is not to be cached, as it may change at any time; store this temporarily in your client application to use for verification of typed passwords.


Requests


The TimeWellScheduled API allows you to call modules with the TimeWellSchedule service that respond in standard XML.

 

The API URL is located at https://api.timewellscheduled.com/response.asp

 

All requests to the TimeWellScheduled API must be packaged as encoded URI Strings, and appended to the API URL in a well-formed GET HTTP Request Method. Virtually all requests require an API Key and Application ID. There are additional requirements for most API calls, as follows:

Remember that any data passed to the API must be in a URI string, and properly encoded (eg, %20 in place of spaces). Here is an example of how this can look in PHP:

Responses

Upon your application sending a properly-formed request, with an appropriate value for action, the server will return an XML response:

The returned values are explained as follows:


Modules

The following modules are support at this time, and are to be passed in the ‘a’ attribute of each request

ActionModuleDescrition

1 begin This is the “Begin Shift” Module;use this module to allow an employee to record the beginning of their shift.

RETURNS:A custom message waiting for this employee

2 end This is the “End Shift” Module; use this module to allow an emplyee to record the end of their shift. Assumes the employee is not on a break or meal.

RETURNS: A custom message waiting for this employee

3 break This is the “Begin/End Break” Method; use this module to allow an employee to record the beginning or end of their regular paid break. Assumes the employee is not on a meal, and has not Ended their shift. If the employee has already recorded a “Begin/End Break” activity, the server will tak ethem off their break;

RETURNS: A custom message waiting for this employee

5 meal This is the “Begin/End Meal” Module; use this module to allow an employee to record the beginning or end of their regular paid break. Assumes the employee is not on a break, and has not Ended their shift. Acts like “Begin/End Break”
schedule_list schedule_list This is the ‘list schedule’ module; use this module to request an employees schedule. Requires the schedule to be published. Requires a StartDate and EndDate be passed in (ex. 2016-08-01)
role_list role_list This is the “role_list”module, use this module to obtain the active role list.
department_list department_list This is the “department_list” module, use this module to obtain a list of the active departments.
employee_list employee_list This is the “employee_list” module, use this module to obtain the list of active employees
employee_details employee_details This is the “employee_details”, use this module to obtain an employee’s specific details, the eCode corresponding to the employee code is required.
message_list message_list This is the “message_list” module use this module to obtain a specific employee’s unread messages. The eCode corresponding to the employee code is required.
messages_mark_read messages_mark_read This is the “messages_mark_read” module, use to mark a message as read, the
MessageID is required.


Response Codes


At this time, the following response codes are supported, and will be supplied in the ‘success’ return value in any of the module responses.


Sample Workflow


To help you better understand how our API works we’ve provided a brief example of a ‘real world’ workflow of making calls to various modules of the TimeWellScheduled API.

 

The API URL is located at https://api.timewellscheduled.com/response.asp

Step 1:

Your application launches, and sends the first initial request to authenticate/verify:

The server response with XML code provided the Application ID (appid), Company ID (c) and API Key (p) match:

Success is equal to 1, meaning our request was successful. We’ve been given an EventID, and in the message, we’ve been given a XML list of employees to store temporarily, some branding information, and the bCrypt Salt used to hash typed passwords and to compare against.

Step 2:

The first employee punches in for his or her shift to start:

The server responds with XML code, indicating that this employee is on-­‐time, and has a message waiting for them; it also retrieves the photo1.jpg file mentioned in the ‘a’ attribute (uploaded on a separate thread, and placed in a holding area), and attaches it to this event.

The employee would then dismiss this message.

 

Step 3:

The second employee punches in for his or her shift to start:

The server responds:

The employee confirms the message, and the UI is reset.

 

Step 4:

The first employee needs to punch in to begin their meal:

The server responds:

The employee confirms the message, and the UI is reset.

 

Step 5:

The second employee has already successfully punched out for a regular break, and returns, attempting to punch in immediately for lunch:

However, this employee tapped ‘Meal,’ but was already out on break; the server responds:

The employee confirms the message, and attempts to return from break:

The server responds:

The employee can now punch out for their meal.

Step 6:

The first employee punches out to leave their shift for the day:

The server responds:

The employee then confirms their message.

 


Optional Modules


The following are some neat additional (and optional) API’s to hook into

Reason:
A watch – dog event : allow the employee insert additional information at the moment of doing the punch. For example when the employee is late for their punch. If your APP are certificated to handle Whatchdog module, each response from the server contains a value 0, also it will contain a tag, like the one below

    
<response>
<success>0</success>
<ontime>0</ontime>
<eventid>
$2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm
</eventid>
<message>You are 107 minutes late</message>
<watchdog>
  <message>Select a reason.</message>
  <reasons>
    <reason ID="2233">Accident de route</reason>
    <reason ID="153">Car problems</reason>
    <reason ID="157">Computer issues</reason>
    <reason ID="1482">Default reason code</reason>
    <reason ID="159">Finished early</reason>
    <reason ID="154">Not feeling well</reason>
    <reason ID="156">Other (Please explain)</reason>
    <reason ID="1983">Personal emergency</reason>
    <reason ID="2231">Rendez-vous chez le medecin</reason>
    <reason ID="158">Traffic</reason>
    <reason ID="2232">Urgence</reason>
    <reason ID="155">Weather</reason>
   </reasons>
</watchdog>
</response>

    

You should have a watchdog contain a modal window and each set it on a drop-down list , after you have the value that the user select you must generate another call to the API

https://api.timewellscheduled.com/response.asp?c=ABC_123&u=user&p=password &action=1&module=begin&appid=$2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm&Year=2016&Month=4&Day=28&Hour=14&Minute=47&Second=56&reason=2223

The server to this answer must return a <ontime> in 1.

Attachment module a:

This variable will allow you to send the name of a file that is related to the registration of the punch, we use this to send the name of the photo that was taken at the momento of making the punch.
GeoLocation module lat y lng:

If you are collecting GPS location data at the time of the Punch, you can pass this information in each HTTPS GET request ( the latitude value as long, and longitude value as a long).

https://api.timewellscheduled.com/response.asp?c=ABC_123&action=2&module=end&appid=$2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm&&u=kk0166&p=password&Hour=15&Minute=15&Second=18&Month=04&Day=28&Year=2016&a=13222F23-C76A-7781-0C12-0293E3B34398.jpg&lat=+42.997450&lng=7444957

Access restriction:

The application has 2 types of Access

1. IP: you can register your IP in TWS, if it is not register it will display this message

<response>
  <success>0</success> 
  <ontime>1</ontime>
  <eventid>
    $2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm
  </eventid>
  <message>
     Failure to authenticate. Password to access the application is incorrect Or IP is not Valid - 200.58.74.137
  </message>
</response>
    

2. Password administrator (pws): this is the encrypted password from an administrator.


https://api.timewellscheduled.com/response.asp?c=ABC_123&u=5502&p=$2a$05$wzjnhnHZh3teE4AZfHGDY./1Sni1dQTK2VmPgugIth/xY3dfz5NUO&action=1&module=begin&appid=$2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm&Year=2016&Month=4&Day=28&Hour=14&Minute=47&Second=56&pws=passwordadmin

 

Modulo schedule_list 


https://api.timewellscheduled.com/response.asp?c=ABC_123&eCode=256&module=schedule_list&appid=$2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm&StartDate=2016-06-01&EndDate=2016-06-30 
  • Use the following fortmat for the date yyyy-mm-dd
  • The employee code, company code and appid are required.
<response>
   <success>1</success>
   <ontime>1</ontime>
   <eventid>
     $2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm
   </eventid>
   <schedules>
    <schedule date="2016-6-1">
      <time>7:00 AM-2:00 PM</time>
      <type>Regular Hours</type>
      <deptName>Office</deptName>
      <roleBelong>Cash Balancing</roleBelong>
      <comment></comment>
    </schedule>
    <schedule date="2016-6-2">
      <time>7:00 AM-2:00 PM</time>
      <type>Regular Hours</type>
      <deptName>Office</deptName>
      <roleBelong>Cash Balancing</roleBelong>
      <comment></comment>
    </schedule>
  </schedules>
</response>
    

Role_list module

  • It will only list active roles
  • The company code and appid are required.
https://api.timewellscheduled.com/response.asp?c= ABC_123&module=role_list&appid=$2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm
<response>
<success>1</success>
<ontime>1</ontime>
<eventid>
   $2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm
</eventid>
<roles>
<role roleID="15">
  <roleName>Business Owner</roleName>
  <roleLevel>1</roleLevel>
</role>
<role roleID="2">
  <roleName>Store Manager</roleName>
  <roleLevel>2</roleLevel>
</role>
</roles>
</response>

 

Department_list module

  • It will only list active departments
  • T It requires the company code and appid.

https://api.timewellscheduled.com/response.asp??c= ABC_123&module=department_list&appid=$2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm
<response>
  <success>1</success>
  <ontime>1</ontime>
  <eventid>
    $2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm
  </eventid>
  <departments>
    <department departmentID="2002">
      <departmentName>Adjusting</departmentName>
      <departmentCode>18</departmentCode>
      <departmentCodePrefix></departmentCodePrefix>
      <departmentCodeSuffix></departmentCodeSuffix>
    </department>
    <department departmentID="1">
      <departmentName>Automotive Parts</departmentName>
      <departmentCode>2</departmentCode>
      <departmentCodePrefix></departmentCodePrefix>
      <departmentCodeSuffix></departmentCodeSuffix>
    </department>
  </departments>
</response>

Employee_list module


https://api.timewellscheduled.com/response.asp??c= ABC_123&module=employee_list&appid=$2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm
  • It will only list employees that are active on TWS
  • The company code and appid are required
<response>
  <success>1</success>
  <ontime>1</ontime>
  <eventid>
    $2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm
  </eventid>
  <employees>
    <employee>
      <name>Abed</name>
      <lastName>Mart</lastName>
      <employeeCode>394</employeeCode>
      <payrollType>Hourly</payrollType>
      <internalStatusName>No longer employed</internalStatusName>
      <street>119 Moore Avenue</street>
      <postalCode>N5H 2Z8</postalCode>
      <birthday>1995-02-08</birthday>
      <hireDate>2013-03-25</hireDate>
      <terminationDate></terminationDate>
      <phone1>000-000-0000</phone1>
      <phone2>000-000-0000</phone2>
    </employee>
    <employee>
      <name>Adam</name>
      <lastName>Thomson</lastName>
      <employeeCode>371</employeeCode>
      <payrollType>Hourly</payrollType>
      <internalStatusName>No longer employed</internalStatusName>
      <street>49300 Lyons Line, RR #2</street>
      <postalCode>N0L 2J0</postalCode>
      <birthday>1994-02-22</birthday>
      <hireDate>2011-03-02</hireDate>
      <terminationDate>2015-08-28 5:37:49 PM</terminationDate>
      <phone1>000-000-0000</phone1>
      <phone2>000-000-0000</phone2>
    </employee>
  </employees>
</response>

Employee_details module


https://api.timewellscheduled.com/response.asp??c= ABC_123&module=employee_details&eCode=2&appid=$2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm
  • Employee code is required
  • Company code and appid are required
<response>
  <success>1</success>
  <ontime>1</ontime>
  <eventid>
    $2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm
  </eventid>
  <employee>
    <name>Maureen</name>
    <lastName>Martin</lastName>
    <employeeCode>2</employeeCode>
    <payrollType>Salaried</payrollType>
    <internalStatusName>Active</internalStatusName>
    <street>270 Caverly Road</street>
    <postalCode>N5H 2V3</postalCode>
    <birthday>2013-08-30</birthday>
    <hireDate>1988-08-10</hireDate>
    <terminationDate></terminationDate>
    <phone1>000-000-0000</phone1>
    <phone2></phone2>
  </employee>
</response>

Message_list module


https://api.timewellscheduled.com/response.asp??c= ABC_123&module=message_list&eCode=51&appid=$2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm
  • The employee code is required
  • Company code and appid are required
<response>
  <success>1</success>
  <ontime>1</ontime>
  <eventid>
    $2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm
  </eventid>
  <messages>
    <message dateTime="2015-08-20 4:45:02 PM" MessageID="1111675">
      <subject>
        LIMITED EDITION 
      </subject>
      <body>
        TO: Please see the boards for the details of the auction. You can pick up a ballot from Shirley beginning Monday, August 24th. The winning bid will be donated to Jump Start Charity. The hat can be seen by request.
      </body>
    </message>
  </messages>
</response>

 

Messages_mark_read module

  • MessageID is required
  • Coompany code and appid are required

https://api.timewellscheduled.com/response.asp??c= ABC_123&module=messages_mark_read&MessageID=xxx&appid=$2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm
<response>
<success>1</success>
<ontime>1</ontime>
<eventid>
$2a$12$x4yLqN1yWaNfg2qbzw6GDen9g8C/IbH/cEvEfzsSGdysYyjIAhqwm
</eventid>
<message>Your action has been recorded successfully</message>
</response>


Terms of Use


TBD