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 SSO using Active Directory 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

SSO using Active Directory

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

  • Microsoft .NET Framework 4.8

  • SYSPRO 8 e.net Communications Load Balancer

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

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 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)

Service operators are signed in by a SYSPRO service and are used for any functionality that is required by the service to obtain information about SYSPRO.

Normal operators sign in to SYSPRO with a username and password. They access certain programs and functions to perform specific tasks.

For example:

the __SRS service operator is used by the SYSPRO 8 Reporting Host Service to obtain information about the companies in an environment, but it isn't used by the business object to retrieve the data for a report, as that would be the specific normal operator that submits the request for the report.

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

Service operators are created by SYSPRO and are used by SYSPRO services to obtain information about SYSPRO.

The service operator code starts with a double underscore to differentiate them from other operators. A default company code must be assigned to each service operator within the Operator Maintenance program, as we use the company code to log in the service operator via e.net .

The following is a list of service operators and their function within SYSPRO:

  • The __ADSYNC service operator is used by the SYSPRO 8 Active Directory Sync Service to push Microsoft Active Directory (AD) information into SYSPRO for Active Directory managed operators.

  • The __DFM service operator is used by the SYSPRO 8 Document Flow Manager Folder Poller and SYSPRO 8 Document Flow Manager Queue Poller to monitor folders, send files to the queue and process files.

  • The __ESP service operator is used by the following services:

    • SYSPRO 8 Espresso Service,

    • SYSPRO 8 Espresso Notification Service,

    • SYSPRO Espresso Development Plugin and the

    • SYSPRO Avanti Web Service to obtain information for the password reset and forgot password functionality.

  • The __POS service operator is used by the SYSPRO 8 Point of Sale Services to determine and validate the setup options and required credentials at start up, update the required databases and post to SYSPRO (if the Point of Sale operator doesn't have access to SYSPRO).

  • The __RUL service operator is used by the SYSPRO 8 Rules Engine Service and the SYSPRO 8 Rules Data Service.

  • The __SA service operator is used by the SYSPRO 8 Analytics service to make business object calls.

  • The __SAI service operator is used by the SYSPRO 8 Machine Learning service.

  • The __SRS service operator is used by the SYSPRO 8 Reporting Host Service and the SYSPRO 8 Cognitive Service to manage client-side report printing.

  • Only specific services use service operators to log in via e.net.

  • SYSPRO creates service operators by copying the ADMIN operator. If the ADMIN operator record doesn't exist (i.e. it may have been deleted), then the current operator is used when saving system details from the Setup Options program.

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.

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

The minimum setting is 0.30 minutes.

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