TIMESHEET PORTAL Integration

Created by Martin Parkinson, Modified on Fri, 25 Oct at 9:38 AM by Paul Martin

From version 1.00.21.080 (or later) the Influence database integrates with Timesheet Portal.

Timesheet Portal is a great on-line timesheet system which allows workers to enter their own timesheets and client managers to approve those timesheets.

Once approved, entered hours can be retrieved into Influence for reference.

Timesheet Portal will allow Client Billing and Worker Payroll, as well as integration with accounts systems such as XERO, SAGE or Quickbooks. (Please speak to Timesheet Portal for more info)

NOTE: You will need a license in order to use Timesheet Portal - Please contact us to ask about this. (See Signup process below).

CONTENTS (Click an item to Jump to that section)

TABLE OF CONTENTS

The Signup Process
Timesheet Approvers
Managing Duplicate Contacts
Sending Timesheets
- Optional - Specified Clients Only.
- Optional - Repost Booking to Timesheet Portal (Catchup).
Retrieving Timesheets
Reversing Authorised Timesheets (Errors)
TROUBLESHOOTING

1) Once you have decided you want to use Timesheet Portal (TSP) then give us a call. One of our friendly sales team can get you over a quote for the integration and put you in touch with the right people at TSP to get the ball moving.

2) After you've purchased the Influence integration license you will need to speak to TSP and get your account sorted with them. Remember to mention you will be integrating with Influence, and ask them for your API Details.

Once you have these just give us a call with your TSP details (Username, Password and Account name). Our super support team can then get the licence installed, the integration all turned on and set up for you.

3) Book some time with one of our consultants. We can run through the process of making a booking so it gets submitted to TSP and help setup any extra statuses you might want, in order to help track these timesheets.

4) Start using it.

From the Influence side of things, that's it.

NOTE: You might want to organise some staff training on the Timesheet Portal side of things if you are taking advantage of their Payroll or Billing features - in which case speak to the lovely people at Timesheet Portal.

Back to Contents

Things to Setup in Timesheet Portal (TSP)

In order for the two systems to talk to each other, you will need to make sure certain things are setup within TIMESHEET PORTAL (TSP).

For full information about how to use, setup and maintain Timesheet Portal, please contact timesheet portal themselves. ( https://www.timesheetportal.com/contact )

1. Users

All of your consultants need to be setup as users within your TSP system. TSP logins are based upon email addresses. Importantly the CODE needs to match the UserID in Influence.

2. Placement Categories

You must setup Placement Categories that match those sent by Influence. These will be BOOK and CONTRACT.

BOOK is used for sending Temp Bookings. CONTRACT is used for sending Contract placements (made via a contract Vacancy in Influence).

NOTE: For full information about how to use, setup and maintain Timesheet Portal, please contact timesheet portal themselves. ( https://www.timesheetportal.com/contact )

Back to Contents

Post Rates to Timesheet Portal

In Influence there are various RATES and RATE CODES that are setup. Any new RATES/RATE CODES that are added to Influence need to be sent to Timesheet Portal so that when a Booking or Placement is confirmed any possible Rates already exist within Timesheet Portal.

Places where Rates are Held

There are several places where rates are held within Influence; if new codes are added to any of these, then you should re-post the rates to ensure that the new Rate codes are sent. (Or manually add the relevant rates to match within Timesheet Portal).

Location in Influence	Details
Maintenance > Setup > Code Tables Code Table RATE CODES [217]	This holds Selectable Rate codes that can be assigned to certain clients, and used as part of their Rate cards
Maintenance > Setup > Code Tables Code Table Pay Codes [154]	This holds rates that will 'always' appear on every rate card.
Maintenance > Setup > Code Tables Code Table CONTRACT RATE DES [422]	This holds rate codes used for Contract Placements (if used).

IMPORTANT: Rates can be posted to TSP using Maintenance > Temp Centre > Setup > Timesheet Portal Post Rates Codes.
This will only add NEW rate codes - existing codes will not be re-sent/affected.
{There is a setting in the Timesheet Portal API which they (TSP) can set that ensures only NEW Rate codes get added }

How it Works (overview)

Below is a description of how things basically work when making Temp Bookings and sending things to TSP.

1. Make a booking in Influence

2. In order to be posted all parties involved need to have an email address. The parties involved are:

Consultant: This is the consultant (UserID) who is making the booking.

Timesheet Approver: This is the specified "Approver" contact from the client record OR the client contact from the booking if there is no specified 'Approver' at the client.

Worker/Candidate: This is the candidate who is assigned to the Booking.

3. Confirm the booking to the Candidate. The act of confirming the booking sends details of the booking to TSP using their API.

Successful posting of the booking to TSP can be viewed from the Bookings Planner simply by hovering over the booking itself, please see below: Look for TSP POSTED

4. TSP will try to process the booking. If it is rejected by TSP then they will send an error message explaining the problem, and this message will be displayed in Influence.

{NOTE: The message contents come from TSP, so if you have questions about exactly what is meant, it is often best to talk to them (TSP) about exactly what their message means. We have added details of some of the more 'common' error messages from TSP. Please see the TROUBLESHOOTING section at the end of this guide.}

5. If there are errors (as above) you will need to rectify the problem (e.g. Add an email address to the contact, set a valid Pay Rate/Charge Rate, etc.) Once you have corrected the issue you will need to Re-Post the booking to send the details to TSP to be processed.

Tip: When re-posting bookings there is often no need to re-send the actual email to the candidate. In this case when you send the candidate confirmation, choose a METHOD of File Note rather than email.

Back to Contents

Timesheet Approvers

When you confirm a booking to the worker, at that point the system will send details of the booking to Timesheet portal. The booking will be sent with an approver - which will be either:

a) A specific nominated individual (or individuals) who is set as an approver at the client where the booking is being made. There can be multiple approvers specified at a client.

IMPORTANT: If there is a single person who approves timesheets for multiple clients, then you must associate the one contact record with multiple sites. DO NOT Create multiple contacts with the same name/email address - this will not work
See below for details.

b) If there are no specific approvers at the client, then the contact from the booking will be sent as the approver for this timesheet.

