Quick Links

Integration Setup

Shift Setup in Quinyx

Controlling the Online Booking Option

Wards and Teams

Marking an Absence

Remember Synchronisation and Saving

Error Logs

Introduction

Quinyx is a workforce management and scheduling software. Provet Cloud integrates with Quinyx so that staff shifts can be managed in Quinyx. The integration fetches the shifts from Quinyx to Provet Cloud, but managing the shifts continues on the Quinyx side. HR Gateway Portal, a third element developed by the Provet Cloud team, is used to map Quinyx and Provet Cloud shifts with each other and manage the integration.

NOTE: This guide assumes that you have already completed your Quinyx account setup and implementation and are using the system.

Integration Setup

1. Get Quinyx API key and the portal credentials.

1. Contact Quinyx support and ask for the root unit API key for Provet Cloud integration.
2. Forward the key to your Provet Cloud contact.
3. The contact will make necessary adjustments and returns to you with the HR Gateway Portal address (URL) and login credentials. You will need these in the next steps.

2. Set employee numbers.

For the integration to work, you must make Provet Cloud employee numbers to match with the badge numbers in Quinyx.

For each employee who needs to be involved:

1. Go to the People page in Quinyx.
2. Find the desired employee.
3. Find the Badge number.
4. Go to Settings > Users in Provet Cloud.
5. Edit the corresponding user in Provet Cloud and add the badge number to the Employee number field.

3. Ask users to restrict appointments outside shifts (OPTIONAL).

When editing or removing shifts from Quinyx, the corresponding shift on the Provet Cloud side will also be updated or removed. That shift may already have some appointments on it, and orphan appointments may happen when this is not restricted. With the restriction, a corresponding error will appear on the HR Gateway Portal Log page (described below).

For this restriction, users need to edit their profiles in Provet Cloud:

1. Go to your User Profile from the top-right menu in Provet Cloud.
2. Open the profile for editing.
3. Tick the option No scheduling outside shifts.
4. Save.

4. Configure the organisation settings.

From this step forward, you will need access to the HR Gateway Portal with the URL mentioned in step 1. Once you log in, you should be directed to the organisation settings automatically. If not, navigate to Settings > Organization in the HR Gateway Portal.

Configure the following settings. Note that some may already be configured by your Provet Cloud contact - in that case, leave them as is. Also, some of the settings may be set to read-only, which is normal.

Integration enabled: This must be checked for the integration to work.

Notification recipient emails: Select emails that should receive notifications about errors related to appointments and shifts in Provet Cloud. This is organisation-specific, meaning that if there is an error in any of your departments (locations), the recipients will get an email about this.

NOTE: In case of an error, the related action will not be performed.

Timezone: The timezone in Quinyx, HR Gateway Portal and Provet Cloud must match.

Import interval: Set the frequency of automated shift imports per day. The suggested default is 'Every 24 hours', in which case, the import will run automatically once per day around midnight. A 'Manual' option is also available. The import is not automated then, but will have to be done manually from the department (location) settings in the HR Gateway Portal.

Input system URL: Mandatory, usually configured by your Provet Cloud contact.

Input system API key: Mandatory, usually configured by your Provet Cloud contact.

Output system URL: Mandatory, usually configured by your Provet Cloud contact.

Output system API key: Mandatory, usually configured by your Provet Cloud contact.

To finalise:

1. Select Save settings.
2. Select Synchronize all data.

NOTE: The synchronisation button will not be visible unless all mandatory fields are filled.

5. Configure the department settings.

After synchronisation, your departments (locations) should appear in the left menu. Select a department from the menu on the left and configure the following required settings. Note: Configure all the required settings before you enable the integration.

1. Quinyx departments: Select the department in Quinyx that you want to map with the selected Provet Cloud department.
2. Select Save main settings.
3. Shift type mapping: Map Quinyx shifts to Provet Cloud shift types displayed on the left. The names of the shifts in Quinyx and Provet Cloud do not have to be identical.
   
   • If the shift should allow online booking, map it using the 'Shift type for online booking' column.
   • If the shift is a regular shift, map it using the 'Quinyx Shift type' column.
4. Select Save subsettings from the bottom of the page.
5. Import period type: Choose between fixed dates and fixed length.
   
   • Fixed dates - Shifts from the selected date range will be imported. When doing initial tests (described below), it is recommended to use this option with one day as the date range. Both days are included. Note that the import will only be done for future dates.
   • Fixed length - Define a duration starting from the current date. The shifts from within the duration will be imported.
