#Manage Connections

Refer to the following sections for detailed instructions on how to manage your connections.

#Create a Connection

Refer to the following steps to create a connection:

1. Click Create connection > Create new connection to open the Create connection window.

2. Connection name – Enter a name for the connection.

3. Description – Enter an optional description.

4. Source HR system – Currently, only AFAS Profile is supported.

5. Destination tenant type – Select the destination tenant type, either Cloud or Hybrid.

6. Click Create to create the connection.

#Copy from Another Connection

Refer to the following steps to create a connection by copying from another connection:

1. Click Create connection > Copy from another connection to open the Copy from another connection window.

2. Connection name – Enter a name for the connection.

3. Description – Enter an optional description.

4. Copy from – Select a connection to copy from.

5. Click Next.

6. Add tenant – Select a customer and click Continue.

7. Select a tenant of the customer.

8. If the APElements Security and Analysis app for the tenant has already been consented, an app consented icon will appear.

   If the APElements Security and Analysis app for the tenant needs to be consented, click Authenticate. The permissions required for this app are displayed. Review the permissions and click Accept. For the list of permissions required by the app, refer to App Permissions Required by Other Premium Services.

9. Click Save.

#Configure a Connection

After creating a connection, click the connection name to open the Connection details page, and then complete the 5-step configuration process. There is a progress bar showing your current step in the process.

You may return to any previous step to review its configurations. Please note that modifying configurations in a specific step resets the connection configuration progress to that point. As a result, you will need to complete all subsequent steps again before you activate the connection and set a synchronization schedule.

#Step 1: Configuration

This is the initial step to configure the connection. In the Source HR system configuration section, you need to provide the connection details to the HR source system. These details can be obtained from the source HR system:

• Environment ID – Specifies the target AFAS environment to connect to.

  1. Log into your AFAS backend administration console.

  2. Navigate to Environment Settings.

  3. Locate and copy the unique environment ID (typically starts with T for test and P for production).

  4. Enter the ID precisely into the field.

• Environment type – Specifies the target AFAS environment type:

  • Test – Used for testing and development purposes. It contains non-sensitive, sample data and is ideal for validating configurations without impacting real employee data.

  • Accept – Used for acceptance testing. It contains data that closely mirrors the production environment and is used to validate changes before they are deployed to production.

  • Production – Used for live operations. It contains real employee data and is used for day-to-day HR operations.

• Authentication token – Provides secure, authorized access to the AFAS REST API for data retrieval.

  1. In AFAS, go to Settings > API Management > Tokens.

  2. Generate a new token with the Read permissions for HR-related data connectors.

  3. Copy the generated token string immediately, as it may not be displayed again.

  4. Securely store and enter this token into the field.

• Primary connector – Defines the main AFAS data source from which employee records will be extracted.

  1. Verify the correct connector name with your AFAS administrator.

  2. Enter the exact connector name into the field.

• Employee ID column – Specifies the field in AFAS that contains the unique identifier for each employee.

  1. Identify the exact column containing unique employee IDs.

  2. Enter the exact column name (case-sensitive) into the field.

• Object ID column – Specifies the field representing organizational units, such as departments or cost centers.

  1. Identify the organizational structure column.

  2. Enter the exact column name into the field, or leave blank if not needed.

• Display name column – Specifies the field whose value will be used as the employee's display name in the target system.

  1. Identify the column in AFAS that contains the preferred display format for employee names.

  2. Enter the name of the chosen column into the field.

• Include contract information – Determines whether employment contract data should be synced alongside basic employee information. After enabling this setting, additional fields will appear to specify where contract information is stored in AFAS:

  • Contract connector – Specifies the AFAS connector that contains the contract information.

    1. Consult with your AFAS administrator to identify the correct connector for contract data.

    2. Enter the exact connector name into the field.

  • Contract display-name column – Specifies the column showing contract identifier.

    1. Within the contract connector, identify the column that best describes the contract.

    2. Enter the exact column name into the field.

  • Contract start-date column – Specifies the column containing the official start date of employment contracts. Ensure the date is in ISO format (YYYY-MM-DD) for compatibility.

  • Contract end-date column – Specifies the column containing the official end date of employment contracts. Ensure the date is in ISO format (YYYY-MM-DD) for compatibility.

#Step 2: Property Mapping

This step is to map HR source fields to destination AD attributes. Make sure each required AD field is mapped correctly to avoid sync failures.