NOTE: When sending approvers to TSP the systems sends the approvers 'as is' at the time the placement/booking is posted. If additional approvers are added after that, then they will not be associated with the booking unless it is Re-Posted.

Option (a)

If you have specified an approver at the client who approves all timesheets, then this will be sent to TSP when the booking is confirmed. There can be more than one approver at a client, in which case all will be sent to TSP.

Option (b)

If there are no approvers set at this client, then the system will send the details of the booking contact as the approver.

NOTE: The booking contact is only sent when there are no specific approvers specified on the client record itself.

Option (c)

In the case of a CONTRACT placement, the system will send the following contacts as Approvers

Approver 1	Manager (from [Details] sub-tab of the [Contract] ) will be sent as the Approver for Timesheets.
(Alternative Approver 1)	IF Manager field (above) is <blank>, then the *CVs To* contact from the vacancy will be sent as Approver 1 instead.
Other approvers	Any Contacts on the CLIENT record who are marked as Timesheet Approvers are also sent to TSP as Additional approvers.

See below for screenshot showing Manager / CVs To contacts

* Single Contact who Manages Multiple Sites

If there is a single contact who manages multiple sites you must not create multiple contacts. Instead open the existing contact and associate them with multiple clients/sites.

Step 1:

Open the existing contact record at their 'current' client.

Step 2:

Once the contact opens, choose Show Where [ ] - and then select All Branches at the top right.

Expand the relevant section and right-click to choose the new client where this person is an approver. Then choose Base contact at this Branch.

Back to Contents

Managing Duplicate Contacts

IMPORTANT: If you are using Timesheet portal it is important that you do not create duplicate contacts with the same email address, since email address is used as the "Unique identifier" within timesheet portal.

Each email address can only be used once and associated with one contact only.

Sending Timesheets

Once the Timesheet Portal integration has been setup by our team, using it is super simple. It is almost invisible to users and works in the background.

Just make a booking as you normally would, and then send a confirmation (email, text, or file note) to the worker. The act of sending the confirmation to the worker triggers the timesheets to be sent to TSP using their API.

Below is an example of one of the ways you may send a confirmation.

Having sent the confirmation to the worker the status of the booking will be updated. When viewed on the planner the Status icon will indicate if the booking has been confirmed (and hence sent to TSP) - Usually with a green TICK ✅.

TIP: If you need to repost a booking then simply open the booking, click [OK] and when asked if you wish to confirm to the candidate, say yes.
When sending the confirmation you can choose a method of File Note instead of Email if you do not with to resend the email to the candidate.