6. Integration enabled: Enable the integration by checking the respective setting at the top of the page.
7. Select Save main settings.

Overview of Other Department Settings

Notification recipient emails: Similar to the organisation setting, this setting allows sending error notifications to selected emails, but in this case, only about errors that happen in the selected department.

Wards and teams enabled: Allows mapping and importing ward and team information and enables the options Wards mapping and Teams mapping.

Duration of a slot in use: Allows splitting shifts into smaller, equally sized blocks when they are imported into Provet Cloud. Has the same effect as the 'Duration of a slot' checkbox in Provet Cloud calendar. Note that the slot durations also have to be mapped at the bottom of the settings page, if they are in use.

Calendar slot size: Used together with the duration setting mentioned above.

Import only published shifts: Enabled by default and recommended. If enabled, unpublished (draft) shifts will not be imported from Quinyx.

6. Test the integration.

A simple testing workflow is suggested here. Note that the real setup scenario usually involves a broader importer date period, so make sure to reconfigure before the real use.

1. Create a test user in both Provet Cloud and Quinyx and link them with the badge number as described above.
2. In the HR Gateway Portal, set the department Import period type to 'Fixed dates' and set the start and end dates to be on the same day, some freely selected day from the future. Remember to Save main settings.
3. Plan a shift for the test user in Quinyx for the selected date. The shift structure must follow the requirements mentioned below.
4. Publish the test user's schedule in Quinyx. NOTE: When publishing, you can set the publishing date - it should never be put into the past.
5. In the Portal, select Manually import shifts from the department settings. A short loading process will take place.
6. The imported shift should now appear in Provet Cloud. Check that the shift type is correct to verify that the mapping was done correctly.

If this initial test is successful, it is recommended to gradually increase testing complexity to iron out any issues and arrive at the real use case:

1. Test all shift types with the test user.
2. Test with real users, using a real scenario, but one-day setup as in the initial test.
3. Increase the period to one week and test again.
4. Switch to the full setup and automation. Make sure to plan the switch well ahead and communicate with all needed staff members.

Appropriate testing should be performed after any changes to the integration setup.

Shift Setup in Quinyx

The shifts that arrive in Provet Cloud through the integration are actually Tasks under the shifts in Quinyx.

In the image below, the tasks marked with green and red colours would be imported into Provet Cloud as shifts, if the Quinyx shift is appropriately mapped. If the Quinyx shift is left 'empty' with no tasks, nothing is imported into Provet Cloud.

It is recommended that the relevant shift types are designed in Quinyx so that they already have the needed tasks.

After the import, the resulting shifts look as below. Note that the 'Lunch break' shift was not created because it was not mapped.

Controlling the Online Booking Option

Imported Shift That Has Online Booking Enabled

If you need a shift type where Provet Cloud's online booking functionality is enabled, follow these steps:

1. In Provet Cloud, ensure that you have the shift type set up with online booking enabled.
2. Create the corresponding shift type in Quinyx.
3. Go to the HR Gateway Portal and open the department settings.
4. Map the shift types to each other using the Shift type for online booking column.
5. Select Save subsettings at the bottom of the page.

Imported Shift That Sometimes Has Online Booking Enabled

In some cases, you may want to regularly decide on the Quinyx side whether the shift has online booking enabled or not. In that case, set up mapping so that the Provet Cloud shift is mapped to two similar Quinyx shifts depending on the online booking choice.

1. In Provet Cloud, ensure that you have the shift type set up with online booking enabled.
2. In Quinyx, create two similar shifts and name them so that you can recognise which one is meant for online booking. For example:
   • Workday no online booking
   • Workday
3. Go to the HR Gateway Portal and open the department settings.
4. Map the Quinyx shifts to the Provet Cloud shift:
   • Workday no online booking - Quinyx Shift type column
   • Workday - Shift type for online booking column
5. Select Save subsettings at the bottom of the page.

After the setup, when you book shifts in Quinyx, select the appropriate type to make the decision. Depending on the choice, the shift will have online booking enabled in Provet Cloud or not.

NOTE: Appropriate testing should be performed after any changes to the integration setup.

Wards and Teams

If the department (location) uses teams and/or wards, the integration can be used to select them for Provet Cloud shifts that are imported. Wards can be used independently, but teams require using wards since they are a sub-unit of a ward.