Mapping rules are used in this step to extract and process information from the source user object. For the mapping rule configurations, refer to Mapping Rules.

#Variables

Create variables that act as placeholders for your source data fields. These variables enable dynamic mapping to target system properties for user names and user properties.

To add a new variable, click Add and select Add variable. Enter a name for your variable and configure the source property to define where the data originates, select the Is mandatory checkbox if a value is required for the operation to proceed, and click Save.

To add a predefined variable, click Add and select Quick add. Select the desired variable and click Save.

To copy variables from another connection, click Add and select Copy from another connection. Select a connection to copy from, select the variables you want to copy, and click Add.

To edit a variable, click the Edit button next to the variable. Make your updates and click Save to apply the changes.

To delete a variable, click the Delete button next to the variable.

#User Names

This section includes user display name mapping, mailnick name mapping, and UPN mapping. You can configure mappings to establish the connection between source and destination user names.

To edit a mapping, click the Edit button next to it to enter the editor mode. Make your updates and click Save to apply the changes.

#Properties

Configure property mappings to establish the connection between source and destination user attributes.

To add a property mapping, complete the following steps:

1. Click Add and select Add property.

2. Description – Enter an optional description.

3. Source property – Configure the property from which the data will be sourced

4. Destination property – Select the target property where the data will be written.

5. Update behavior – Define how updates are applied to the destination fields during synchronization.

   • Is mandatory – If enabled, the sync job will fail with an error when the source property is missing or empty.

   • Allow empty – If enabled, the value in the destination field will be cleared when the source value is empty.

   • Allow override – If enabled, the value from the source will overwrite any existing value in the destination during the sync.

6. Click Add.

To copy properties from another connection, click Add and select Copy from another connection. Select a connection to copy from, select the properties you want to copy, and click Add.

To edit a property, click the Edit button next to the property. Make your updates and click Save to apply the changes.

To delete a property, click the Delete button next to the property.

#Step 3: Behavior Condition

This step is to define rules that determine which users are included and specify how actions or behaviors are applied.

Mapping rules are used in this step to extract and process information from the source user object. For the mapping rule configurations, refer to Mapping Rules.

#Scope Filter

The scope filter determines which employees are included in the synchronization by defining a scope condition. Only employees who meet this condition will be synchronized. To include all employees, keep the default scope condition Constant Boolean: true unchanged.

To modify the scope condition and limit the employees to be synchronized, click the Edit button. Make your updates to the condition, and click Test to preview which users will be synchronized. If the results are as expected, click Save to apply the new scope condition.

#Creation

The creation filter determines which users will be created in the destination. To allow creation for all in-scope users, set the creation condition to Constant Boolean: true. To restrict user creation to specific employees, define custom conditions accordingly. To prevent user creation entirely, set the creation condition to Constant Boolean: false.

To modify the creation condition, click the Edit button. Make your updates to the condition, and click Test to preview which users will be created. If the results are as expected, click Save to apply the new creation condition.

#Deletion

The deletion filter determines which users will be deleted from the destination. To allow deletion for all in-scope users, set the deletion condition to Constant Boolean: true. To restrict user deletion to specific users only, define custom conditions accordingly. To prevent user deletion, set the deletion condition to Constant Boolean: false.

To modify the deletion condition, click the Edit button. Make your updates to the condition, and click Test to preview which users will be deleted. If the results are as expected, click Save to apply the new deletion condition.

#Activation/Deactivation

The activation/deactivation filter controls whether users will be activated (sign-in enabled) or deactivated (sign-in blocked) in the destination. Users will be activated when the specified condition is met, and deactivated when the condition is not met.

To modify the activation/deactivation condition, click the Edit button. Make your updates to the condition, and click Test to preview which users will be activated/deactivated. If the results are as expected, click Save to apply the new activation/deactivation condition.

#Manager Assignment

Manager assignment determines how managers from the source HR system are identified, matched, and assigned to users in the destination system.

• Manager identifier type – Select the identifier used to match managers, such as user object ID or user employee ID.

• Manager selector – Specify the method for identifying managers in the HR source data and assigning them to users in the destination system. To avoid assignment failures, verify that the corresponding manager records exist in the source HR system.

  To update the manager selector condition, click the Edit button. Make your updates to the condition, then click Test to preview the results. If the results are as expected, click Save to apply the new manager selector condition.

