Somroli’s Attendance Management Solutions can be easily integrated with any enterprise business applications using our proprietary open standard XML interfaces. Application Programming Interfaces(API) with our centralized server is available for push and pull messaging. We are able to provide end to end integrated solutions as well as provide integration guides for enterprises which want to design and implement integration in-house.
Somroli Systems Server(S3) is a middle-ware that can be used with any ERP and 3rd party data capture terminals (Time clocks).

Introduction

This document details the usage of APIs available for integration with S3. The client programs connecting to a web service can read the WSDL to determine what functions are available on the S3. The client can then use SOAP to actually call any of the functions listed in the WSDL.This is a living document. We are constantly enhancing and adding more API as we deem fit for use by broader client requirements. We will always ensure that APIs are ackward compatible, in other words newer versions will always be compatible with older versions of integration mplementations.This is not the final list of APIs, if your firm has specific needs that are unique to your organization or industry, Simple IT Solutions Inc, will be able to provide specific API based on your organization
requirements. A written request must be submitted to Simple IT Solutions Inc for any custom requirements with details of input and output parameters required. The API signature will be designed and implemented at the is cretion of Simple IT Solutions Inc. Though this manual refers to PaaS solution, same manual is applicable for client hosted environment as well.

2.1 Version Information

S3 supports SOAP protocol version 1.0 and all later versions.

2.2 Overview

2.2.1 S3 PaaS Solution

This is a suite of services available in S3.

By integrating to S3 using S3 with either client hosted or PaaS Solution, customer can manage their employee attendance registered in the device as well as perform employee setup as well device configurations. Extended APIs are also available to perform various setups including organization roles, locations and other attendance calculation rules.

Authentication method is http_base_auth, client applications can leverage both HTTP and HTTPS protocols for authentication. PaaS corporate account login & Password has to be passed through SOAP headers. SOAP has an API to set the user ID/password for HTTP basic authentication.

The APIs available in S3 can be called from any application with communication in SOAP
protocol.

pic1

2.3 Related Documents

The documents listed below are provided to help our customer to perform specific integrations to support S3.
o WSDL URL –

3 Document Structure Guideline

3.1 Definitions

Understanding of the following terms will facilitate a better grasp if the information presented in this document:

S3
Somroli Systems Server

PaaS
Platform-as-a-Service

SOAP
SOAP is remote procedure calls transported via HTTP.
SOAP enables client applications to easily connect to remote services and invoke remote methods.

WSDL
A client program connecting to a web service can read the WSDL to
determine what functions are available on the server.
The client can then use SOAP to actually call one of the functions listed in the WSDL.3.2 Formats

3.2 Formats

Rest of the document will explain the below APIs, available in S3. There are other APIs which are not listed here in this document, can be provided upon integrator’s needs as well.

API Names Functions
s3_paas_add_location The Function is to add a new location.
s3_paas_delete_location The Function is to delete an existing location.
s3_paas_get_timeclockslist The API is used to get the biometric device list.
s3_paas_set_device_configuration This API is used to configure the biometric device.
s3_paas_delete_device This is used to delete an existing device.
s3_paas_get_device_configuration This is used for getting the biometric device information.
s3_paas_delete_device This is used to delete an existing device.
s3_paas_get_device_configuration This is used for getting the biometric device information.
s3_paas_get_attendance_logs This API is used for getting the attendance logs from biometric device for a specific date range and customer.
s3_pass_get_processed_attendance This API is used to get the processed attendance data registered in biometric device.
s3_paas_upload_employee_info This API is used to create the employees in the biometric devices as well as GTW system.
s3_paas_get_employee_info This is used for getting the Employee information.
s3_paas_update_employee_info The function is to update the employee in biometric device as well as GTW.
s3_paas_delete_employee This is used to delete an employee.
s3_device_offline_att_log_process Offline upload can be done using this API.
s3_pass_get_report Work hour details, Work Hour Summary, Check In/Out Exceptions reports are accessible through this API.
s3_paas_get_workhours_export PrimePay, Quickbooks can be exported using this API.

The format for API documentation will be

API Name

Description:

Input:

Input Parameters Description

Output:

Output Parameters Description
Note:

Clientconfig which is Customer ID in the GTW is common input for all the APIs

4 s3_paas_add_location:

4.1 Description:

The Function is to add a new location.

4.2 Input:

Input Parameters Description
LOCATION_ID ID the client system for the Site
LOCATION_NAME Name for the Site
LOCATION_CITY City of the site
LOCATION_COUNTRY Country of the site
LOCATION_STATE State of the site
LOCATION_ZIP Zip of the site
LOCATION_ADDRESS Address of the site
LOCATION_PHONE Phone of the site contact (if any)
LOCATION_FAX Fax of the site (if any)
LOCATION_EMAIL Email of the site contact (if any)
TIMEZONE Time zone of the site
FIRST DAY OF THE WEEK First day of the week of the site
EMPLOYEE OVERTIME CRITERIA Criteria for over time calculation for the employee belongs to the site
URL Employee clock in/out link

