PaySpace API

1. Import payroll companies.
2. Import payroll company groups.
3. Import or update payroll employees Information.
4. Import pay run period setup in PaySpace.
5. Generate payroll export hours.
6. Store history of the exported hours to payroll with result and identification codes.
7. API Logs
8. Application Service Options

Run the API application by clicking on the Eco PaySpace API shortcut on the desktop or running the application called PaySpaceAPI32 or PaySpaceAPIMs.

1. Select the Settings - PaySpace Tab on the Eco Time PaySpace API Client :

   

   1. API Scope: Leave the default as api.full_access.
   2. Receive Format: The receive format is json and for information purposes only.
   3. Working Company ID: The current selected company's employee payroll hours will be exported to PaySpace. This is a lookup field. Most customer have one in PaySpace. The companies table is populated when the Authentication API is run.
   4. Payroll Period: The current selected payroll period for which employee payroll hours will be exported to PaySpace. This is a lookup field. The Pay Runs table is populated when the Pay Runs API is run.
   5. Stop timed events: This stops time based and web initiated (manual) events. Typically, useful when doing fault finding or analysing data on the client response screen. The generate payroll hours and upload payroll hours is always a manual event, requiring user input via the web interface or desktop application.
   6. A web interface option is available. More information can be found here.
       
2. Select the Settings - API Tab on the Eco Time PaySpace API Client

   

   1. Client API Type: This setting defaults to "PaySpace". and cannot be changed.
   2. Client API Mode: The Production option sets the api to interface with the customer's live PaySpace data. The QAS option sets the api to interface with the customer's test PaySpace data. Please note, each mode has its own settings.
   3. Client API Status: The two options are Enabled or Disabled. The setting has to be "Enabled" to make the PaySpace options avilable in Eco Time's Web Browse menu.
   4. Version Number: This is the API version and cannot be changed,
   5. Log History Records: The log history will be truncated at this number of records (default 2000).
   6. Employee Identifier: Set to identify if the employees in PaySpace are identified by Eco Time's employee number or payroll number. 
   7. Last Leave Time Stamp: The unique time stamp of the last Eco Time leave record uploaded to PaySpace.
   
   
3. Select the Settings - Syncronise Tab on the Eco Time PaySpace API Client

   

   1. Last Sync Date: The last date all companies, frequencies, pay runs and employees were synced.
   2. Last Sync Time: The last time all companies, frequencies, pay runs and employees were synced.
   3. 1st Sync Time: The 1st time of day all companies, frequencies, pay runs and employees will be synced.
   4. 2nd Sync Time: The 2nd time of day all companies, frequencies, pay runs and employees will be synced.
   5. Purge Unverified Employees after (Days) : Employees in the list, which were not found in the PaySpace system, will be removed after this number of days.
      
4. Select the Settings - Profiles Tab on the Eco Time PaySpace API Client :

   

   

   1. Profiles can be assigned to an API company, allowing different connection strings to be used. If a specific profile is not assigned to a company, the default profile will automatically be used.
   2. Server: The API server URL or IP address and port number as supplied by the client. The current default is the current PaySpace standard.
   3. Authentication Server: The API server URL or IP address and port number as supplied by PaySpace. The current default is the current PaySpace standard.
   4. Client Code: The client code supplied and generated in the customer's PaySpace system.
   5. Client Secret: The client secret supplied and generated in the customer's PaySpace system.
   6. Authorization Key: The Authorization key can be used in placed of a company code and secret.
Run the API for the first time
1. After the API Client has been configured, run the application and select the Authentication tab.

   

2. A web interface option is available. More information can be found here.

3. Please Note that the "Stop timed events" check box is enabled by default on a new API installation. There is no point running timed events until the configuration has been completed.

4. Select the API button on the bottom right. This will open the API Client window.

   

5. Now Press the Post (POST) button
6. The request window is now populated with text.

   

7. To verify the connection, select the response tab.

   