• Manager synchronization – Enable this setting to synchronize manager assignments, or disable it to skip manager synchronization entirely.

#Group Assignment

Group assignment determines how users are assigned to groups during the synchronization. This configuration consists of two parts:

• Groups – Rules that determine user-to-group assignments, including the following group types:

  • Constant group – All users are assigned to the group, regardless of their properties.

    Use this group type when every in-scope user should always be assigned to the same group. For example, assign all employees to an "All Staff" or "Everyone" group in the destination system.

  • Conditional group – Only users whose properties meet the specified criteria are assigned to the group.

    Use this group type when only specific users should be assigned to the group based on their properties. For example, you can assign users to a group based on their department, job title, or any other attribute available in the source HR system.

  • Relational group – A relational group has two key components: a collection and a source condition. The collection maps source identifiers from the HR system to their corresponding destination groups. The source condition defines which HR system property is used for the comparison. During synchronization, the system compares each user's HR property value with the source identifiers in the selected collection. When a match is found, the user is assigned to the corresponding destination group. You can configure collections and identifiers in the Group identifier tab.

    Use this group type when users should be assigned to groups based on identifiers specified in a collection.

• Group identifiers – Mapping tables that link source identifiers from the HR system to destination groups.

Add a Constant Group

Refer to the following steps to add a constant group:

1. Under the Groups tab, click Add and then select Constant group.

2. Destination group – Enter a name for the destination group.

3. Assign groups to deactivated users – Select the checkbox if you want to assign groups to deactivated users.

4. Comment – Enter comments.

5. Click Add.

Add a Conditional Group

Refer to the following steps to add a conditional group:

1. Under the Groups tab, click Add and then select Conditional group.

2. Destination group – Enter a name for the destination group.

3. Destination condition – Define the criteria for the conditional group.

4. Assign groups to deactivated users – Select the checkbox if you want to assign groups to deactivated users.

5. Comment – Enter comments.

6. Click Add.

Add a Relational Group

Refer to the following steps to add a relational group:

1. Under the Groups tab, click Add and then select Relational group.

2. Collection – Select a collection to specify the identifiers and the corresponding destination groups.

3. Source condition – Define the source condition by selecting the HR employee property that will be compared against the identifiers in the selected collection. This condition determines which property the system evaluates to find a match. After defining the condition, click Test to preview which users will be assigned to groups based on the current configuration.

4. Assign groups to deactivated users – Select the checkbox if you want to assign groups to deactivated users.

5. Comment – Enter comments.

6. Click Add.

Add a Collection

To add a collection, navigate to the Group identifiers tab, and click Add collection. Enter a name for the collection and click Add.

Copy from Another Connection

To copy from another connection, navigate to the Group identifiers tab, and click Add > Copy from another connection. Select a connection to copy from, select the group identifier mappings you want to copy, and click Add.

Edit a Collection

To edit a collection, navigate to the Group identifiers tab, and select the collection you want to edit. You can add one or multiple group identifier mappings to it.

To add a group identifier mapping to the collection, click Add > Add group identifier mapping. Specify the identifiers and destination groups, and click Add.

To edit a group identifier mapping, click the Edit button next to the mapping. Make your updates and click Save to apply the changes.

To delete group identifier mappings, select the mappings you want to delete and click Delete.

Delete a Collection

To delete a collection, navigate to the Group identifiers tab, and select the collection you want to delete. Click Delete and confirm the deletion.

#User Password Policy

Configure how initial passwords are managed for users created during synchronization:

• Send invitation link to employee's email – Sends an email invitation that allows the user to set their own password. You must specify the HR source field that contains the employee's email address for the invitation.

• Send initial password to manager – Sends a system-generated initial password to the employee's manager for distribution. The password is sent to the manager's Microsoft 365 email address. If that address is unavailable, it is sent to the next-level manager. To ensure delivery, verify that managers have valid Microsoft 365 email accounts.

• Send password directly – Sends a system-generated password directly to the user by email. Enter the destination email address for password delivery.

#Write-back Option

Specify whether updates made to users' user principal names and email addresses in the destination system should be written back to the source HR system. When this option is enabled, the system will write back the user principal name and email address to the designated fields in the source HR system after each synchronization. To enable write-back, select the corresponding checkbox and click Save.

#Step 4: Simulation