Optional - Specified Clients Only.

In the unusual circumstance that only certain clients need to have their workers' timesheets sent to Timesheet Portal rather than all clients, this can be achieved using a Compliance item.

Parameter TSPORTAL,Text(6) is used to hold the CODE for a compliance item that must be created. (Speak to Influence for help in setting this up)

For each client whose timesheets should be sent to Timesheet Portal, simply go to the client record, choose the [Compliance] tab and tick the relevant compliance item.

see below

Optional - Repost Booking to Timesheet Portal (Catchup).

If you have recently switched on integration with Timesheet Portal it is possible that you have existing bookings which have already been confirmed to workers, but that have not been sent to TSP because they were sent before the integration was activated.

In those circumstances, there is an option to Re-Send existing bookings directly to TSP without the need to re-confirm the bookings.

Go to Maintenance > Temp Centre > Setup > TSP Repost Bookings

You will be presented with a screen where you can choose a cut-off date, and select which bookings you wish to repost.

*All*	This will post details of ALL bookings after the cut-off date to TSP
*Unposted Only*	This will send details of any un-posted bookings since the cut-off date to TSP
*Posted Only*	This will only send details of booking that have already been posted to TSP (i.e. Re-send already sent items)

Back to Contents

Retrieving Timesheets

Once timesheets have been submitted and approved within Timesheet Portal, they can be retrieved into Influence. This is usually done automatically overnight by a background process (daemon) that would have been setup when your integration was configured.

It is also possible to manually force the system to go and retrieve the timesheets if you do not want to wait.

To force the system to retrieve timesheets, go to Maintenance > Tools > Timesheet Portal Import

Choose [OK] to run the import.

Retrieved timesheets can be seen within TIMESHEET Entry. They are usually given a status of TSE

[This status for retrieved timesheets can be changed if necessary, and is controlled with parameter TSPORTAL, Text(10) ]

Back to Contents

Reversing Authorised Timesheets (Errors)

If a timesheet has been authorised in error within TSP, then the following process should be followed to reverse the timesheet and move things back for re-approval.

DETAILS TO BE PROVIDED >>> NOT COMPLETE YET.

Back to Contents

TROUBLESHOOTING

Issue 1: Missing approver email address.

When using TSP every person (worker, Timesheet approver, etc) must have an email address. The message below will appear if you try to send a booking where the TIMESHEET APPROVER Contact at the Client has no email address.

Back to Contents

Issue 2: TSP Branches (projects) API failed with HTTP status:401

Need to find the details and complete more detail here.

Back to Contents

Issue3: Duplicate Reference Exception

In this instance the first part of the message indicates that the email address has already been used within Timesheet portal. Within TSP email addresses must be unique. Because this email address is already a USER of TSP (i.e. one of your own consultants) it cannot also be the email address for a worker or a client contact.

Important: Within TSP email addresses must be unique; If an email has been used for a 'Staff' login the same email address cannot be used as a 'worker' or a client 'contact'.

Back to Contents

Issue 4: Multiple Errors

The screenshot below shows an example of a message that returns multiple errors. Each section is a different error that causes the posting to be rejected by TSP.

Item 1: TSP Approvers API Failed.

In this case the person assigned as the timesheet approver for this client (where the booking is being made) does not have an email address. All approvers must have an email address as this is part of the login requirements for TSP to enable them to login and approve timesheets.

Item2: Duplicate Reference Exception

This shows that the email address assigned to the consultant ID "BRDA" has been used twice. When posting Consultants, workers or approvers to TSP the email address for a person must be unique; it cannot be assigned to two people.

You may also see a duplicate Consultant failure if users are setup manually in TSP without populating their UserCode to be the same as the userID in Influence:

Item 3: Rate code HO is not associated with placement.

This is caused because the booking has hours allocated against a rate code HO but there was no actual RATE set (i.e. pay/charge were both set to £0.00).

It could also be caused if the Rate Code 'HO' did not exist in TSP. In that case you would either need to create a matching rate code (manually) in TSP re-post all the rates to ensure that the code gets sent to TSP.

Note - this has now been changed - the system will post rates EVEN IF they are both set to zero.

Rate codes are usually setup and then posted to TSP as part of the initial system setup. If new Rate codes have been added after 'Go-Live' then it will be necessary to re-post these new rates manually add them to TSP.
To repost rates use: Maintenance > Temp Centre > Setup > Timesheet Portal Post Rates Codes