8. If the response is very short, then there are the following possible errors:

   1. Server connection cannot be opened: The PaySpace server connection details are incorrect or a firewall is blocking the connection.
   2. 403 Unauthorized: The API operator does not have privilege to view the monitored items.
   3. 400 Bad Request: The response at the bottom will indicate {"error":"invalid_client"} which means cleintid or client secret is wrong.
9. The features to the API methods which are available to the API operator are controlled by the PaySpace user privileges. Eco Time needs the following API methods for integration:
   1. Companies and Company Groups
   2. Frequencies
   3. Component Codes
   4. PayRuns
   5. Employees
   6. EditPaySlip
10. The "Do Not Process Reponse" disables any results processing. No tables will be populated. This is typically used for fault finding and in cases where you want to inspect the request packet and result packet.
11. Once you have established and tested that the PaySpace API Client is successfully communicating with the PaySpace API Server, the PaySpace API Client must be loaded with the API information in the following sequence.
    1. Companies and Company Groups. The authentication API populates both.

       

    2. Update the company information and features which displays the following update form.

       

    3. Set the company export and import features now.
    4. NB!! - The Working Company ID on the Settings - PaySpace Tab must now be set.
    5. Employee group: The Eco Time employee group for this frequency / payroll roll rule. Only the employees' times in this group will be uploaded to payroll, firstly filtered by the company employee group and then by this employee group. 
    6. Profile ID: Profiles can be assigned to an API company, allowing different connection strings to be used. If a specific profile is not assigned to a company, the default profile will automatically be used. 
    7. Frequencies are for reference purposes only, but they are required for the API upload of the payroll export.

       

    8. A web interface option is available. More information can be found here.
    9. Updating the frequencies displays the following update form:

       

       1. Company ID: The company ID populated by the API (read only).
       2. ID: The GL code as populated by the API (read only).
       3. Description: The GL code description as populated by the API (read only).
       4. Frequency: The frequency description  populated by the API (read only).
       5. Employee group: The Eco Time employee group for this frequence / payroll roll rule. Only the employees' times in this group will be uploaded to payroll, firstly filtered by the company employee group and then by this employee group. 
       6. Setting the employee group at the company level will limit the API's employee import and verification to this specific Eco Time group. This is useful in cases where a company has staff, such as executives, recorded in Eco Time, but they do not use time and attendance clocks. In this scenario, you can create and assign an employee group called for example "Time and Attendance" to the applicable employees. By updating the API's company employee group to this, executives will be excluded from the API processing .
       7. A web interface option is available. More information can be found here.
    10. Component Codes are for reference purposes only. Although it is important that the frequency of the component codes being exported must be the same as the Pay Runs' frequency.

        

    11. Input Type Codes are for reference purposes only. It is important that the correct of input code description must be assigned to the payroll export settings. The input type codes will be exported with each component code and will be visible in the export hours browse.

        

    12. NB!! - The Pay Runs must now be assigned an Eco Time payroll date. How to do this can be found here.
    13. NB!! - The Pay Periods on the Settings - PaySpace Tab must now be set.
