In Caspeco some users will have multiple accounts, if they work at multiple locations. They will however have the same userID, email (and CPR) across the accounts.

The above information being identical across the accounts should allow the Caspeco users to be treated as a single Ziik user.

Requirements in Ziik

You need to be a platform administrator to set-up integrations in Ziik.

Requirements in your Caspeco site

You will need to:

Have access to setup webhooks.
Have access to information about the various users
Have a data quality that allows the expected behaviour; This is especially relevant, if you have multiple Caspeco sites, which you want to integrate with the same Ziik site. E.g. using the same email across multiple sites, but for different users, will cause issues.

Setting up the integration

This explains, step by step, how to set up an integration between Caspeco and Ziik.

Step 1:
Go into Ziik and start the process of creating a new integration; Ask to create a Caspeco integration and copy the “Endpoint URL”; You’ll need that for Caspeco.

2023-02-01_11-46-18

Press + create integration and select Caspeco

2023-02-01_11-49-40

Step 2:
Webhooks must be created. Caspeco needs to be told to send events to Ziik’s endpoint.
The shared secret must be saved for use in Ziik. “System” will also be used in Ziik.

Step 3:
The integration must be defined. As part of setting up the integration in Ziik, the shared secret and “System” must be input and saved. Once everything is saved correctly, make sure the integration in Ziik is “enabled”, as this is needed for the integration to be actively used.

You will also have to perform a mapping of data from Caspeco's Professions, to Ziik’s Roles. Caspeco has data roughly equivalent to Ziik’s Role, but the names might not match exactly, or multiple professions might need the same Role in Ziik. Or a profession might need multiple Roles when synchronised into Ziik.

Therefore you must add Caspeco’s professions to the fields of Ziik Roles, which have been made available in Ziik. All mappings that you want to effectuate, must be performed in the integration, even if the names match.
(See the Vocabulary section, for a translation between the systems.)

2023-02-01_12-24-03

Step 4:
The integration must be initiated in Caspeco, to enable Ziik to identify change requests on existing users. Otherwise, only new users created in Caspeco, will be synchronised with Ziik.

Vocabulary

Ziik	Caspeco
Admin
User
Unit	Business Unit (Organisationstillhörighet)
Usertype	Job role / Profession (Yrke)
Email	Private Email
Email	Work email
Department Is simply used to organise the units contact list in Ziik
NA	Job profile (Defines the learning modules for the user)
NA	Station
User Reference / External Id	Employee Id

Pre-conditions for exporting user data from Caspeco

Ziik	Caspeco	Comment
Active subscription	Active subscription
Unit	BusinessUnit	The value must be identical in both platforms, as matches will be done by comparing names.
Usertype	Job role / Profession	You have access to information regarding expected connection between values in Caspeco and Ziik. E.g. Chef in Caspeco should match Employee in Ziik.
Email	Email	Unique Identifier, but only used during “create user requests”, to enable mapping with the existing user in Ziik.
First name	First Name
Last name	Last Name
User.Reference	EmployeeId	Unique Identifier

How export of users from Caspeco are handled in Ziik

Creation, updating and deletion of users will happen in Ziik when Ziik is notified by Caspeco via their webhooks.

Create User

	Information present	What happens (Any rejection will see the entire call rejected)	After the call in Ziik, if call did not get rejected.
Always	Caspeco user id present	OK	If an existing user was found, based upon the Caspeco user id supplied, or the email supplied, then this “creation” will not create a new user; Instead this information will overwrite the names, email and reference for the user found and a connection to this integration will be added to the user. If no existing user was found, then a new user will be created with the names, reference and email supplied and a connection will be created to this integration.
	Caspeco user id present and maps to user in Ziik; Even if a connection between the user and the integration does not exist, the user having the Caspeco id in their “reference” field will allow finding the user.	OK
	Caspeco user id missing	Gets rejected
	Invalid email	Gets rejected
	Missing email	Gets rejected
	Valid email, already in Ziik; Even if a connection between the user and the integration does not exist, the user having this email will allow finding the user.	OK
	Valid email	OK
	Missing firstname	Gets rejected
	Firstname present	OK
	Missing lastname	Gets rejected
	Lastname present	OK
	CreatedBy->Type missing	OK
	CreatedBy->Type present but does not equal “Clock	OK
	CreatedBy->Type present and equals “Clock”	N/A (Instead see “time clock” Create User table.)
	No employments	OK
