#Manage Connections

The connections table provides an overview of all available connections. Each connection represents a connection between the source HR system and the destination Microsoft 365 tenant. By clicking a connection name, you will be redirected to the connection details page.

You can perform the following operations to manage connections:

• Simulate – Run a simulation to preview changes before activating a connection. Select a connection in the Simulation state, and click Simulate to start the simulation job. Upon completion, the results will be displayed on the connection details page.

• Set schedule – Configure a recurring synchronization schedule by setting a start time and interval. Select a connection in the Active state, click Set schedule, define an interval and a start time, and click Save and activate.

• Deactivate – Stop sync jobs for a connection by deactivating it. Select a connection in the Activestate, click Deactivate, and then click OK to deactivate the connection.

• Delete – Permanently delete a connection. Select the connections that you want to delete, click Delete, and then click OK to delete the connection.

#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.

9. Click Save.

#Configure a Connection

After creating a connection, you need to complete a 5-step configuration process.

Click the connection name to access the Connection details page, where you can track your progress and view key information including: the connection name, the source HR system and the destination tenant type, tenant name and organization name, the last sync time, and the next sync time.

The View audit logs link allowing you to view detailed logs of the performed operations.

#Step 1: Configuration

This is the initial step to configure the connection. In the Source HR system configuration section, define connection details to the HR source system, which can be obtained from the source HR system:

• Environment ID – Specifies the target AFAS environment (Test or Production) 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.

• 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.

  • 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.

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 it. To delete a variable, click the Delete button next to it.

#User Names

This section includes user display name mapping, mailnick name mapping, and UPN mapping. Configure mappings to establish the connection between source and destination user names. To edit a mapping, click the Edit button next to it.

#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.

#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 should be included in the synchronization by specifying a scope condition. Only employees who meet this condition will be synchronized. To synchronize all employees, set Scope condition to true.

To modify the scope condition, click Edit. Make your updates to the condition, then 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 specifies which users should be created. If you want to allow user creation, set Creation condition to true. To allow user creation for specific employees only, define custom conditions accordingly. To prevent user creation, set Creation condition to false.

To modify the creation condition, click Edit. Make your updates to the condition, then 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 specifies which users should be deleted. If you want to allow user deletion, set Deletion condition to true. To allow user deletion for specific employees only, define custom conditions accordingly. To prevent user deletion, set Deletion condition to false.

To modify the deletion condition, click Edit. Make your updates to the condition, then 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 user activation or deactivation. 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 Edit. Make your updates to the condition, then 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

The manager assignment filter determines how managers from the source HR system are matched and assigned to users in the destination system.

• Manager identifier type – Choose the identifier type used for 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. Confirm that managers are present in the HR system to prevent assignment errors.

  To modify the manager selector condition, click Edit. 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 or disable this setting to indicate whether manager synchronization should be performed.

#Group Assignment

The group assignment filter determines how users are assigned to groups during the synchronization.

• For a conditional group, only users whose properties meet the specified criteria are assigned to the group.

• For a constant group, all users are assigned to the group regardless of their properties.

Refer to the following steps to add a constant group:

1. 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.

Refer to the following steps to add a conditional group:

1. 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.

#User Password Policy

Configure how initial passwords are managed for users created during synchronization by selecting one of the following methods:

• Send invitation link to employee's email – Users will receive an email invitation to set their own password. You must specify which HR system field contains the employee's email address for the invitation.

• Send initial password to manager – A system-generated initial password will be sent to the employee's manager for distribution.

  For this method, the password will be sent to the manager's Microsoft 365 email address. If the manager's email address is unavailable, the password will be sent to the next higher-level manager. To ensure reliable delivery, please confirm that all managers have valid Microsoft 365 email accounts.

• Send password directly – A system-generated password will be emailed directly to the user. Enter the specific email address to receive the password.

• Write-back option – Specify whether the user principal name and email address made to users in the target destination should be written back to the source HR system.

#Step 4: Simulation

Upon entering the Simulation step, the system will automatically initiate a simulation process to retrieve data from the source database, allowing you to preview results before activating the connection. To view the simulation results, please refresh the page.

You can run a simulation immediately by clicking Simulate now.

The simulation results are comprised of the following components:

• Mutation risk score – Displays both the maximum score and the current risk score. The Configure button allows you to specify whether to control synchronizations based on risk score and set up a maximum allowed risk score. When the calculated risk score for a sync job exceeds the threshold you set, the sync job will be automatically stopped.

• Total actions – Indicates the overall number of actions taken, as well as a breakdown by action type.

• Failed actions – Shows the total number of failed actions, including a count for each 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 examine the details of a specific simulation, click View details.

If the results are as expected, you can activate the connection and set a schedule for it. 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 maximum score and the current risk score. The Configure button allows you to specify whether to control synchronizations based on risk score and set up a maximum allowed risk score. When the calculated risk score for a sync job exceeds the threshold you set, the sync job will be automatically stopped.

• Total actions – Indicates the overall number of actions taken, as well as a breakdown by action type.

• Failed actions – Shows the total number of failed actions, including a count for each 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 examine the details of a specific synchronization job, click View details.

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.

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.

#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.