12. Updating a company's employee group:

    
    Select the change button on the companies browse opens the companies update form above.

    1. Status: Enables or disabled the company, which disabled all API calls to the PaySpace server for the disabled company.
    2. ID: Internal record number identifier. For reference purposes only and not updatable.
    3. Company ID: Company Identifier. This field is automatically populated by the API, but can be edited to match the General Ledger setup ID. This value is also used when filtering the employees browse when displaying employees for the company.
    4. Employee group: The Eco Time employee group for this company. Only the employees' times in this group will be uploaded to payroll. 
    5. Profile ID: Profiles can be assigned to an API company, allowing different connection strings to be used. If a specific profile is not assigned to a company, the default profile will automatically be used.
    6. API features: The API features below can be enabled or disabled: 
       1. Note: When features are disabled, the relevant tabs and options will not be visible.
       2. Export Payroll: Enables the export of payroll hours to PaySpace.
       3. Import Employees: Enables the import of employees from PaySpace.
       4. Export Employees: Enables the export of employees to PaySpace.
       5. Import Leave: Enables the import of leave from PaySpace.
       6. Export Leave: Enables the export of leave to PaySpace.
       7. Allow automatic import / export: When enabled, the respective API option will automatically be processed during the sync schedule. When the respective API option is disabled, the applicable API processed must be manually initiated by the user.
    7. Updating a company's export settings:

       
       

       1. Override Export Settings: When enabled, the Export settings Tabs will override the payroll export codes and settings configured in Eco Time. This allows for different export settings for different payroll companies at one site.
       2. Input Codes: The default input code description for component codes are hours. These fields can be changed, without having to enable the Override Export Setting. The available input code descriptions can be seen here.
    8. Payroll Names:
       

       

       Allows users to configure an Eco Time payroll leave type based on a combination of the imported Leave Bucket, Leave Type, and Leave Reason values's imported leave records, the specified action and leave code will be applied to the matching records during the current import.
       By default, the leave import will lookup the Eco Time leave type's payroll name, if it the leave import does not find a matching Payroll name rule.
    9. Update Payroll Names:
       

       

       1. Company ID: the payroll name rule can be limited to a Company ID or zero for all Companies.
       2. Eco Leave Code: Eco Eco Time Leave Type Code to be assigned to the imported leave record which mathes the rule.
       3. Leave Bucket: The full leave bucket name to match the imported leave record's leave bucket description (PaySpace's LeaveBucket field).
       4. Leave Type: The full leave type name to match the imported leave record's leave description (PaySpace's LeaveType field).
       5. Leave Reason: The keyword to be found in the imported leave record's leave reason. The search is case insensitive (PaySpace's LeaveReason field)
       6. The rule allocation operates based on the values entered in the Leave Bucket, Leave Type, and Leave Reason fields. If a field is left blank, it is ignored in the leave code allocation rule.
       7. For example, if both Leave Bucket and Leave Type have values entered, the imported record must match both values for the leave code to be allocated to that record. Values evaluated as case-insensitive.
       8. The Leave Reason field is a case-insensitive search. It can contain a keyword or words. If the keyword is found within the imported leave reason, the rule will be considered a match and applied accordingly.