4.3 Output:

Output Parameters Description
Result 1 means success, 0 means error
Message contains the message(success or error)

5 s3_paas_delete_location

5.1 Description:

The Function is to delete an existing location.

5.2 Input:

Input Parameters Description
CUSTOMER_ID Customer Id in GTW
LOCATION_ID Location id in the client system to be deleted

5.3 Output:

Output Parameters Description
Result 1 means success, 0 means error
Message contains the message(success or error)

6 s3_paas_get_timeclockslist

6.1 Description:

The API is used to get the active biometric device list against a customer id.

6.2 Input:

Input Parameters Description
CUSTOMER_ID Customer Id in GTW

6.3 Output:

Output Parameters Description
TIMECLOCK_DEVICE_ID ID of the biometric device
TIMECLOCK_LAN_IP IP address of the device
TIMECLOCK_NAME Name of the device
TIMECLOCK_PASSWORD Password
TIMECLOCK_ACCOUNT_STATUS Account Status
TIMECLOCK_READ_STATUS Read status
US_USER_SITE_PROFILE_ID Site id where the device is installed
UPDATED Last updated date
USER_SITE_NAME Name of the site where the device is installed
USER_SITE_CITY City of the site where the device is installed
TIMECLOCK_SERIAL_NUMBER Serial Number of the Device
TIMECLOCK_MAC_ADDRESS Mac Address of the Device
LAST_DATA_XFER_TIMESTAMP Mac Address of the Device
TIME_SINCE_LAST_TXN Since when the last transaction has happened

7 s3_paas_set_device_configuration

7.1 Description:

This API is used to configure the biometric device.

7.2 Input:

Input Parameters Description
TIME_CLOCK_ID IF TIME_CLOCK_ID IS BLANK, create a new clock TIME_CLOCK_ID
TIME_CLOCK_NAME Name of the device
TIME_CLOCK_MAC Mac Address of the Device
TIME_CLOCK_SERIAL Serial Number of the Device
TIME_CLOCK_IP IP address of the device
TIME_CLOCK_LOCATION_ID ID the client system for the Site
TIME_CLOCK_LOCATION_NAME Name for the Site
TIME_CLOCK_LOCATION_CITY City of the site
TIME_CLOCK_LOCATION_COUNTRY Country of the site
TIME_CLOCK_LOCATION_STATE State of the site
TIME_CLOCK_LOCATION_ZIP Zip of the site
TIME_CLOCK_LOCATION_ADDRESS Address of the site
TIME_CLOCK_LOCATION_PHONE Phone of the site contact (if any)
TIME_CLOCK_LOCATION_FAX Fax of the site (if any)

7.3 Output:

Output Parameters Description
Result 1 means success, 0 means error
Message contains the message(success or error)

8 s3_paas_delete_device

8.1 Description:

This is used to delete an existing device.

8.2 Input:

Input Parameters Description
CUSTOMER ID Customer Id in GTW
DEVICE ID ID of the biometric device

8.3 Output:

Output Parameters Description
Result 1 means success, 0 means error
Message contains the message(success or error)

9 s3_paas_get_device_configuration

9.1 Description:

This is used for getting the biometric device information.

9.2 Input:

Input Parameters Description
CUSTOMER ID Customer Id in GTW
DEVICE ID ID of the biometric device

9.3 Output:

Output Parameters Description
TIME_CLOCK_ID ID of the biometric device
TIME_CLOCK_NAME Name of the device
TIME_CLOCK_MAC Mac Address of the Device
TIME_CLOCK_SERIAL Serial Number of the Device
TIME_CLOCK_IP IP address of the device
TIME_CLOCK_LOCATION_ID ID the client system for the Site
TIME_CLOCK_LOCATION_NAME Name for the Site
TIME_CLOCK_LOCATION_CITY City of the site
TIME_CLOCK_LOCATION_COUNTRY Country of the site
TIME_CLOCK_LOCATION_STATE State of the site
TIME_CLOCK_LOCATION_ZIP Zip of the site
TIME_CLOCK_LOCATION_ADDRESS Address of the site
TIME_CLOCK_LOCATION_PHONE Phone of the site contact (if any)
TIME_CLOCK_LOCATION_FAX Fax of the site (if any)

10 s3_paas_get_attendance_logs

10.1 Description:

This API is used for getting the attendance logs from biometric device for a specific daterange and customer.

10.2 Input:

Input Parameters Description
Start Date Timestamp Start date with timestamp to get the attendance from that time
End Date Timestamp End date with timestamp to get the attendance until that time

10.3 Output:

