TimeTrex Community Edition Integration: How to integrate third party Payroll/Time Clock software into SambaPOS

[Jesse]

!!!IMPORTANT READ FIRST!!!

This tutorial will be based on the understanding that you already have TimeTrex Community Edition installed and it is operating correctly it will not explain how to install and operate TimeTrex Community Edition. You should have a working knowledge of how to administer TimeTrex BEFORE you deploy it or this tutorial in your business.
If you have any questions on Installation or Administration of TimeTrex use the official TimeTrex resources http://forums.timetrex.com/ You will not get answers about TimeTrex in the SambaPOS forums

Furthermore you must understand that to see the Entity Screen correctly you should wait until they release the HTML5 version of TimeTrex Community Edition which is due out very soon.

TimeTrex Community Edition is an open source Time Clock and complete Payroll system you can find it at http://sourceforge.net/projects/timetrex/files/TimeTrex%20Community%20Edition/

Purpose of this Tutorial:

Until native support for a built in Time Clock or Payroll system is developed within Samba this Tutorial will show how to integrate various functions of TimeTrex Community Edition into SambaPOS V4 for purpose of automating employee punches and adding other optional functionality. This will serve as a way to include Time Clock and Payroll functions into Samba and making it function as if it was built in without requiring the employee’s to navigate to outside software or opening a separate browser.

Operational Flow:

Employee logs in to Samba at start of their shift: Samba displays a popup for them to Clock In Employee presses clock in which records a time punch in TimeTrex for that employee.

Employee Navigates to Time Clock Entity Screen to Clock Out: Pressing Clock Out will record a time punch in TimeTrex and log the user out of SambaPOS.

When HTML5 version is released I will demonstrate how to design buttons like Check Schedule and it will bring up the employees schedule within TImeTrex and display it on the HTML viewer widget.

Database Tools Module Import File: This is just the SambaPOS setup portion you still need to setup the TimeTrex scripts as listed below.

Samba_TimeTrex.zip (1.7 KB)

You will need to update the file locations, user names, role names within a few of the rules to match your setup.

TimeTrex Scripts: You will need to edit these as according to the tutorial below.

TimeTrex Scripts.zip (1.6 KB)

Screenshots of the integration and how it functions:

First Login for Work Period:

Time Clock Custom Entity Screen:

TimeSheet View: This is a Demo to show possible function not an actual Timesheet

Check Schedule Button is Pressed: This is a Demo to show possible function not an actual Schedule

Check Exceptions View: Admin Only Access This is a demo to show possible function not an actual Exceptions Screen

[Jesse]

Inside your TimeTrex/scripts folder create three folders:

php
bat
vbs

Create a .php file for each employee named the same as their SambaPOS login and save them in the php folder you just made. Can use notepad and just save file as .php instead of .txt

Example SambaPOS login=Jesse PHP file would be named Jesse.php **CASE SENSITVE**

When you enter each employee into TimeTrex you must use the same log-in that you used for them in SambaPOS and it should be CASE SENSITIVE

Passwords do not have to be the same for SambaPOS and TimeTrex just Usernames.

Within each employee PHP file that you just made put the following code:

<?php
    require_once('../../classes/modules/api/client/TimeTrexClientAPI.class.php');
    /*
     Global variables
    */
    $TIMETREX_URL = 'http://localhost:8085/api/soap/api.php';
    $TIMETREX_USERNAME = 'SAMBAUSERNAME';
    $TIMETREX_PASSWORD = 'TIMETREXPASSWORD';

    $api_session = new TimeTrexClientAPI();
    $api_session->Login( $TIMETREX_USERNAME, $TIMETREX_PASSWORD );
    if ( $TIMETREX_SESSION_ID == FALSE ) {
       echo "Login Failed!
    \n";
       exit;
    }
    echo "Session ID: $TIMETREX_SESSION_ID
    \n";

    $punch_obj = new TimeTrexClientAPI( 'Punch' );

    $punch_data = array(
            'user_id' => 3, //Active
            'station_id' => 1,
            'type_id' => 10,
            //'status_id' => 10, //status type of in 10 , out 20
            //'created_by' => 1,
            'time_stamp' => time()

    );
    try{
    $result = $punch_obj->setPunch( $punch_data );
    if ( $result->isValid() === TRUE ) {
       echo "Punch added successfully.
    \n";
       $insert_id = $result->getResult(); //Get punch new ID on success.
    } else {
       echo "Punch save failed.
    \n";
       print $result; //Show error messages
    }
    }catch(Exception $e){
       echo $e->getMessage();
    }

    ?>

[Jesse]

!!IMPORTANT!!

[Jesse]