Simulation lets you validate the current configuration before you activate the connection and schedule synchronization.

When you open the Simulation step, the system automatically starts a simulation to retrieve data from the source database. You can also manually start a new simulation by clicking Simulate now and then clicking OK in the confirmation dialog. After the simulation is completed, refresh the page to view the latest results.

The simulation results are comprised of the following components:

• Mutation risk score – Displays both the current risk score and the configured maximum score. The Configure button allows you to specify whether to control synchronizations based on risk score and set up a maximum allowed risk score. If a synchronization run exceeds that threshold, the system automatically stops the run.

• Total actions – Displays the total number of actions, including a breakdown by action type.

• Failed actions – Displays the total number of failed actions, including a breakdown by action type.

• Mutation details – The mutation table provides an overview of all simulations, listing their execution time, the total number of objects processed, and their current status. To view details of a specific simulation, click View details.

#Activate and Set Schedule

If the results are as expected, you can activate the connection and set a synchronization schedule. Click Set schedule. Specify your desired sync frequency and start time, and click Save and activate to apply the settings.

#Step 5: Active

After a connection is activated and scheduled, sync jobs will start based on the interval and start time. After a sync job completes, you can view results.

The sync results are comprised of the following components:

• Mutation risk score – Displays both the current risk score and the configured maximum score. The Configure button allows you to specify whether to control synchronizations based on risk score and set up a maximum allowed risk score. If a synchronization run exceeds that threshold, the system automatically stops the run.

• Total actions – Displays the total number of actions, including a breakdown by action type.

• Failed actions – Displays the total number of failed actions, including a breakdown by action type.

• Mutation details – The mutation table provides an overview of all scheduled synchronizations, listing their execution time, the total number of objects processed, and their current status. To view details of a specific synchronization job, click View details.

#Edit Synchronization Schedule

You can modify the synchronization schedule for this connection. Click Edit schedule at the upper-right corner of the page, update the schedule and click Save and activate.

#Deactivate Connection

You can stop the subsequent sync jobs for this connection by deactivating the connection. Click Deactivate at the upper-right corner of the page and then click OK to deactivate the connection. The state of the connection will change to Deactivated.

#Reactivate Connection

You can reactivate the connection at any time by clicking Activate at the upper-right corner of the page and then clicking OK to reactivate the connection. The state of the connection will change to Active.

#Mapping Rules

Mapping rules extract and process data from the source user object. They can read a single property or combine multiple rules into complex expressions, and are used throughout the Property Mapping and Behavior Condition steps of connection configuration. Refer to the following sections on the supported rule types.

#Read Property

This rule retrieves the value of a specific property from the source user object. To use it, you need to specify the name of the property to retrieve it. You can enter the property name manually or select from a list of all available properties.

#Read Variable

This rule retrieves the value of a predefined variable from your configuration. To use it, specify the name of the variable you want to access. You can enter the variable name manually or select from a list of all available variables.

#Read Relational Property

This rule retrieves values from relational objects attached to the source user. Relational objects represent data without a one-to-one relationship to the user, such as contract history, where an employee may have multiple entries.

1. The first step when configuring this kind of mapping rule is selecting the relationship name (e.g. Contracts). The drop-down list will suggest all the options found.

2. The second step is selecting which property of the relational object you want to read. This would be a property of the contract in the earlier example.

3. The last step is configuring the logic to pick the right item from the list. For example: you might want to select the contract that is the most recent. It’s also possible to combine the values extracted from all the objects in the list into a single value.

Object Selection Methods

The following table lists the available object selection methods:

Selection Method	Parameter	Description
Single item	-	Takes the first and only object of the list. Fails with an error if there is not exactly one item in the list.
First item of the list	-	Takes the first object of the list.
Last item of the list	-	Takes the last object of the list.
Minimum integer value	Field name	Takes the object where the value of the selected property is the lowest integer value.
Maximum integer value	Field name	Takes the object where the value of the selected property is the highest integer value.
Oldest date-time	Field name	Takes the object where the value of the selected property is the earliest date-time value.
Newest date-time	Field name	Takes the object where the value of the selected property is the latest date-time value.
Longest text length	Field name	Takes the first object where the value of the selected property is the longest (highest character count).
Shortest text length	Field name	Takes the first object where the value of the selected property is the shortest (lowest character count).
First not empty	Field name	Takes the first object where the value of the selected property is not empty.
First true	Field name	Takes the first object where the value of the selected property equals true.
First false	Field name	Takes the first object where the value of the selected property equals false.