For every employment present, that the user is expected to get.	BusinessUnit missing	Gets rejected	Every employment supplied here, was added to the user.
	BusinessUnit not mapped to Ziik Unit	Gets rejected
	BusinessUnit mapped to Ziik Unit	OK
	Profession missing	Gets rejected
	Profession not mapped to Ziik Role	Gets rejected
	Profession mapped to one or more Ziik Roles	OK

Create user - Timeclock

	Information present	What happens (Any rejection will see the entire call rejected)	After the call in Ziik, if call did not get rejected.
Always	Caspeco user id present	OK	If an existing user was found, based upon the Caspeco user id supplied, or the email supplied, then this “creation” will not create a new user; Instead this information will overwrite the names, email and reference for the user found and a connection to this integration will be added to the user. If no existing user was found, then a new user will be created with the names, reference and email supplied and a connection will be created to this integration.
	Caspeco user id present and maps to user in Ziik; Even if a connection between the user and the integration does not exist, the user having the Caspeco id in their “reference” field will allow finding the user.	OK
	Caspeco user id missing	Gets rejected
	Invalid email	Gets rejected
	Missing email	Gets rejected
	Valid email, already in Ziik; Even if a connection between the user and the integration does not exist, the user having this email will allow finding the user.	OK
	Valid email	OK
	Missing firstname	Gets rejected
	Firstname present	OK
	Missing lastname	Gets rejected
	Lastname present	OK
	CreatedBy->Type missing	N/A (Instead see standard Create User table.)
	CreatedBy->Type present but does not equal “Clock OK	N/A (Instead see standard Create User table.)
	CreatedBy->Type present and equals “Clock”	OK
	No employments	OK
For every employment present, that the user is expected to get.	BusinessUnit missing	Gets rejected	Every unit supplied here, was added to the user. But all professions are ignored.
	BusinessUnit not mapped to Ziik Unit	Gets rejected
	BusinessUnit mapped to Ziik Unit	OK
	Profession missing	OK
	Profession not mapped to Ziik Role	OK
	Profession mapped to one or more Ziik Roles	OK

Enabling / disabling

	Information present	What happens (Any rejection will see the entire call rejected)	After the call in Ziik, if call did not get rejected.
Always	User enabled/disabled status present	OK	Determines whether we’re trying to re-create a user or delete a user in Ziik. Since Ziik does not actually support “deactivated users”, this needs to be able to either create/delete a user, based upon the information in the call.
Always	User enabled/disabled status missing	Gets rejected
If enabling the user	Caspeco user id present and maps to user in Ziik; Even if a connection between the user and the integration does not exist, the user having the Caspeco id in their “reference” field will allow finding the user.	OK	This information will overwrite the names, email and reference for the user found and a connection to this integration will be added to the user, if it doesn’t already have such a connection.
	Caspeco user id present, but does not map to user in Ziik	Gets rejected
	Caspeco user id missing	Gets rejected
	Invalid email	Gets rejected
	Missing email	Gets rejected
	Valid email	OK
	Missing firstname	Gets rejected
	Firstname present	OK
	Missing lastname	Gets rejected
	Lastname present	OK
	No employments	OK
If enabling the user, then for every employment present, that the user is expected to get.	BusinessUnit missing	Gets rejected	Every employment supplied here, got stripped from the user.
	BusinessUnit not mapped to Ziik Unit	Gets rejected
	BusinessUnit mapped to Ziik Unit	OK
	Profession missing	Gets rejected
	Profession not mapped to Ziik Role	Gets rejected
	Profession mapped to one or more Ziik Roles	OK
If disabling the user	Caspeco user id present and maps to user in Ziik	OK	If the user was not mapped to any other Caspeco integration, then the user was soft-deleted in Ziik. If the user was mapped to another Caspeco integration, then that connection was severed. (A soft deleted user can be enabled again. But upon getting soft-deleted their email will be stripped from the user and the user won’t be able to log in. After a 90 day retention period, the user will be anonymised and stripped of most data in Ziik, including memberships and groups, although any connections to Caspeco integrations will be retained.)
	Caspeco user id present, but does not map to user in Ziik	Gets rejected
	Caspeco user id missing	Gets rejected