Output Parameters Description
EMPLOYEE_FRIST_NAME First Name of the employee
EMPLOYEE_LAST_NAME Last Name of the employee
PIN PIN set in the device for the employee
EMPLOYEE_ID Employee ID in the client system
DATE_TIME Time stamp of the attendance registered
STATUS_CODE Status of the completion
WORK_CODE Work Code whether it’s a in/out
VERIFICATION_METHOD_CODE To know whether it is verified or not
LOCATION_ID Location where the attendance got registered

11 s3_pass_get_processed_attendance

11.1 Description:

This API is used to get the processed attendance data registered in biometric device.

11.2 Input:

Input Parameters Description
Start Date Timestamp Start date with timestamp to get the attendance from that time
End Date Timestamp End date with timestamp to get the attendance until that time

11.3 Output:

Output Parameters Description
EMPLOYEE_FRIST_NAME First Name of the employee
EMPLOYEE_ID Employee ID in the client system
SHIFT_COMPLETE_FLAG Flag to know whether the shift is completed or not
EMPLOYEE_LAST_NAME Last Name of the employee
PIN PIN set in the device for the employee
DATE Time stamp of the attendance registered
START_TIME Start date with timestamp to get the attendance from that time
END_TIME End date with timestamp to get the attendance until that time
WORK_CODE Work Code whether it’s a in/out
CLOCK_IN_TYPE Whether it is from clock in or not
CLOCK_OUT_TYPE Whether it is from clock out or not
LOCATION_ID Location where the attendance got registered

12 s3_paas_upload_employee_info

12.1 Description:

This API is used to create the employees in the biometric devices as well as GTW system.

12.2 Input:

Input Parameters Description
LOCATION_ID Client system used location_id, if location_id is null or blank; employee will be created at all the location biometric devices.
EMPLOYEE_ID Employee ID in the client system
EMPLOYEE_FIRST_NAME First Name of the employee
EMPLOYEE_MIDDLE_NAME Middle Name of the employee
EMPLOYEE_LAST_NAME Last Name of the employee
EMPLOYEE_ROLE Role in the organization
TIMECLOCK_PIN PIN set in the device for the employee
TIMECLOCK_PASSWORD Password
TIMECLOCK_CARD Card
TIMECLOCK_PRIVILEGE Privilege
EMAIL Email of the employee
PHONE Contact number of the employee

12.3 Output:

Output Parameters Description
Result 1 means success, 0 means error
Message contains the message(success or error)

13 s3_paas_get_employee_info

13.1 Description:

This is used for getting the Employee information.

13.2 Input:

Input Parameters Description
CUSTOMER_ID Customer Id in GTW
EMPLOYEE_ID Employee ID in the client system

13.3 Output:

Output Parameters Description
Employee Information All the attributes of the employee
Result 1 means success, 0 means error
Message contains the message(success or error)

14 s3_paas_update_employee_info

14.1 Description:

The API is to update the employee information in biometric device as well as GTW.

14.2 Input:

Input Parameters Description
CUSTOMER_ID Customer Id in GTW
EMPLOYEE_ID Employee ID in the client system
Employee Information All the attributes of the employee

14.3 Output:

Output Parameters Description
Result 1 means success, 0 means error
Message contains the message(success or error)

15 s3_paas_delete_employee

15.1 Description:

This is used to delete an employee.

15.2 Input:

Input Parameters Description
CUSTOMER_ID Customer Id in GTW
EMPLOYEE_ID Employee ID in the client system

15.3 Output:

Output Parameters Description
Result 1 means success, 0 means error
Message contains the message(success or error)

16 s3_device_offline_att_log_processs

16.1 Description:

Offline upload can be done using this API.

16.2 Input:

Input Parameters Description
All the attributes in the upload Excel To be provided on request

16.3 Output:

Output Parameters Description
Result 1 means success, 0 means error
Message contains the message(success or error)

17 s3_pass_get_report

17.1 Description:

Work hour details, Work Hour Summary, Check In/Out Exceptions reports are accessible
through this API.

17.2 Input:

Input Parameters Description
REPORT NAME Name of the report
LOCATION_ID Location Id for which the report can be generated (if required to generate thee report)
EMPLOYEE_ID Employee Id for which the report can be generated (if required to generate thee report)
START_DATE Start date to get the data from that time
END_DATE End date to get the data until that time

17.3 Output:

Output Parameters Description
Report output Based on the report name passed on the API.

18 s3_paas_get_workhours_export

18.1 Description:

PrimePay, Quickbooks, ADP can be exported using this API.

18.2 Input:

Input Parameters Description
Export template Name PrimePay, Quickbooks, ADP etc

18.3 Output:

Output Parameters Description
Export output Based on the export template name passed on the API.

19 Appendix

19.1 Appendix A – Acronyms

Acronyms Description
SOAP Simple Object Access Protocol
WSDL Web Services Description Language

19.2 Appendix B – SOAP Architecture

192

For more details and for a test account for integration with cloud enabled biometric time clocks, please click here to contact us.