Overview
The Handyman integration with Tripletex is a two-way integration built around projects. A project in Tripletex is an order in Handyman, and that pairing carries the whole integration: the project is created or maintained in either system, the technicians do the work in Handyman, and everything they register — hours, material, travel costs, mileage, descriptions and documents — is written back onto the same project so that it can be invoiced from Tripletex.
Around that core, master data moves one way only. Tripletex is the master of departments, employees, customers, categories, salary codes and product catalogues; Handyman receives them and does not send changes back. The one exception is customers: a customer created in Handyman is exported to Tripletex the first time it is used on an order, and from then on Tripletex owns it.
Stock is not part of the integration. Inventory, store items, stock movements and stocktaking stay in each system, and invoicing stays in Tripletex — the integration delivers the priced material and hours the invoice is built from, but never the invoice itself.
Data flow at a glance
Master data and projects come from Tripletex; the work registered on the order goes back onto the same project. The table below sets out the same exchange in words.
What is exchanged
| Direction | Data | Notes |
| Tripletex → Handyman | Departments, employees, customers with their addresses and contacts. | Employees are imported so that those who can be project managers are recognised as such. Inactive customers are not imported. |
| Tripletex → Handyman | Customer categories and project categories. | Project categories become order categories; they can be restricted to a chosen set. |
| Tripletex → Handyman | Project activities, travel cost categories and mileage allowance rates. | All three become salary codes in Handyman — in hours, amount and kilometres respectively. |
| Tripletex → Handyman | Products, and the catalogues of the selected wholesalers. | Products become items on a wholesaler that represents your own company; wholesaler catalogues become item lists under their own wholesaler, by NRF or EL number. |
| Tripletex → Handyman | Projects, with participants, description, category, delivery address and order lines. | The project becomes an order; its order lines become material on that order. |
| Handyman → Tripletex | The order itself, as a project. | Created on first export, updated on later ones. Participants are kept in step, and participants removed in Handyman are removed from the project. |
| Handyman → Tripletex | Order descriptions. | The project description is written back to the project; the remaining descriptions become order lines on it. Internal descriptions are never sent. |
| Handyman → Tripletex | Material registrations. | As project order lines, priced according to what the technician registered and matched to the Tripletex product by item, NRF or EL number. |
| Handyman → Tripletex | Hour registrations. | As timesheet entries, and — when hourly rate export is switched on — as project-specific hourly rates for the day, employee and activity. |
| Handyman → Tripletex | Cost and mileage registrations. | As travel expense costs and mileage allowances, gathered per employee on one open travel expense per project. |
| Handyman → Tripletex | Order documents and reports. | Uploaded to the project's document archive. Optional, and each document is sent once. |
| Handyman → Tripletex | Customers created in Handyman. | Exported the first time the customer is used as the invoice customer of an exported order. |
| Not exchanged | Hours, costs and mileage registered in Tripletex. | Registrations flow towards Tripletex only. Time entered directly in Tripletex does not appear on the Handyman order. |
| Via 3.party integration from Suppli | Inventory, store items, stock movements and stocktaking. | Stock is kept separately in each system. |
| Via 3.party integration from Suppli | Invoices and purchase orders. | Invoicing is done in Tripletex on the exported project. |
How the integration works
The integration runs as a service. It watches for changes on both sides and reacts to them; there is no nightly batch that everything waits for, and no client software to keep up to date.
What sets it in motion
| Trigger | What happens |
| Material is booked on a project in Tripletex | When a voucher is posted or updated, the projects it books onto are re-read, so material and cost registered through the voucher appear on the Handyman order. Tripletex does not raise a project change for this, which is why the voucher itself is watched. |
| An order changes in Handyman | The order is exported to Tripletex — either on every change, or only once it reaches the status agreed for the installation. An order can also be exported manually from Handyman. |
| A record changes in Tripletex | Tripletex notifies the integration when an employee, customer, contact, product or project changes, and that single record is updated in Handyman within moments. |
| A scheduled refresh | Product and wholesaler catalogues are large and change constantly, so they are refreshed on a schedule rather than one record at a time. |
| A full import is requested | Master data can be re-imported from Handyman when something needs to be brought back in step — after a longer outage, for example, or when a new wholesaler is added. |
How a run is carried out
Work for one installation is carried out one run at a time, so an incoming change waits rather than colliding with a running import. Imports of large data sets are done in portions: each kind of data remembers the last change it saw, so the next run asks Tripletex only for what has changed since, and a catalogue import that spans thousands of records simply continues until it is done.
An export follows a fixed order. The order becomes a project — creating the customer first if it does not yet exist in Tripletex — and then participants, descriptions, material and registrations are placed on that project. Documents follow last, once the order itself has been exported successfully.
How the two systems stay matched up
Every record that has been exchanged carries a reference to its counterpart: the Handyman order knows its Tripletex project, each material line knows its project order line, and each registration knows the timesheet entry or travel expense it produced. That is what keeps a second export from creating a duplicate — exporting the same order again updates the existing project rather than adding a new one — and it means an order can safely be re-sent if something needs correcting.
What you see when something fails
Every run reports back to Handyman, record by record: what was processed and what failed, with the reason. A rejected export is reported against the order it belongs to, so the person who made the registration can see why it did not reach Tripletex. An error on a single record does not stop the rest — the remaining orders and registrations are still processed.
What is needed to get started
The integration connects to Tripletex as an employee of your own company, using an access token that you generate in Tripletex and hand over to GSGroup.
| What | Details |
| Access to Tripletex | An employee token created in your Tripletex account for the GSGroup integration. All work is carried out as that employee, so it needs rights to projects, customers, employees, products, timesheets and travel expenses. Keep the employee active — the integration stops working if the token is revoked or the employee is deactivated. |
| A default payment type | Required. Travel and cost registrations are exported against one Tripletex payment type; the integration cannot run until it has been chosen. |
| The wholesalers to work with | Which of your Tripletex wholesalers should be available to technicians in Handyman, and whether each is used with NRF or EL numbers. |
| A category decision | Whether all Tripletex projects should become Handyman orders, or only those in certain project categories. |
| A start date | Where Tripletex projects already carry historical material, a date from which material should be imported, so that old lines are not pulled into Handyman. |
Options – Products and wholesalers
Which Tripletex product catalogues the technicians see in Handyman, and how prices and units are derived.
| Option | Values / default | What it does |
| NrfWholesalersToImport | List of Tripletex wholesalers | The wholesalers whose products are made available by NRF number. Each becomes a separate wholesaler in Handyman. If the list is empty, no NRF catalogues are imported. |
| ElWholesalersToImport | List of Tripletex wholesalers | The same for wholesalers used with EL numbers. A wholesaler that appears in both lists is created twice in Handyman — once for NRF and once for EL numbers — because the two catalogues use different item numbers. |
| DefaultProductUnit | Text | Unit used when a Tripletex product has no unit of its own. Units longer than four characters are shortened. |
| CostMarkupForPriceCalculation | Percentage | When set, the sales price in Handyman is calculated from the Tripletex cost price with this markup, and the Tripletex sales price is kept as list price. When it is not set, the Tripletex sales price is used directly. Use it where material is priced from cost rather than from the catalogue price. |
| ExecuteImportOnTimer | Yes / No, default No | Includes the installation in the scheduled catalogue refresh, so that products and wholesaler items are kept up to date without anyone asking for an import. |
Options – Projects becoming orders
How Tripletex projects appear as orders in Handyman.
| Option | Values / default | What it does |
| ProjectCategoryFilter | List of project categories | Restricts the integration to projects in the chosen categories, and imports only those categories as order categories. When it is not set, all projects are imported. Note that choosing no categories at all is not the same as leaving it unset — it filters everything out. |
| ImportProjectDescriptionToMessage | Yes / No, default No | Puts the Tripletex project description in the order's message field, where the technician sees it on the device. When it is off, the description is imported as an order description instead. |
| SetOrdersToFreeIfNoParticipant | Yes / No, default No | Marks an imported order as free — available to anyone — when the Tripletex project has no participants. Orders that do have participants are unaffected. |
| ImportProjectManagerAsOrderParticipant | Yes / No, default No | Normally the project manager becomes the order's manager and is left out of the participant list. Turn this on to add the project manager as a participant as well, so that the manager also sees the order as an assignment. |
| AllowImportOfEmptyProductInOrderlines | Yes / No, default No | Imports project order lines that have no product. By default such lines are skipped, since they cannot be matched to an item in Handyman. |
| DisableImportOfOrderLineWhenZeroQuantity | Yes / No, default No | Skips order lines with a quantity of zero, or with no quantity at all. Use it where such lines are used in Tripletex for text or pricing purposes and should not appear as material on the order. |
| MigrationDate | Date | Only order lines created in Tripletex on or after this date are imported. Set it at go-live so that historical material on existing projects stays in Tripletex. |
Options – Hours, travel and salary codes
Tripletex activities become salary codes in hours, travel cost categories become salary codes in amount, and mileage allowance rates become salary codes in kilometres. What the technicians register in Handyman is returned to Tripletex as timesheet entries, travel expense costs and mileage allowances.
The hours type of an imported activity is decided from its name. Each hours type has a list of text fragments; an activity whose name contains one of them is imported with that type. Matching ignores upper and lower case and looks anywhere in the name, the lists are checked in the order below, and an activity that matches nothing becomes normal time.
| Option | Values / default | What it does |
| DefaultPaymentTypeId | Tripletex payment type, required | The payment type used for every cost registration the integration exports. The integration does not run for the installation until it is set. |
| HoursType1Texts | List of text fragments | Activities whose name contains one of these are imported as overtime. |
| HoursType2Texts | List of text fragments | Imported as holiday. |
| HoursType3Texts | List of text fragments | Imported as sick time. |
| HoursType4Texts | List of text fragments | Imported as extra pay. |
| HoursType5Texts | List of text fragments | Imported as quantity. Unlike the four types above, quantity salary codes are not summed on the timesheet. |
| ExportHourlyRates | Yes / No, default No | Exports the customer price of each hour registration as a project-specific hourly rate in Tripletex, per day, employee and activity. Use it where the price is decided in Handyman rather than in Tripletex. Two different prices for the same employee, activity and day cannot be represented and are reported as an error on the order. |
Options – Export of orders
How Handyman orders are written back to Tripletex.
| Option | Values / default | What it does |
| ExportOrdersOnStatus | Order status, or every change | Decides when an order is sent. Either the order is exported on every relevant change, including manual export, or only once its controlled status reaches the agreed value — the usual way of exporting only orders that have been checked. Note that when a status is used, manual export is not honoured. |
| SetOrderNameFromServiceModule | Yes / No, default No | For orders without a name of their own, builds the project name from the site: its number followed by the site name. Otherwise the name falls back to the address of the order. |
| FixedTripletexProjectManagerId | Tripletex employee | Puts every exported project on one fixed project manager, regardless of who manages the order in Handyman. Use it where Tripletex requires a responsible person that Handyman does not track. |
| DisableExportOfOrderDescription | Yes / No, default No | Stops order descriptions from being written to Tripletex as project order lines. Internal descriptions are never exported in any case. |
| DisableProjectDescriptionUpdateOnExport | Yes / No, default No | Leaves the Tripletex project description untouched on export. By default the description is written back, which overwrites changes made in Tripletex in the meantime. |
| ExportOrderEndDateOnlyWhenReadyForInvoicing | Yes / No, default No | Sends the project end date only once the order is completed and ready for invoicing. By default the end date is sent on every export, which moves the project period in Tripletex while work is still going on. |
Options – Documents and reports
Documents attached to an order, and the reports Handyman generates for it, can be uploaded to the document archive of the corresponding Tripletex project.
| Option | Values / default | What it does |
| ExportDocuments | Yes / No, default No | Uploads order documents to the Tripletex project after the order has been exported successfully. Reports are included once the order is finished. |
| ReportsToExport | List of reports | Restricts which generated reports are uploaded. When it is not set, all reports are uploaded; choosing none keeps reports out while ordinary attachments are still exported. |
Good to know
Behaviour that is regularly mistaken for a fault.
| Subject | What to expect |
| A new Tripletex token takes effect gradually | The integration keeps its Tripletex session for up to a day. A newly issued or newly revoked token can take that long to take full effect. |
| Material follows Tripletex | Material that exists on a Handyman order but has been removed from the Tripletex project is removed from the order at the next import. |
| Registrations travel one way | Hours, costs and mileage entered directly in Tripletex do not appear on the Handyman order. Registrations made in Handyman do reach Tripletex. |
| Documents are sent once | A document that has already been uploaded is not sent again, even if it is changed afterwards. |
| Descriptions are round-tripped carefully | The project description imported from Tripletex is recognised again on export, so it is not duplicated as an order line. |
| Inactive records are skipped | Customers, suppliers and products that are inactive in Tripletex are not imported. Activities and cost categories that are disabled are removed from the salary code groups in Handyman. |
| Invoicing stays in Tripletex | The integration delivers priced material, hours and costs onto the project. The invoice itself is created in Tripletex. |