SYSPRO 8 Active Directory Sync Service

Exploring

The SYSPRO 8 Active Directory Sync Service is used to integrate Microsoft Active Directory (AD) to read all users contained within the SYSPRO.ERP security group.

The service updates the AdmSsoUsers table, which updates the operators listed in the Active Directory User Management program.

The service also provides an audit trail of all updates that occur. This information is stored in the AdmSsoUserSyncLog table of your system-wide database.

The service is used by Single Sign-on and comprises the following:

  • Main service

  • Receiver

The main service is responsible for the synchronization of components according to the configured synchronization schedule.

The following functions are performed by this component:

  • Read configuration files

  • Interrogate Microsoft Active Directory (AD)

  • Generate XML for passing into the AdmSsoUsers table

  • Call relevant SYSPRO business objects

Benefits include:

  • The service is fault tolerant and allows a custom retry timer if a fault is detected.
  • The service allows custom configuration, if required, which takes precedence and remains in force when updating the service.
  • The service doesn't need to be restarted when creating custom configuration.
  • The service has a delayed start which results in improved machine start times.

The receiver is the listening component of the service which is responsible for listening for external synchronization requests.

It is activated by the Sync Now option in the Active Directory User Management program.

Benefits include:

  • Synchronization between SYSPRO and Microsoft Active Directory (AD) can be performed at any time.

  • The service has a delayed start (30 seconds after system start) which results in improved machine start times.

  • The default location for this service is:

    Program Files > SYSPRO > SYSPRO 8 Active Directory Sync Service

Overview topic

SYSPRO Services

Topics

Single Sign-on

Programs

Active Directory User Management

Add Operator and Link to AD User

Active Directory Link Operator

Operator Maintenance

PDF and Video Resources

Install Guides

Starting

The SYSPRO 8 Active Directory Sync Service must be run as a named user that has READ permission to access Microsoft Active Directory (AD).

  • Microsoft .NET Framework 4.6

  • SYSPRO 8 e.net Communications Load Balancer

    A valid endpoint must be configured in the Setup Options program of SYSPRO 8.

  • This service is installed using the SYSPRO Installer Application.

  • The SYSPRO 8 Active Directory Sync Service must be run as a named user that has READ permission to access Microsoft Active Directory (AD).

  • This service can be installed on any machine that has access to Microsoft Active Directory (AD) and the SYSPRO 8 e.net Communications Load Balancer service.
  • The SYSPRO 8 Active Directory Sync Service can only be installed once per machine.

  • Each security group in Microsoft Active Directory (AD) requires its own SYSPRO 8 Active Directory Sync Service to be installed.

Solving

The SYSPRO.AD.Sync.Service.exe.config file is located in the same folder in which the service is installed.

Avoid editing this file as it could potentially break the service at the next update.

If you need to make changes to the file, we suggest the following alternative options:

  • Uninstall the service
  • Create a custom.config file

To create a custom.config file, make a copy of the SYSPRO.AD.Sync.Service.exe.config file and rename it to custom.config.

The custom.config file can then contain the entry you want to modify and the startup node. Any entries not contained in the custom.config file are retrieved from the original SYSPRO.AD.Sync.Service.exe.config file.

You should ideally stop the service while you do this, otherwise the configurations will be picked up at the next poll interval.

You can view monitoring and troubleshooting messages about this service using the Event Viewer function in Windows:

(Control Panel > System and Security Administrative Tools > Event Viewer > Applications and Service Logs)

However, this depends on the logging level defined in the Service.config file.

You can start, stop, restart and configure this service using the Services function in Windows:

(Control Panel > System and Security Administrative Tools > Services)

The SYSPRO 8 Active Directory Sync Service must be run as a named user that has READ permission to access Microsoft Active Directory (AD).

The PollInterval is set to default every 12 hours, but can be changed if required.

The minimum setting is 0.30 minutes.

None.

The synchronization between SYSPRO and Microsoft Active Directory (AD) is a one-way service.

SYSPRO operators defined as AD Managed are managed by Microsoft Active Directory (AD) and updated accordingly in SYSPRO automatically when the SYSPRO 8 Active Directory Sync Service runs.

The following operator attributes are managed by Microsoft Active Directory (AD) and cannot be maintained in SYSPRO for Active Directory operators:

  • Operator name
  • Operator email address
  • Network user name
  • Operator status (i.e. Active, Disabled or Removed)

You can rename the SYSPRO.ERP security group in Microsoft Active Directory (AD) by adding a suffix to the group name.

For example:

SYSPRO.ERP.ACCOUNTS

When you install the SYSPRO 8 Active Directory Sync Service (using the SYSPRO Installer app) ensure that you enter this suffix at the Security Group Suffix parameter field.

If required, you can update the suffix after installing the SYSPRO 8 Active Directory Sync Service:

  1. Create a custom.config file:

    To create a custom.config file, make a copy of the SYSPRO.AD.Sync.Service.exe.config file and rename it to custom.config.

    The custom.config file can then contain the entry you want to modify and the startup node. Any entries not contained in the custom.config file are retrieved from the original SYSPRO.AD.Sync.Service.exe.config file.

    You should ideally stop the service while you do this, otherwise the configurations will be picked up at the next poll interval.

  2. Update the ADSecurityGroup key's value with the new security group name.

If you have configured receiving emails in the System Setup program (Review email required, Failure email required, Success email required) the following variables are passed to the email templates when the Microsoft Active Directory (AD) synchronization takes place:

  • $SsoUserCount$

    Count of users added for review.

  • $SsoOpChanged$

    Count of operators with changes (e.g. email, name).

  • $SsoOpActivated$

    Count of operators whose status has changed to active from disabled or removed.

  • $SsoOpDisabled$

    Count of operators whose status has changed to disabled.

  • $SsoOpRemoved$

    Count of operators whose status has changed to removed.

  • $FailedMsg$

    If the synchronization fails, then this contains the message as written to the log file.

Referencing

Key Description
LoadBalancerAddress

This specifies the URL for the SYSPRO 8 e.net Communications Load Balancer service, as defined when the service is installed in the SYSPRO Installer.
ReceiverEndpoint

This specifies the service's endpoint (as defined when the service is installed in the SYSPRO Installer) so that SYSPRO can call the service.

instancekey

This specifies the base directory instance on the SYSPRO application server, as defined when the service is installed in the SYSPRO Installer.
languageCode

This specifies the SYSPRO language code.
PollInterval

This determines how often the service will pull information from Microsoft Active Directory (AD).

The default is 12 hours.

The minimum setting is 0.30 minutes.
FailedRetryInterval

This determines how often the service will try to post again after a failure.

The default is 1 hour.

The minimum setting is 0.30 minutes.
LogLevel

This enables debug logging for the service in the Microsoft DebugView tool and outputs logging to the logfile.txt:

  • N = None (Default)
  • I = Information
  • E = Errors Only
EventLoggingRequired

This enables additional logging for the service and outputs the log entries to the EventLog.

If this key is disabled when the service starts, normal default entries are written. However, if this key is enabled, then entries are written to a dedicated section in the EventLog.

The level of detail output depends on the logging level defined against the LogLevel key.

The detailed logging includes the full FQDN (Fully Qualified Domain Name) for all processed uses and failed objects. Therefore, it is not recommended to set the LogLevel as I, as that would result in the entries being verbose including the FQDN.

This entry is only applicable in the custom.config file. Therefore, attempting to enable this key in the standard SYSPRO.AD.Sync.Service.exe.config file has no effect.
ADSecurityGroup

This indicates the Microsoft Active Directory (AD) security group (set to SYSPRO.ERP as the default, but can be customized using custom configuration).