Back to Contents

Issue 5: Reference Not Found - Employment Details. Third Party Agency Code. '0' is not a valid third party agency code.

You may receive an error message saying TSP Workers (contractors) API Failed, that then mentions '0' is not a valid third party agency code.

In this case the system is telling you that the worker (Jo Henderson) does not have a valid Umbrella company set. To correct this go to the [Controls] tab of the worker record and use the [... ] button to select a valid Umbrella Company.

Back to Contents

Issue 6: Field Required Exception - Email

If the error message returned from TSP states: TSP Approvers API Failed. Field Required Exception - Email this indicates that there is a problem with the person(s) sent as Timesheet approvers - and that they do not have an email Address.

Anyone submitted to TSP as an approver *must* have an email address (since email address is what is used as their login/ID for TSP)

When looking to see if the contact has an email address, remember to check;

i) Any contacts on the Client record who have been recorded as timesheet approvers.

ii) The contact on the booking (who will be sent as the approver if there are no specific approvers for this client).

In this case, because they do not have an email address, the approver does not get sent/created by TSP, hence their reference is not found.

Fix: Add an email address to the approver(s) sent to TSP for this booking.

Back to Contents

Issue 7: Field Exception - Assigned Rates - Rate code 'xxxxx' has 2 or more mappings with date overlap.

You may receive an error message such as the one below when posting a booking to TSP.

this can be caused by having a CANCELLATION, on the same date as the booking you are trying to post, with the same Booking Ref.

In this example there are multiple bookings with booking ref: 1000000812, one of which is a cancellation and one of which is a "live" booking.

The fastest solution to this to to delete/remove the Cancellation, then try to re-post the "Live" booking.

Issue 8: Field Exception - Assigned Working Pattern. The Rate code XXXXX assigned to one of your work patterns is not associated with the booking.

You may receive an error message such as this.

This can occur when a new rate / shift has been added to Influence but not posted to TSP before a booking with such rate/shift has been added. Simply run the utility in Influence that posts up all rates.

Head to Maintenance -> Temp Centre -> Setup -> Timesheet Portal Post Rate Codes

Then repost the Booking.

Issue 9: Placed Contract shows in "Bookings" but not in Timesheets.

After placing a worker into a CONTRACT and clicking [POST] - Sometimes you may not be able to find the details within "Timesheets" in your TSP system.

The REASON for this is most likely because there are no RATES on the placement within Influence. As soon as you add rates, then TSP will create timesheets for this booking when it is re-posted. (Click the POST button to re-post)

The REASON is that in Influence the placement

Issue 10: No timesheet available for workers to enter time despite booking during the active period.

If workers or consultants see the below error where there are active bookings posted to TSP (confirmed by looking at the

Influence planner) the best option is for users to contact TSP directly to assess what the issue may be. Could be that a blank timesheet has been saved as a Draft. TSP support will help out here.

That should help with this issue.

Issue 11: Duplicate Email Exception / Reference Not Found: Assigned Approver Code xxxx

If you receive a message such as the one below, it is likely that you have created TWO contacts in your Influence database who both have the same email address, and are both marked as 'Approvers' (Importance)

In this example you can see that there are two Contacts called Jade Ward; both had the same email address, but then one of them was "Deleted" within Influence.

The problem with doing this is that Influence sends details of ALL approvers up to TSP, hence Jade gets sent twice; once for the 'Live' approver and again for the 'deleted' approver.

In this case as well as DELETING the duplicate contact in Influence, you need to make sure to change their IMPORTANCE

DO NO LEAVE them with Importance 'TSP Approver'.

Please change this to something else, such as 'Mark as Deleted' or 'Left'.

Issue 12: Attempting to delete booking from TSP Failed

When trying to delete a booking within Influence, you must not remove a worker from a booking ('unfill a booking') before deleting the booking in TSP.

TSP booking codes are created with two parts:

1) The Booking Reference in Influence

2) The candidate unique id

These are separated by a dash
e.g.. B1000000156-0000034535 relates to Booking B1000000156 and candidate 0000034535

If you remove a worker from a booking that has already been posted to TSP before deleting it, Influence will send a command to TSP to find the booking in TSP but is unable to as the command Influence sends ONLY contains the Booking Reference and the not the FULL reference in TSP that includes the worker unique.