Combine Methods

The following table lists the available combine methods:

Combine Method	Description
Combine values (comma separated)	Takes all the values from the selected property and combines them into one string value. The values are separated by a comma (,).
Combine values (semicolon separated)	Takes all the values from the selected property and combines them into one string value. The values are separated by a semicolon (;).
Combine values (custom separator)	Takes all the values from the selected property and combines them into one string value. The values are separated by configurable separator.

#Constant Value

This rule outputs a fixed, predefined value regardless of the source data. It is useful for setting default values or applying uniform properties to users. To configure it, enter the exact string value you want the rule to output consistently.

#Compare

This rule compares the results from two nested mapping rules and returns either true or false. It is often used to create conditional logic in property mappings.

• Equals – This mapping rule takes two mapping rules as input. If both values are the same, the rule returns true. If they are different, it returns false.

• Does not equal – This mapping rule also takes two mapping rules as input. If both values are the same, it returns false. If they are different, it returns true.

#Logical Relationship

This rule can be used to apply logical operations (And/Or) to the output of two or more mapping rules. They enable you to evaluate conditions and build complex expressions for advanced data handling.

• And – This option performs a logical AND operation on the outputs of two or more mapping rules. The rule returns a Boolean true value only if all input rules evaluate to true. If any of the input rules returns false, the result will be false. Use the Add rule button to add more mapping rules. Use the Remove rule button to remove a mapping rule.

• Or – This option performs a logical OR operation on the outputs of two or more mapping rules. It returns a Boolean true value if at least one of the nested rules evaluates to true. The result will be false only if all input rules return false. Use the Add rule button to add more mapping rules. Use the Remove rule button to remove a mapping rule.

#Strings

This rule can be used to combine one or more properties into a string value, with flexible formatting options.

• .NET format string – Uses the .NET string formatting syntax to build your output string. You can mix regular text with argument placeholders, using curly braces to mark where each argument should appear: {0} for the first item, {1} for the second, {2} for the third, and so on. Add the names of the arguments with the Add button. Properties of the user object can be used here. Use Remove to remove arguments.

  • Select the Remove whitespace at the start and end of the output checkbox to eliminate any spaces at the beginning or end of the resulting string.

  • Select the Fail on missing arguments checkbox to make the mapping rule fail whenever any required input is missing. If you leave this option unchecked, missing values will simply be replaced with empty strings.

  • Select the Return empty on missing arguments checkbox to have the output return an empty string whenever any input value is missing or contains only whitespace.

• Built-in string templates – Uses special functions to insert and manipulate text, allowing you to generate values based on context. These functions are surrounded by square brackets ([]). Some functions support arguments, which are listed after a colon (:) and separated by semicolons (;).

  For example, the template [lower:[first:[firstname] applies the 'first' function to 'firstname' and then uses 'lower' to convert the result to lowercase.

#Switch

This rule makes it possible to switch between multiple nested mapping rules based on a selector value. The selector value is established through a specific mapping rule, functioning similarly to other mapping rules by generating an output. The switch mapping rule will select the case (nested mapping rule) to use for its output, based on the selector value. Each “case” is a combination of a selector value and mapping rule. This mapping rule will use the fallback value (also a mapping rule) in case the selector values does not match with any of the defined cases.

Some example use-cases are:

• Select the right way to format the surname based on another field that determines the desired format. This case is very common for Dutch names because of many Dutch HR applications allow configuring if someone wants to use the surname of their partner, when married.

• Format the function titles differently for different departments.

• Replace some specific output values with other output values. Useful when translating values or assigning display names for system values.

#Date and Time

This rule is used to parse and process date-time values.

• Parse date-time – Converts a string value into a date-time value by parsing it. Some other mapping rule types need this data type as their input.

• Simple date-time comparison – This mapping rule takes a date-time value from a nested mapping rules and applies a built-in operation, such as comparing two dates or checking if a date meets certain criteria. The output will be true or false. Select the operation from the drop-down list and enter the parameters for operations that require it. The input date-time value can be empty. Use the Empty input option to specify what the result should be in that case.

• Add time – Takes the output date-time value from a nested mapping rules and adjusts it by either adding or subtracting a specified amount of time. To decrease the time, use negative numbers.