Setup the API for Eco Time integration
1. Start by populating the following lists in order by pressing the API button on the respective tabs:
   1. Employees- Get Employees: The API button brings up the following popup menu:

      

      Select the "Get Employees" option by clicking on this item.

      
      The api employee table contains all the captured employees on the PaySpace system
      The following api employees table fields will be populated

      1. ID: Internal PaySpace Employee ID code
      2. Employee Number: Employee number captured in PaySpace.
         1. This field is used to match the Eco Time employee number and if a match is found, the Eco Time fields will be populated.
         2. If an Emp Number is not imported, no matching attempt will be made.
         3. If an Emp Number is imported, the corresponding Eco Time details will be populated in the api employee table:
            1. Eco Emp Number
            2. Eco Emp First Name
            3. Eco Emp Last Name
         4. If an Emp Number is imported, the API validates the employee surname and employee number.
            1. If employee name and surname do match, an image will appear next to the employee.
            2. If and Eco Time employee is not found in PaySpace, an error image will appear next to the employee.
            3. If employee surname does not match, an error image will appear next to the employee.
            4. The AP tries to match first names. If the first names do not match, the API tries to resolve initials or initials in combination with first names. But if this fails a warning image will appear next to theEmployee.
            5. You can mark the match indicator (see next paragraph). An exempted employee will display the exempted image .
            6. You can override the employee match indicator.
      3. firtName: Employee first name captured in PaySpace.
      4. lastName: Employee last name captured in PaySpace.
      5. Gender: Gender of employee captured in PaySpace.
      6. ID Number: Employee ID or Passport number.
      7. Company ID: Company ID this employee is allocated to.
      8. Company Rule ID: Company Rule ID this employee is allocated to. Optional and is not always set.
      9. Company Rule Display: Company Rule Description this employee is allocated to.
      10. Eco Emp Number: Eco Time employee number matched with PaySpace.
      11. Eco First Name: Eco Time employee firstname matched with PaySpace.
      12. Eco Last Name: Eco Time employee last name matched with PaySpace.
      13. Imported into Eco Time: Status and date details when this employee was imported into Eco Time.
      14. Updated in Eco Time: Status and date details when this employee was updated in Eco Time after being imported.
      15. Verified Date: Date verified between API Employee's and PaySpace. If the verified date is older than today's date, then that employee does not exist in PaySpace anymore.
      16. Import Date: Date added to the API Employee's table.
      17. Show All Employees: When this option is not selected, only employees who are part of the working company's employee group will be displayed. Additionally, employees with a "No Match" error will also be displayed if their Company ID matches the Company ID of the working company.
      18. A web interface option is available. More information can be found here.
           
   2. Updating an employee's matching status:

      
      Select the change button on the Employees browse opened the employe update form above.
      
      The user can override the employee's match status. Select Exempt if you will not export this employees hours to payroll and do not require a match to be performed in the future for this employee. Select OK to save your changes. Note: Not in Payroll cannot be set to exempt and must be excluded from the export with filter groups.
      
      A web interface option is available. More information can be found here.

   3. Pay Runs

      
      The api Pay Runs table contains all the payroll periods setup in PaySpace.
      The following apipayrollruns table fields will be populated

      1. Description: Payroll Period Description.
      2. Is Main Run: For Eco Time reference, but PaySpace internal use only.
      3. Pay Hours Date: This field must be updated by changing the record and entering Eco Time's corresponding payroll hours date for the payroll run. NB!!. This is a prerequisite in order to generate payroll hours and upload these to PaySpace.
      4. PayDate: For Eco Time reference, but PaySpace internal use only.
      5. Period Start Date: For Eco Time reference, but PaySpace internal use only.
      6. Period End Date: For Eco Time reference, but PaySpace internal use only.
      7. RunStatus: For Eco Time reference, but PaySpace internal use only.
      8. Run Type: For Eco Time reference, but PaySpace internal use only.
      9. Value: For Eco Time reference, but PaySpace internal use only.
      10. Frequency: For Eco Time reference, but PaySpace internal use only.
      11. A web interface option is available. More information can be found here.
           
   4. Updating a payrun record with an Eco Time Payroll date:

      
      Select the change button on the companies browse opens the update companies form above.
      
      The user MUST assign an Eco Time payroll hours date to a PayRun record. The PaySpace API uses this date to generate a payroll export hours and display history for the selected payroll run period. If this date is NOT SET, no hours will be generated or uploaded.
      
      A web interface option is available. More information can be found here.

Generating the Export and Uploading Payroll Hours
1. Payroll Export:

   
   The API Client will generate the payroll hours to be uploaded by selecting the Generate Export button.
   The export is generated form Eco Time's payroll hours for the selected pay run's payroll date.
   The Generate Export button can be used multiple times as it will clear the last generated export and recalculate the export from EcoTiem's current payroll hours.
   Select the API button to upload the Export Hours to PaySpace.

   1. Payroll Hours: This is Eco Time's payroll hours date as setup in the Payroll Period (Pay Run) current selected.
   2. Request ID: An internal incremental rerefernce ID created by Eco Time, which is used to upload the payroll hours to PaySpace and match reponses from PaySpace to the transaction.
   3. Payroll No: Eco Time's payroll number. Depending on the Identifier type selected in the settings tab, this can be Eco Time's payroll number or employee number.
   4. First Name: Eco Time's employee First Name.
   5. Surname: Eco Time's employee Surname.
   6. Component Code: Payrol code as configure in Eco Time's time category setup .
   7. Input Type:The default is "Hours" but can be changed in the company's export settings form.
   8. Input Value: Totals payroll hours for the time category in decimal format.
   9. Cost Centre Code: PaySpace required field. Not supported by Eco Time.
   10. Activity Code: PaySpace required field. Not supported by Eco Time.
   11. A web interface option is available. More information can be found here.
        