Updating user

	Information present	What happens (Any rejection will see the entire call rejected)	After the call in Ziik, if call did not get rejected.
Always	Caspeco user id present and maps to user in Ziik; Even if a connection between the user and the integration does not exist, the user having the Caspeco id in their “reference” field will allow finding the user.	OK	The information passed from Caspeco (if any for the corresponding field) was allowed to overwrite the users current information. The users “reference” was overwritten with their Caspeco id. If an email was supplied, then their email will have been updated. If names were sent, then the names sent were updated.
	Caspeco user id present, but does not map to user in Ziik	Gets rejected
	Caspeco user id missing	Gets rejected
	Invalid email	Gets rejected
	Missing email	OK
	Valid email	OK
	Missing firstname	OK
	Firstname present	OK
	Missing lastname	OK
	Lastname present	OK
	No employments	OK
For every employment present, that the user is expected to already have, but get modified.	BusinessUnit missing	Gets rejected	Every employment supplied here, got stripped from the user.
	BusinessUnit not mapped to Ziik Unit	Gets rejected
	BusinessUnit mapped to Ziik Unit	OK
	Profession missing	OK
	Profession not mapped to Ziik Role	Gets rejected
	Profession mapped to one or more Ziik Roles	OK
	BusinessUnit and Professions combination, does not already belong to user	Gets rejected
For every employment present, that the user is expected to get.	BusinessUnit missing	Gets rejected	Every employment supplied here, was added to the user.
	BusinessUnit not mapped to Ziik Unit	Gets rejected
	BusinessUnit mapped to Ziik Unit	OK
	Profession missing	Gets rejected
	Profession not mapped to Ziik Role	Gets rejected
	Profession mapped to one or more Ziik Roles	OK

Editing employment

	Information present	What happens (Any rejection will see the entire call rejected)	After the call in Ziik, if call did not get rejected.
Always	Caspeco user id present and maps to user in Ziik; Even if a connection between the user and the integration does not exist, the user having the Caspeco id in their “reference” field will allow finding the user.	OK	The user will have lost the corresponding UnitMembership(s).
	Caspeco user id present, but does not map to user in Ziik	Gets rejected
	Caspeco user id missing	Gets rejected
For every employment present.	BusinessUnit missing	Gets rejected
	BusinessUnit not mapped to Ziik Unit	Gets rejected
	BusinessUnit mapped to Ziik Unit	OK
	Profession missing	Gets rejected
	Profession not mapped to Ziik Role	Gets rejected
	Profession mapped to one or more Ziik Roles	OK
	BusinessUnit and Professions combination, does not already belong to user	Gets rejected

Deleting user

	Information present	What happens (Any rejection will see the entire call rejected)	After the call in Ziik, if call did not get rejected.
Always	Caspeco user id present and maps to user in Ziik; Even if a connection between the user and the integration does not exist, the user having the Caspeco id in their “reference” field will allow finding the user.	OK	If the user was not mapped to any other Caspeco integration, then the user was soft-deleted in Ziik. If the user was mapped to another Caspeco integration, then that connection was severed. (A soft deleted user can be enabled again. But upon getting soft-deleted their email will be stripped from the user and the user won’t be able to log in. After a 90 day retention period, the user will be anonymised and stripped of most data in Ziik, including memberships and groups, although any connections to Caspeco integrations will be retained.)
	Caspeco user id present, but does not map to user in Ziik	Gets rejected
	Caspeco user id missing	Gets rejected

Integration Log

You can access the integration log direct from you integration admin panel.

Caspeco Documentation

https://cloud.caspeco.se/public/support/faq/3309895685

User Synchronisation Troubleshooting

User misses Role and Unit in Ziik

Ensure that person is created in Caspeco
Ensure that person only has one active employment in Caspeco (Per system)
Ensure that “Profession” and “Organisational belonging” in Caspeco exist in the integration setup within Ziik.
If these steps are covered, contact Ziik support:
- Provide a picture of the employee and the employment from Caspeco
- Provide user name and intended destination “unit XYZ” and “profession ABC”
If you need more information about the synchronization process, you can refer to the integration log.