1. Enable wards and teams from the portal.

1. Go to the HR Gateway Portal and open the department settings.
2. Enable Wards and teams enabled. This can be done during the initial setup, too.
3. Decide the ward information source in Quinyx using the Ward source menu. The recommended option is 'Main shift's section field'.
4. Decide the team information source in Quinyx using the Team source menu. The recommended option is 'Main shift's category field (shift type)'.
5. Select Save main settings.

2. Configure the sources in Quinyx.

The sources selected in step 1 need to be created and/or configured in Quinyx.

To configure a main shift's section field (for the ward source):

1. Go to Account settings from the personal menu in Quinyx.
2. Select Group management from the left menu panel.
3. Select the needed unit from the middle. A configuration panel will open.
4. Select Add sections from the panel.
5. Fill the section fields with the ward information.
6. Select Ok to save.

Once wards are created as sections, they appear as options under the main shift's Section field (image below).

To configure a main shift's shift type (for the team source):

1. Go to Account settings from the personal menu in Quinyx.
2. Go to Shift types from the left menu panel.
3. Select Add from the top right.
4. Create the team as a shift type by filling in the Name field and making sure that the duration covers (start and end time) the normal time frame of the shifts.
5. Select Save.

3. Map wards and teams in the HR Gateway Portal.

This step assumes that you already have wards and teams set up in Provet Cloud as needed.

Mapping wards:

1. Go to HR Gateway Portal and open the department settings.
2. Scroll down to the Wards mapping section.
3. For each Provet Cloud ward, map a Quinyx Ward.

Mapping teams.

1. Scroll to the Teams mapping section in the portal department settings.
2. For each Provet Cloud team, map a Quinyx Shift type (category).

To finalise, select Save subsettings at the bottom of the page.

Testing and Usage

If configured as described above, the wards and teams can now be indicated when creating shifts in Quinyx.

Make sure to test the setup with the test user as described above.

In conclusion:

1. The shift information itself comes from the Tasks.
2. The ward information comes from the Section.
3. The team information comes from the Shift type.

Marking an Absence

Sometimes, an employee's shifts have already been planned and imported to Provet Cloud, but due to their absence, the shifts must be updated (removed).

To mark an absence:

1. Make sure that related appointments in the Provet Cloud calendar have been moved or removed first.
2. Go to the Schedule in Quinyx.
3. Find the shift and select it.
4. Select More options.
5. At the bottom of the dialogue, select Add absence.
6. Fill out the absence form and select Save. The shift will be moved to the 'Unassigned shifts' section.
7. Delete the shift from the 'Unassigned shifts' section. This is important because otherwise the shift will not be removed from Provet Cloud, which will happen during automatic or manual import.

Synchronisation and Saving

Whenever configuration changes are made in Provet Cloud or Quinyx that have an effect on shifts, wards or teams, the changes must be synchronised in the HR Gateway Portal.

1. Go to the Organization settings in the HR Gateway Portal.
2. Select Synchronize all data.

Examples of cases where synchronisation is required:

• A shift type is created or edited in Provet Cloud.
• A department is created in Provet Cloud.
• A ward is created or edited in Provet Cloud.
• A shift type is created or edited in Quinyx.
• A unit is created in Quinyx.
• A section is created or edited in Quinyx.

Whenever changes are made in the HR Gateway Portal, the changes must always be saved with Save settings, Save main settings and Save subsettings on the respective pages.

Whenever changes are made to the mappings in the Portal, they should be tested as described above. Testing can save a lot of work, because incorrectly imported shifts have to be removed manually.

Error Logs

In the HR Gateway Portal, there is a Log tab in the top menu bar which provides detailed information about input and output errors. The log sections are organisation-wide, meaning errors from all departments are listed in them.

Input errors - Errors related to issues connecting to Quinyx. Input errors are rare and they usually require assistance from Provet Cloud support.

Output errors - Errors related to shift import into Provet Cloud. These are more common, related to incorrect mappings, missing employee numbers and such.

When people receive error notifications via email, as described above, it is advisable to first check the error logs, especially the output errors.

The search field in the log can be used to filter entries by:

• Department name
• Database shift ID
• Quinyx shift ID
• Error code
• Person ID / Employee number

To see detailed information about an error, select Show error message.

See Also

Troubleshooting

Updated 11 January 2024 05:48