2. Export History

   
   Once the payroll export has been uploaded to PaySpace, the PaySpace will respond to each component uploaded.
   The hours uploaded and the PaySpace response is stored in the API's Export History table.
   Note: You will on see the export history for the current selected payroll run period. To see previous payroll run's history, select the appropriate payroll run period from the settings tab.

   1. Payroll Date: This is Eco Time's payroll hours date as entered for the pay run currently selected in the settings tab .
   2. Request ID: An internal incremental reference ID created by Eco Time, which is used to upload the payroll hours to PaySpace and match reponses from PaySpace to the transaction. This wil match the component's ID uploaded to PaySpace.
   3. PaySlip ID: For Eco Time reference, but PaySpace internal use only.
   4. Request ID: An inte
   5. Sucess: A Yes if the upload was successful or a No if not. This is a response from PaySpace.
   6. Error: If the upload was NOT successful, this reason field will be populated. This is a reason response from PaySpace.
   7. Employee No: Eco Time's employee number. Stored for history of the original upload.
   8. Payroll No: Eco Time's employee payroll number. Stored for history of the original upload.
   9. First Name: Eco Time's employee first name. Stored for history of the original upload.
   10. Surname: Eco Time's employee Surname. Stored for history of the original upload.
   11. Component Code: Payrol code as configure in Eco Time's time category setup . Stored for history of the orrginal upload.
   12. Input Type:The default is "Hours" but can be changed in the company's export settings form. Stored for history of the original upload.
   13. Input Value: Totals payroll hours for the time category in decimal format. Stored for history of the original upload.
   14. Cost Centre Code: PaySpace required field. Not supported by Eco Time. Stored for history of the original upload.
   15. Activity Code: PaySpace required field. Not supported by Eco Time. Stored for history of the original upload.
   16. Date Added: The date the payroll export was uploaded and a PaySpace response was received.
   17. Date Updated: If the Payroll Export was regenerated, and uploaded, this date will be updated when a PaySpace response was received.
   18. A web interface option is available. More information can be found here.
        
Generating and uploading of leave records
1. Leave Export

   
   The API Client will generate the leave records to be uploaded by selecting the Generate Export button.
   The export is generated from Eco Time's leave records from the last processed leave records' time stamp.
   The Generate Export button can be used multiple times as it will clear the last generated export and recalculate the export from EcoTime's current leave records from the last leave time stamp as set on the settings tab.
   Select the API button to upload the leave records export to PaySpace.

   1. From Date: This is Eco Time's leave record's from date.
   2. To Date: This is Eco Time's leave record's from date.
   3. Employee No: Eco Time's employee number.
   4. Payroll No: Eco Time's payroll number. Depending on the Identifier type selected in the settings tab, this can be Eco Time's payroll number or employee number.
   5. Type Code: Payroll leave type code as configured in Eco Time's leave types setup .
   6. Units Taken: Total leave days for the this leave record.
   7. Units Capture: Total leave days for the this leave record.
   8. Reason Code: Reason code for the this leave record.
   9. Comment: Comment for the this leave record.
   10. Reference No: An internal incremental reference no created by Eco Time, which is used to upload the leave records to PaySpace and match responses from PaySpace to the transaction. This will match the reference numbers uploaded to PaySpace.
   11. A web interface option is available. More information can be found here.  


2. Export History

   
   Once the leave records have been uploaded to PaySpace, the PaySpace API will respond to each records uploaded.
   The leave records uploaded and thePaySpace response is stored in the API's Leave Export History table.
   

   1. From Date: This is Eco Time's leave record's from date.
   2. To Date: This is Eco Time's leave record's from date.
   3. Employee No: Eco Time's employee number.
   4. Payroll No: Eco Time's payroll number. Depending on the Identifier type selected in the settings tab, this can be Eco Time's payroll number or employee number.
   5. Type Code: Payroll leave type code as configured in Eco Time's leave types setup .
   6. Units Taken: Total leave days for the this leave record.
   7. Units Capture: Total leave days for the this leave record.
   8. Reason Code: Reason code for the this leave record.
   9. Comment: Comment for the this leave record.
   10. Reference No: An internal incremental reference ID created by Eco Time, which is used to upload the payroll hours to PaySpace and match responses from PaySpace to the transaction.
   11. Sucess: A Yes if the upload was successful or a No if not. This is a response from PaySpace.
   12. Error: If the upload was NOT successful, this reason field will be populated. This is a reason response from v.
   13. A web interface option is available. More information can be found here.
       