Example error:

"The JobCode B1000000156 - is not a valid JobCode"

The valid JobCode in TSP would be always be something like B1000000156-0000034535 (booking, followed by '-', followed by candidate unique id)

The error returned when trying to remove will only contain the booking reference. Notice this ends with a '-' as there is no candidate unique id on the end.

Therefore, if you wish to remove a booking or a worker from a booking that has already been posted to TSP, delete the booking in Influence first, without removing the worker form the booking. Then rebook.

Issue 13: Posting the Company to TSP failed with the Following Message: Duplicate Record Exception - Existing Company Code 279 has the same name as this company. (The Company was XXXXXXXX )

Details of the Problem: Trying to post this contract to TSP, gave the error

Duplicate Record Exception - Existing company code 279 has the same name as this company

(See below)

In Influence, the client M00022 has the name Mental Health

SOLUTION:

You will find that there is already a client created in TSP with the same name (i.e. Mental Health)

The 'fix' is to edit the client record in TSP and change the 'Client Code' from 279 as it as, to M00022 - so that it matches Influence.

Issue 14: No email entered against Consultant posting bookings to TSP

Each User in Influence that wants to post bookings to TSP must have an email address entered within their User Profile record in Influence. This email is used to create or update an Admin record in TSP (i.e the booking consultant will be an admin in TSP).

Influence will clearly respond with an error message to say that there is an issue due to a null email address and which consultant this is in relation to.

Issue 15: Posting Approvers to TSP failed with the following message: Duplicate Email Exception - [email protected] is in use by user Invoicee VEndors {nnnn}. The Branch was xxxxxxxxxxxxxxxxx

Basically the system is telling you that there is already a contact with the specified email address in TSP. In this case, the contact within Influence is associated with different branch at the site.

To 'correct' the issue, go and find the existing contact and associate them with the 'New' branch where you now wish to place contractors.

This contact may happen to be the Accounts Contact on the Contract. They also MUST be based at the correct site:

Issue 16: Posting the Booking to TSP failed with the following message: ReferenceNotFound - JobCategoryCode - BOOK.

To fix this log into the TSP Portal and choose Settings (bottom-left) then click on [+Create placement category]

Add a new Category, Code = BOOK Description = Booking

Issue 17: Posting the Booking to TSP failed with the following message: errors were encountered inporting bookings, the attached bookings were not imported. See ValidationErrors in returned object for details

When Posting Bookings to TSP, as from Influence version 1.00.24.250 the following is now in place:

In the Working Pattern, we first try to group by each Rate used for the booking and within that group specify which days of the week are relevant to that rate.
This works fine until you have multiple instances of the same rate on a particular day. i.e. a shift that starts with DAY rate, breaks into NIGHT rate and finishes up with a couple hours at DAY rate.

In this case, Influence will purposely create a NEW timesheet line in TSP for the second instance of this particular rate, meaning multiple rows for the same rate in TSP. This is absolutely necessary as you need to be able to account for this same rate being used twice with two different start and end times.

Result in TSP - We only see HBNIGHT twice as this rate is used twice. All other rates only have a single line in the booking if there are only one instance of this rate on any given day.

Issue 18: Posting separate Companies with the same name

Users may encounter such an error when posting Bookings or Contracts

This is more common when there are multiple Companies create for the same hospital but have separated each 'branch' into separate Clients. TSP will create Client records using the ACCOUNT NAME. All Companies on Influence must have a different Account Name:

See below screenshot - each main Site for each Client must have a unique name.

Don't have multiple Clients with the same Client name, even if the branch name is different for each main site.

Other 'troubleshooting items will be added here as/when they are discovered.

Issue 19: Days on Timesheets on TSP with working times on despite no booking for the day(s) in Influence

Example - Below dates included Mon 14th and Tuesday 15th on TSP.

But in Influence there are no bookings on the 14th or 15th for the particular worker:

This is because the same booking ID 1000010428 has been used for multiple weeks where there have been different days worked each week, i.e. a different working pattern (TSP terminology). TSP should only have one set weekly pattern per Booking ID.

Solution - Make a Booking for one week at a time in Influence. You can use the copy and paste function on the Planner (easier to do this for one candidate at a time) to copy bookings over to multiple weeks. This will ensure there is a new Booking ID for each week, which they allows users to chop and change the days each week as necessary.

Attachments (25)