❕

Required query parameters for global values and sets.

• companyUid - Uid of a platform.
• globalValueUid - Uid of a global value.
• globalValueSetUid - Uid of a global value set.
• employeeUid - Uid of an employee.

Global values and sets

Global values and sets are a core part of Zenegy's logic and, if used correctly, can help ensure consistency and accuracy in employee profiles.
Using Global values and sets can simplify and automise the work of creating employee profiles and salary profiles by quickly assigning specified values to individual properties.

Understanding Global Values

Global Values are values associated with specific properties within an employee's profile. Not all properties can be used with global values, and the properties that can use global values do not have to use them.

It is up to each company to choose how they wish to use global values, they can not use them at all and stick with manual input of values, they can use global values on all properties possible, or they can mix global values and manual input if they wish.

Understanding Global Value Sets

A global value set is a collection of global values. One set can be assigned to a single employee, and the global values added to the set will be assigned to each of the corresponding properties.

Each company can set up its own global value sets and, like global values, can mix them as much as it wants. A set does not need to include all properties, so it is possible to have a profile with an assigned set but where some properties have global values not in the set or manual inputs mixed into the data as well.

Assigning Global Values or Sets to Employee Profiles

Several methods are possible when using the API to assign global values to an employee profile, any party using the Zenegy API, should make sure that they know exactly how they choose to handle assigning values, and evaluate which method is best.

To assign Global Values and Sets, a valid Uid of either a set or value is required; this Uid can be read via:

• Get global value sets.
• Get global values.

Both endpoints will return a list of sets or values. This means that the best practice for assigning values and sets is to store the UIDs in use within the service using the API.

Assigning sets during the creation of a profile

It is possible to assign a global value set to an employee profile during creation by adding the set's Uid to the creation request body.
Once the set's UID is known, it should be defined as the value of the property "GlobalValueSetUid" in the request body for the post employee request.

"GlobalValueSetUid": "4b9e6fe7-c6a2-4532-8c16-d684696efa48"

Assigning to existing employees

🚧

Assigning Values and Sets to existing profiles

Assigning sets and values to exisisting profiles should only be done, if the properties beeing assigned is not already using a global value, or if the profile does not already have a set defined.
Overriding global values or sets is not possible, if attempted via the API the response will not contain any error, but the data for the profile will remain the same.

When a profile needs to be change to a new global value or set it should to go though the resignation flow

Assigning values to a profile can be done via several different endpoints. The endpoint to use depends on what is needed. However, it is advised to only assign a single value to a single employee per call to prevent errors or incorrect assigning.

The third-party using the API to assign values should also decide whether assigning global values individually or assigning sets is preferred, and all users using Zenegy with the integration should be informed about how the third party uses global values and sets.

🚧

Choosing sets or values

It is adviced to utilize global value sets instead of individual values, as this prevents possible errors and wrong assignments, as well as limiting the amount of requests needed to add data to a profile.

If Global values and sets are managed via the API, evaluate first how assigning sets could work, and use indvidual values as a backup option.

Assigning sets

Assigning a set to an existing profile can be done using several methods. The endpoint to use should depend on the third party's needs, and this decision should be evaluated before using the integration.

The endpoint for assign employees to set allows you to assign several employees to a set.
This endpoint should be used when employee profiles are originally created without a defined set and should get a set assigned after creation. The endpoint uses bulk logic and is recommended for integrations that handle assigning a set to several employees per call.

Assigning a set to a specific employee can be done via our PATCH method.

PATCH employee.

This endpoint should be used in cases where other changes are also done to the profile at the same time, but it is not advised to use this endpoint if the only change is the global value set.

Example of JSON request body for assigning global value set:

[
    {
        "value": "4b9e6fe7-c6a2-4532-8c16-d684696efa48",
        "path": "/GlobalValueSetUid",
        "op": "replace",
    }
]

Assigning individual values

Assigning individual values can be done via 2 endpoints, these endpoints allows for bulk assigning of employees to value and individual assigning to value, the third party should make sure to evaluate their flow and use the best endpoint possible for their flow.

Assigning individual values should always be a backup option; Zenegy advises assigning sets whenever possible.

The endpoint for assign global value to employee allows you to assign individual employees a specific global value.
The endpoint for assign employees to global value allows for bulk assigning of employees to a specific global value.

All the properties listed above can use Global Values from the assigned GVS, allowing for standardised and streamlined management of employee profiles within the Zenegy system.

Unassign Global Values and Sets

🚧

Not standard logic

Manually unassigning values and sets should never be the used as standard logic in integrations using the Zenegy API, usage of this functionality should be as limited as possible.
Incorrect usage of this functionality can cause errors when running payrolls, as well as errors in the employees payslip.

Integrating services are advised to handle switching and unassigning via the resignation flow.

In some cases, unassigning a value or set might be necessary; for example, if a value or set on an employee needs to be changed, unassigning the value or set is necessary.

Unassigning values can be done via the endpoint for remove employees from global value.
Once the value has been unassigned, a new value can be added as hard manual input or by assigning a new global value.

Unassigning sets can be done via the endpoint for remove employees from global value set.
This will unassign all values from the set, and properties will now need to be defined via manual input, assigning individual values, or by assigning a new set.