Importing leave records
1. Leave Import:

   
   Select the API button to import the leave records from PaySpace.
   The API button can be used multiple times as it will recollect the last 30 days of PaySpace leave records and merge them into Eco Time.
   

   1. From Date: This is Eco Time's leave record's from date.
   2. To Date: This is Eco Time's leave record's from date.
   3. Employee No: Eco Time's employee number.
   4. Payroll No: Eco Time's payroll number. Depending on the Identifier type selected in the settings tab, this can be Eco Time's payroll number or employee number.
   5. Type Code: Payroll leave type code as configured in Eco Time's leave types setup .
   6. Units Taken: Total leave days for the this leave record.
   7. Units Capture: Total leave days for the this leave record.
   8. Reason Code: Reason code for the this leave record.
   9. Comment: Comment for the this leave record.
   10. Reference No: An internal reference no created by PaySpace.
   11. A web interface option is available. More information can be found here.
        
PaySpace in Eco Time Web

Important: The PaySpace Api client must be running at the same location as Eco's Web Server.
The webserver passes API requests to the API client, which in turn will process the request and send a response back to the webserver.

1. Payroll Options in the Web

   

   1. When the PaySpace API is enabled in the Desktop Client settings tab, the PaySpace menu will become available in the web's Browse Menu.
   2. Not all the API configuration settings is available in the web in an effort to keep the user experience streamlined. Use the desktop for to change advanced settings.
   3. All changes made in the web are reflected in the desktop API and the other way around.
   4. The settings tab allows the user to set the payroll run period and working company.
   5. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
2. Employees Check in the Web

   

   1. The employee check browse contains all the captured employees on the PaySpace system.
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
3. Updating Employees in the Web

   

   1. The user can override the employee's match status. Select Exempt if you will not export this employee's hours to payroll and do not require a match to be performed in the future for this employee. Select OK to save your changes. Note: Not in Payroll cannot be set to exempt and must be excluded from the export with filter groups.
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
4. Payroll Companies in the Web

   

   1. The payroll companies browse contains all the captured employees on the PaySpace system.
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
5. Updating Payroll Companies in the Web

   

   1. The user may assign an Eco Time employee group. This employee group will used to limit the employees in Eco Time when generating export payroll hours and uploading these to PaySpace. This is an optional field.
   2. Disabling the company will exclude all it and all its employees in Eco Time when generating export payroll hours and uploading these to PaySpace if this company is selected as the working company.

      

   3. When enabled, the Export settings Tabs will override the payroll export codes and settings configured in Eco Time. This allows for different export settings for different payroll companies at one site.
   4. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
6. Frequencies / Payroll Rules in the web

   

   1. The Frequencies browse should contains all the captured frequencies / payroll rules on the PaySpace system and must be manually added.
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
7. Updating Frequencies / Payroll Rules in the web

   

   1. The Frequencies update form allowed the employee group to be assinged or changed..
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
8. Pay Run Periods in the Web

   

   1. The Pay Run browse contains all the pay run periods setup in PaySpace.
   2. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
9. Updating Pay Run Periods in the Web

   

   1. This mimics the behaviour and rules of the desktop interface which can be seen here.
       
10. Payroll Export in the Web

    

    1. The Payroll Export browse contains generated hours extract for the current selected pay run period which can be uploaded to PaySpace.
    2. This mimics the behaviour and rules of the desktop interface which can be seen here.
    3. Note: The Generate and Upload button schedules that processes on a sperate thread for processing by the PaySpace API Desktop Client.
    4. Press the refresh button to update the progress and values in the Payroll Export Browse.
        
11. Payroll Export History in the Web

    

    1. The hours uploaded and the PaySpace response is stored in the API's Export History table and displayed in this browse.
    2. This mimics the behaviour and rules of the desktop interface which can be seen here.
    
    
12. Leave Export in the web

    
    

    1. The Leave Export browse contains generated leave records which can be uploaded to PaySpace.
    2. This mimics the behaviour and rules of the desktop interface which can be found here.
    3. Note: The Generate and Upload button schedules that processes on a separate thread for processing by the PaySpace API Desktop Client.
    
    