Create a .bat file for each employee named the same as their SambaPOS login save them in the bat folder you just made. Can use notepad and just save file as .bat instead of .txt

Example: SambaPOS login=Jesse BAT file would be named Jesse.bat **CASE SENSITIVE**

Within each employee BAT file put the following code:
Change drive letters to fit your own install.

@echo OFF
"f:\timetrex\php\php.exe" f:\timetrex\scripts\php\USERNAME.php %*

[Jesse]

Create a .vbs file for each employee named the same as their SambaPOS login save them in the vbs folder you just made. Can use notepad and just save file as .vbs instead of .txt

Example: SambaPOS login=Jesse VBS file would be named Jesse.vbs **CASE SENSITIVE**

Within each employee VBS file put the following code:
Change drive letters to fit your own install.

Set WshShell = CreateObject("WScript.Shell")
WshShell.Run chr(34) & "f:\timetrex\scripts\bat\USERNAME.bat" & Chr(34), 0
Set WshShell = Nothing

[Jesse]

Now we need to setup the SambaPOS side of things:

Setup two Automation Commands:
No Mapping

And

Setup the following Actions:

Display Popup Action

Time Clock Action

Reset User’s Status Action

Update User’s Status Action

Logout User Action

[Jesse]

Setup the following Rules:

Display Time Clock Popup Rule

Reset User’s Status on Clock Out Rule

Reset User’s Status Rule

Time Punch Rule

Clock Out Rule

[Jesse]

Create your Time Clock Custom Entity Screen:

[Jesse]

This Tutorial will be modified to include additional functions once HTML5 version is released.

[Jesse]

Added the Database Import Tools file for the SambaPOS portion of this tutorial. Reminder you still need to follow the TimeTrex setup portion of the tutorial but this file will setup all of the SambaPOS portions for you.

After you import the settings you will still need to update a few of the rules with your specific User Roles / User Names / File Paths you can see the references above for which ones you will need to change.

[Jesse]

Added Template TimeTrex scripts. Follow the tutorial on how to edit them. You can just copy/paste for your employees and then edit each one as the tutorial describes.

[Jesse]

I always recommend making a backup of your Database before you try anything new

[kmurat]

I follow the tutorial and put in place timetrex and then i launch sambapos with timetrex module, i have same window of you @Jesse but i dont know where i can found the HTML 5 Version of TimeTrex. please thanks for help me.

[Jesse]

It is not released yet. It is due out any time. It is currently in beta test with the cloud version. The screenshots you see with the screen displayed were with the cloud version. I will not use the cloud version you cannot do the integration with it because all the server side is on their servers. I simply used it for illustrative purposes.

You can still pull it up in a normal web browser until the HTML 5 version is released. What I mean is you can still use it for clocking in and out it works really well. You will have to use a web browser to administer it until HTML 5 version is out.

Spend some time getting used to TimeTrex its very powerful. They are beta testing HTML5 on the cloud version of 7.3.10 so im guessing the local version will be out next month.

[Jesse]

The day has come! HTML5 goodness is supported now. They released version 7.4 with full HTML5

[antasp3136]

I have followed this tutorial but when i run the script it gives me the message punch save failed… add permission denied…

[Jesse]

For it to work your users in TimeTrex. have to be configured with the ability to edit their own punches. I mentioned you should get to know TimeTrex really well before you attempt to use it like I showed in the Tutorial.

The tutorial is more to show its possible vs a recommendation. There are ways to prevent users from editing their own punches even though you have enabled it in TimeTrex

[Jesse]

It is logging into TimeTrex as the user and inserting a punch for that user… but technically it is logging in as the user and inserting its own punch based on username logged in. So the User listed in TimeTrex must have permission to edit own punches.

Good news is… it looks like you set everything up correctly! you just need to edit the users permission in TimeTrex to allow it to edit its own punches. This is done through Company/ Permission Groups

They intentionally hide the API for the user to just clock… as they want you to buy professional edition to get that access they call it Quick Punch. Technically you can still do it because it is open source but I was not smart enough to figure out the syntax and its hidden from the API.

So my work around until I can figure out how to get the API to just punch vs Edit a punch… is to let the user edit the punch as this feature was not hidden from the API.

I simply restrict users from accessing their punches if they Log in to timetrex. So this way they can not edit it themself… only Samba does.

[antasp3136]

Well i got it to work by changing the permission the only thing now is that it does not matter what my username is it keeps making punches based on the user id in the php script… so user1 can make punches for administrator as long as the user id matches the administrators. Is this how it works for you as well… I may have missed it but i dont think i saw where we would need to edit this in the script would we?

[Jesse]

Read through again you missed a vital step. You should have a separate script for each user. A separate .vbs and a separate .bat for each user.