Follow

What are integration templates?

Overview

Integration templates are a feature available in the Admin Console under Settings -> Integration -> Templates. They are custom export files used by the Payroll report. These files can be of any textual type you wish: HTML, Excel, CSV, plain text, etc. We provide a number of builder wizards for templates to help get started with them, including for several popular payroll programs such as ADP, Paychex, Sage, and QuickBooks.

Screen_Shot_2022-11-14_at_5.36.25_AM.png

After you run a builder, you can then manually edit the template to your liking.

Screen_Shot_2022-11-14_at_5.37.03_AM.png

 

To use a template, go the Payroll report under Manage -> Reports =-> Payroll, run your report, then export to a template that you created.

Screen_Shot_2022-02-23_at_1.48.31_PM.png

 

Template Language

The template is specified using the rich and powerful Nunjucks template language. Documentation on Nunjucks can be found here:

https://mozilla.github.io/nunjucks/templating.html


One of the many features of Nunjucks is the ability to run "filters" on data values to format or convert them for displaying. In addition to the built-in filters provided by Nunjucks, we provide a few extra filters useful in Fareclock:

  • date - Format a date-time value. The format strings themselves use a 3rd party Date library called Moment.js. To see the available format strings, refer to the Moment.js documentation here: http://momentjs.com/docs/#/displaying/
  • duration - Format a duration value, e.g., total time worked. The format strings use a Moment.js plugin which is documented here: https://github.com/jsmreese/moment-duration-format. The default format is number of hours with precision of 2, e.g., one hour fifteen minutes would be displayed as 1.25.
  • fixed - Format a number to specified precision, i.e., number of decimal digits. This is particularly useful for pay amounts, where you might use fixed(2) to specify cents.

Report Data

A template would not be useful without data to render. The Payroll report provides a rich and deep data object to the template, so you can create pretty much any report you might imagine.

The data object is a JSON object structured as follows:

{  
   "meta":{  
      "title":"Payroll",
      "from":"2015-10-13T04:00:00.000Z",
      "to":"2015-10-13T04:00:00.000Z"
   },
   "payrollId":"ORG_PAYROLL_ID",
   "employees":[  
      {  
         "employee":{  
            "name":"John Doe",
            "firstName":"John",
            "lastName":"Doe",
            "payrollId":"JOHN_DOE_PAYROLL_ID"
         },
         "department":{  
            "name":"Office",
            "payrollId":"OFFICE_PAYROLL_ID"
         },
         "totals":{  
            "duration":657,
            "regularDuration":540,
            "ot1Duration":117,
            "ot2Duration":0,
            "otDuration":117,
            "regularPay":675.09,
            "otPay":675.09,
            "pay":1350.18
         },
         "timecards":[  
            {  
               "date":"2015-10-13T04:00:00.000Z",
               "totals":{  
                  "duration":657,
                  "regularDuration":540,
                  "ot1Duration":117,
                  "ot2Duration":0,
                  "otDuration":117,
                  "regularPay":675.09,
                  "otPay":219.4,
                  "pay":894.49
               },
               "payCodes":{  
                  "5088561288183808":{  
                     "pay":219.4,
                     "duration":117,
                     "payrollId":"JOT1",
                     "name":"Job OT 1"
                  },
                  "5651511241605120":{  
                     "pay":153.77,
                     "duration":123,
                     "payrollId":"JREG",
                     "name":"Job Regular"
                  },
                  "4807086311473152":{  
                     "pay":521.32,
                     "duration":417,
                     "payrollId":"SREG",
                     "name":"Shift Regular"
                  }
               },
               "nonWorkPayCodes":{  
                  "4807086311473152":{  
                     "pay":93.76,
                     "duration":75,
                     "payrollId":"SREG",
                     "name":"Shift Regular"
                  }
               },
               "punches":[  
                  {  
                     "inExceptions":[  
                        "edited",
                        "started_early"
                     ],
                     "inOrgUnit":4649641400336384,
                     "payCodes":{  
                        "4807086311473152":{  
                           "pay":427.56,
                           "duration":342,
                           "payrollId":"SREG",
                           "name":"Shift Regular"
                        }
                     },
                     "in":"2015-10-13T10:00:00Z",
                     "processedTotal":357,
                     "costCenterPayrollId":"",
                     "outExceptions":[  
                        "edited"
                     ],
                     "regularDuration":342,
                     "ot2Duration":0,
                     "out":"2015-10-13T15:57:00Z",
                     "regularPay":427.56,
                     "ot1Duration":0,
                     "inOrgUnitName":"Default",
                     "status":"approved",
                     "costCenter":5810940427632640,
                     "id":6458000873095168,
                     "overtimePay":0,
                     "costCenterName":"Overhead",
                     "inDt":"2015-10-13T10:00:00Z",
                     "outDt":"2015-10-13T15:57:00Z",
                     "totals":{  
                        "duration":357,
                        "regularDuration":342,
                        "ot1Duration":0,
                        "ot2Duration":0,
                        "otDuration":0,
                        "regularPay":427.56,
                        "otPay":0,
                        "pay":427.56
                     }
                  },
                  {  
                     "processedTotal":240,
                     "outExceptions":[  
                        "edited",
                        "left_late"
                     ],
                     "out":"2015-10-13T17:03:00-04:00",
                     "regularPay":153.77,
                     "jobName":"11really really long name x",
                     "jobRegularPayCode":5651511241605120,
                     "in":"2015-10-13T13:00:00-04:00",
                     "jobOvertime1PayCode":5088561288183808,
                     "inOrgUnitName":"Default",
                     "jobPayrollId":"RL",
                     "jobOvertime2PayCode":6214461195026432,
                     "id":5665527867375616,
                     "overtimePay":219.40425,
                     "inExceptions":[  
                        "added",
                        "long_break"
                     ],
                     "regularDuration":123,
                     "ot2Duration":0,
                     "status":"approved",
                     "jobCategory":6466799113601024,
                     "costCenterName":"Overhead",
                     "inOrgUnit":4649641400336384,
                     "payCodes":{  
                        "5088561288183808":{  
                           "pay":219.4,
                           "duration":117,
                           "payrollId":"JOT1",
                           "name":"Job OT 1"
                        },
                        "5651511241605120":{  
                           "pay":153.77,
                           "duration":123,
                           "payrollId":"JREG",
                           "name":"Job Regular"
                        }
                     },
                     "costCenterPayrollId":"",
                     "ot1Duration":117,
                     "job":6200979292684288,
                     "costCenter":5810940427632640,
                     "inDt":"2015-10-13T13:00:00-04:00",
                     "outDt":"2015-10-13T17:03:00-04:00",
                     "totals":{  
                        "duration":240,
                        "regularDuration":123,
                        "ot1Duration":117,
                        "ot2Duration":0,
                        "otDuration":117,
                        "regularPay":153.77,
                        "otPay":219.40425,
                        "pay":373.17425000000003
                     }
                  }
               ],
               "workSegments":[  
                  {  
                     "segment":[  
                        "2015-10-13T10:00:00Z",
                        "2015-10-13T13:00:00Z"
                     ],
                     "punch":6458000873095168
                  },
                  {  
                     "segment":[  
                        "2015-10-13T13:00:00Z",
                        "2015-10-13T13:15:00Z"
                     ],
                     "punch":6458000873095168,
                     "break":true,
                     "overtime":true
                  },
                  {  
                     "segment":[  
                        "2015-10-13T13:15:00Z",
                        "2015-10-13T15:57:00Z"
                     ],
                     "punch":6458000873095168
                  },
                  {  
                     "segment":[  
                        "2015-10-13T13:00:00-04:00",
                        "2015-10-13T17:00:00-04:00"
                     ],
                     "punch":5665527867375616
                  }
               ]
            }
         ],
         "payCodes":{  
            "5088561288183808":{  
               "duration":117,
               "pay":219.4,
               "payrollId":"JOT1",
               "name":"Job OT 1"
            },
            "5651511241605120":{  
               "duration":123,
               "pay":153.77,
               "payrollId":"JREG",
               "name":"Job Regular"
            },
            "4807086311473152":{  
               "duration":417,
               "pay":521.32,
               "payrollId":"SREG",
               "name":"Shift Regular"
            }
         }
      }
   ]
}

This sample data object does not contain every possible value. You can view the entire raw JSON data object by creating a test template based on the "Raw" base template. If you have any questions about how you can access certain data, please contact Fareclock Support.

Excel

If you choose to create an Excel template, you'll want to use the Excel XML Spreadsheet language. Although it's an old specification, it's comprehensive and you can create pretty much any spreadsheet you want. When exporting a report for such a template, we will automatically convert it to a modern, native xlsx file that can be opened by Excel, Google Sheets, or any other program that can render xlsx files.

Our Excel builder creates an example template you can start from, and more information on the Excel XML language can be found here:

https://msdn.microsoft.com/en-us/library/aa140066(office.10).aspx

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk