Directory Synchronization (Retarus DirSync Service)

This guide provides comprehensive information on what the Retarus DirSync Service is, how it works, and how you use it effectively in your organization.

What is the Retarus DirSync Service?

The Retarus DirSync Service automates the synchronization of user data between your organization's directory and Retarus systems, ensuring that user information remains accurate and up to date. This service helps eliminate manual updates and streamlines managing user data across multiple platforms.

The DirSync Service supports synchronization for the following Retarus solutions:

Fax-to-Email
Email-to-Fax
Email-to-SMS
Email Security

By automating the transfer of user data, the DirSync Service ensures that any updates, such as user moves, additions, changes, or deletions (MACD processes), are quickly reflected in your Retarus system configuration.

Supported upload methods

File upload: The data can be uploaded manually or semi-automatically via HTTPS or SFTP using preformatted CSV files.
Direct input: Manual configuration can be managed directly through the EAS portal.

When using the DirSync Service, please avoid manually configuring user data in the EAS portal, as any manual changes will be overwritten during the next synchronization. It is recommended to either use the DirSync Service for automated synchronization or manage user data manually, but not both at the same time to avoid conflicts.

Key features

Automated synchronization: Keeps user information current by continuously synchronizing it with Retarus systems.
Customizable intervals: Administrators can set synchronization frequencies according to business needs.
Secure data transfer: Data is encrypted and uploaded securely using HTTPS or SFTP.
Bulk data handling: Uploads large sets of user data in bulk using predefined CSV file formats.

Core workflow

The diagram below illustrates the core workflow for the Retarus DirSync Service:

Configuring settings in the EAS portal
Preparing data for upload
Securely uploading the prepared data via SFTP/HTTPS

In addition to the core workflow, Retarus offers optional tools that can assist with data uploads—DirSync Client for Windows and Azure Directory Synchronization. These tools enhance the functionality of the DirSync Service by providing tailored solutions for both on-premise and cloud environments.

Getting started with the Retarus DirSync Service

Configuring settings in EAS

To get started, configure the parameters for your data synchronization in the EAS portal. This includes defining the structure of the data to be synchronized, import processing, and reporting options. Refer to the specific documentation for the solution you are using.

Solution	Link to documentation
Fax-to-Email	DirSync settings for Fax-to-Email
Email-to-Fax	DirSync settings for Email-to-Fax
Email-to-SMS	DirSync settings for SMS

Preparing data for upload

Before you can upload and synchronize data using the DirSync Service, you need to prepare a CSV file formatted according to the defined Retarus specification.

Each Retarus solution has its own specific import CSV file structure and content requirements, which are critical for accurate data synchronization. Understanding these specifications is essential to using the Retarus DirSync Service effectively and ensuring smooth integration of user information across different platforms. For detailed instructions, refer to the following information sources.

Solution	Details
Fax-to-Email	File structure: The CSV layout and components needed for Fax-to-Email are outlined in the Fax-to-Email import file format documentation. Content requirements: Must include fields such as user email addresses and fax identifiers. The exact order of these and other fields is critical for effective synchronization.
Email-to-Fax	File structure: The CSV file must be formatted according to the specifications detailed in the Email-to-Fax import file format documentation. Content requirements: Requires fields for user identification, fax number, and any relevant metadata. Each entry must follow the defined layout to ensure successful data import and user synchronization.
Email-to-SMS	File structure: The import file layout and properties are specified in the Email-to-SMS import file format documentation. Content requirements: Must contain fields such as user contacts and SMS settings in the appropriate format to ensure that the data is correctly received and used by the system.
Email Security	File structure: The user management component is described in the Email Security user management documentation. Content requirements: Requires details on domain configurations and user addresses, focusing on how users are added or modified within the system.

An overview of the CSV syntax that applies to most of the Retarus solutions can also be found in CSV Syntax per Retarus product.

Uploading data

Once your CSV file is ready, you can upload your data using the SFTP or HTTPS protocol. If you don't have the required FTP and HTTPS URLs and credentials, contact the Retarus implementation team to obtain them.

Example: Command samples for HTTPS uploads using the cURL command

Fax-to-Email

BASH

curl -v --user name:password -H "Content-Type: text/csv" -X POST --data-binary
    @f2m.csv https://dirfilter.retarus.com/dirsync/v1/upload/?type=f2m

Email-to-Fax

BASH

curl -v --user name:password -H "Content-Type: text/csv" -X POST --data-binary
    @m2f.csv https://dirfilter.retarus.com/dirsync/v1/upload/?type=m2f

Email-to-SMS

BASH

curl -v --user name:password -H "Content-Type: text/csv" -X POST --data-binary
    @m2s.csv https://dirfilter.retarus.com/dirsync/v1/upload/?type=m2s

Example: Upload via SFTP

For file uploads, you can use any standard SFTP client, such as the SFTP utility available on Linux systems. To automate the synchronization process, consider setting up a cron job to upload data at regular intervals, such as once a day.

Best practices: Using profiles to streamline synchronization

One of the most efficient ways to manage user data synchronization in the Retarus DirSync Service is by using profiles. Profiles allow you to group and manage configurations for different groups of users, minimizing the time and effort required to update synchronization settings across large datasets.

Key benefits

Consistency: Apply the same configurations to multiple users or groups of users without having to configure each one individually
Simplicity: Manage settings for multiple users from a central profile, reducing errors caused by manual configuration.
Flexibility: Quickly adapt synchronization policies across user groups by making changes at the profile level.

Example

You can start by identifying the groups of users that share similar synchronization needs. These could be based on:

Geographical regions (e.g., Europe, North America)
Business units or departments (e.g., Marketing, IT)
Retarus service types (e.g., Fax-to-Email, Email Security)

Once the groups are defined, create profiles for each group and specify the appropriate synchronization settings.

Finally, assign the relevant user groups or individual users to the profiles, ensuring that the correct synchronization settings are automatically applied whenever data is updated or imported. Now you can make updates and apply them across multiple users or services at once. When changes such as policy updates or user attribute modifications are required, simply update the relevant profile(s) with the new settings. All associated users will automatically inherit the latest configurations.

Additional tools for the Retarus DirSync Service

In addition to the core Retarus DirSync Service, Retarus provides supplementary tools designed to extend its functionality for various infrastructure needs, whether on-premise or cloud-based. These tools help streamline and automate directory synchronization processes, ensuring seamless integration with Retarus systems.

DirSync Client for Windows

DirSync Client for Windows is provided without official support from Retarus. The software and its documentation are offered free of charge as a courtesy, with no obligations or liabilities. Customers use this tool at their own risk and are not entitled to request or receive official support.

DirSync Client for Windows is a tool developed for customers using Windows environments. It runs as a Windows service and simplifies the setup and management of directory synchronization by automating the polling and synchronization of user data, groups, and attributes.

Key features include:

Automated polling and synchronization: The tool polls the directory at user-defined intervals, ensuring that data is regularly updated in Retarus services.
Customizable settings: Users can configure synchronization intervals and the specific data to be synchronized, tailoring the tool to their environment.
Effortless setup: The tool is easy to install and configure, making it accessible for businesses of all sizes operating within a Windows infrastructure.

For more details, see DirSync Client for Windows.

Azure Active Directory Synchronization (AAD Sync)

Azure Active Directory Synchronization (AAD Sync) is currently available only for Email Security, enabling efficient synchronization of email addresses.

Please note that Azure Active Directory has recently been renamed to Microsoft Entra ID. Therefore, any mention of Azure Active Directory now refers to Microsoft Entra ID.

Azure Active Directory Synchronization offers a valuable solution for organizations using cloud services. This tool efficiently connects cloud-based user directories with Retarus systems, ensuring seamless integration. It provides real-time updates of user information across platforms, including popular services like Microsoft Azure.

Key features include:

Cloud-native design: Built to operate seamlessly in cloud environments, ensuring that directory data remains up-to-date.
Security and scalability: Designed with enterprise-grade security and the capacity to handle directories of all sizes.
Optimized for Azure: Works seamlessly with Azure Active Directory, ensuring ease of use for administrators.

For more information, see Azure Active Directory Synchronization.