13. Leave Export History in the Web

    
    

    1. The leave records uploaded and the PaySpace response is stored in the API's Leave Export History table and displayed in this browse.
    2. This mimics the behaviour and rules of the desktop interface which can be found here.
    
    
14. Importing leave records in the Web

    
    

    
    
    1. The imported leave records, and the PaySpace references are stored in the API's Leave Import table and displayed in this browse.
    2. This mimics the behaviour and rules of the desktop interface which can be can be found here.
Manually Triggering the API
1. An API call can be manually triggered at any time by pressing the API button at the bottom of each browse.
2. An API call triggered will depend on the current tab selected (eg Events).
3. All manually triggered API calls are not automated. This means the API Client Request Window will open and you would manually have to press the Res (Get) button. Afterwards press the close button to exit the API call.
   1. API Client Request Window Request:
      
   2. API Client Request Window Response:
      
4. The API Status message at the bottom left of the browse will be updated with the current action or process.
5. Manually triggering an API is used during the configuration and setting up phase of the API.
6. It is also very helpful when doing fault finding. See the FAQ for more details about this.
Timed API Events
1. Timed events are automated events trigger either by time or an interval duration, in other words automated API calls.
2. During timed events the API Client Request Window is hidden but the API status message is updated.
3. There are three timed events:
   1. The API is authenticated with every timed event.
   2. The employees list is synced twice a day. Once at 1am and once at 1pm.
   3. The Frequencies list is synced twice a day. Once at 1am and once at 1pm.
   4. The Pay Run list is synced twice a day. Once at 1am and once at 1pm.
4. Timed events can be disabled be selecting the "Stop timed events" check box on the PaySpace API Window.
API Logs
1. The logs browse displays general information about the API requests, responses and processes.

   

2. The log display information about:
   1. Details about the API event.
   2. If the API event was processed or rejected. If rejected, it provides a reason.
   3. When manual or timed API events were triggered.
FAQ
1. In which Eco Time version is this feature available?
   From version 2024.07.20 onwards.
    
2. What information must the customer provide to setup the API?
   1. Client ID
   2. Client Secret
   3. The Eco Time employee group for who the payroll hours will be uploaded to PaySpace.
       
3. What process must the customer follow on a regular basis before payroll?
   1. The match discrepancies in the employee browse must be resolved on a regular basis .
       
4. What process must the customer follow to upload payroll hours?
   1. Important: The match discrepancies in the employee browse must be resolved.
   2. Select the correct Pay Run Period.
   3. Generate Export.
   4. Upload Payroll Hours.
       
5. I want to supress some of Eco Time Time Categories being exported.
   You can supress the time category from being exported in the API by disabling the applicable time category's "Export to Payroll" setting in Eco Time.
    
6. Some of the component codes (payroll codes) are incorrect. Where can these be changed?
   You can change the component code exported by the API by changing the applicable time category's "Payroll Code" setting in Eco Time.
    
7. What is a Pay Run or Pay Run period.
   This is the terminology used by Pay Space indicating their pay period start and end date. Eco Time must update each pay run to indicate the payroll end date in Eco Time that matches each pay run.
    
8. My Pay Run API upload returns a large number of invalid component code errors.
   The component codes are linked to a frequency. Refer to the Component Codes' browse to verify that the Pay Run frequency matches that of the component code's frequency. It is most likely that the Pay Run frequency is set incorrectly in PaySpace and now does not include the correct component code group.
    
9. I am trying to assign or select a pay run, but my pay run period is not in the lookup.
   Pay runs will only be available in the lookup if an Eco Time payroll date has been allocated. Select the Pay Runs browse and update the applicable pay run.
    
10. What is an unverified employee.
    This is an employee which was added to the employee browse from the PaySpace system in the past, but in more recently compares between this list and the PaySpace system, the employee was not found in the PaySpace system anymore.
    This typically happens if an employee is removed from the PaySpace system or allocated a new PaySpace employee record.
     
11. I am manually trying to use the API to populate the Pay Runs table, but the API windows does not appear.
    The Frequencies table must be populated first. The Pay Runs API will not run if there are no entries in this browse.
     
12. What is an authentication token?
    An authentication token is a digital credential used to verify the identity of a user, application, or device trying to access a system, service, or resource. It is often generated after successful authentication and can be used to maintain a session or grant access to specific resources without needing to re-authenticate repeatedly.
    
    The token expires after 2 hours, requiring the authentication API to be run again to obtain a new token.  If the token has expired, any API call wil be retun an Invalid Token or Unauthorised error.
     
13. Do I have to request an API Server URL and Authentication Server URL for customer?
    No. PaySpace's URLs are the same for all customers. The default URLs provided will be correct. NOTE: The Production and QAS URLs are different - but provided as defaults for each mode.
     
14. How can the API Client Request Window be used for fault finding?
    1. This window displays the request link in the server fields. You can use his value to determine if the correct link is being used during the call.
    2. Consider selecting the "Do Not Process Response" disables any results processing. No tables will be populated. This is typically used for faulty finding and is used in cases where you want to inspect the request packet and result packet.
    3. The PaySpace API Server response is displayed in the response window's text field. This response is the raw unprocessed data from the PaySpace API Server and represents the true data transmitted and received by the API Client.
    4. The response packet is json and is unformatted (one long string) and is in the body of the response. Copy this body to your clipboard and use an online formatter like https://jsonformatter.org/ to make the response easier to read.
    5. By inspecting the raw formatted json response, you can validate the values eventually stored in Eco Time and the PaySpace API Client.
        
15. How do you configure the PaySpace API Server for API Access?
    The tutorial can be found here: Creating API credentials for integration
     
16. What is the difference when setting the employee group at company and frequency / payroll rule level?
    1. Setting the employee group at the company level will limit the API's employee import and verification to this specific Eco Time group. This is useful in cases where a company has staff, such as executives, recorded in Eco Time, but they do not use time and attendance clocks. In this scenario, you can create and assign an employee group called "Time and Attendance" to the applicable employees. By updating the API's company employee group to this, executives will be excluded from the API processing.
    2. You can assign an Eco Time employee group to each frequency or payroll rule. If the frequency or payroll rule applies to wages staff, you could assign the employee group for wage employees to that frequency. Typically, you would assign an employee group to a frequency or payroll rule to separate wages, salaried, and casual employees when selecting the applicable payroll run to upload employee times. Only the employees' times in this group will be uploaded to payroll, first filtered by the company employee group, and then by this specific employee group.
        
17. What is it important to assign the correct Eco Time employee group to the frequency / payroll rule level?
    1. In PaySpace, the Payroll Run Periods are created for each frequency or payroll rule, such as wages and salaries.
    2. Assigning the incorrect employee group to the applicable frequency or payroll rule could result in salaried employees' time being uploaded to a payroll run meant for wages. Since wage and salaried payroll runs have different component codes (pay codes), employees not belonging to the applicable pay run will trigger an error: "Invalid Component Code."
        
18. The Desktop Server API Settings has an API Mode selection option for Production or QAS. What is the difference between the two modes?
    1. PaySpace offers a default option (upon request) to create a duplicate of the customer's live data on their staging (QAS) server. This data will be accessible when the API's QAS option is selected and the settings are configured accordingly.
    2. The two modes allow the user to have two different settings for testing and live, and removes the requirement to change settings continuously if the user toggles between the testing and the live system.
    3. QAS is for Testing the PaySpace system and Production for the current live PaySpace system.
    
    
19. Not all the leave records are imported into Eco Time
    
    1. This typically occurs when no matching leave import payroll code is found in Eco Time. For more information about the error, please refer to the Leave Import Notes column in the API.
    2. Leave records with the same employee number, start date, and leave type are not imported, as they are considered duplicates. Please refer to the Leave Import Notes column in the API.
    3. Only import leave records with a status of Approved are imported into Eco Time. If an existing Approved leave record that was previously imported is later changed to Declined, the corresponding leave entry in Eco Time will be removed.