Ektron CMS400.Net eSync

Updated 4/5/2011 

Regardless of your personal opinion of Ektron's eSync technology, you can't help but admit it is a pretty amazing. After having used it for a few years, I have gained a love-hate relationship for its ability to seamlessly synchronize every aspect of web CMS implementations, and at the same time, cause hours of angst when it fails.

The goal of this article is to ease the burden of troubleshooting other esync implementations out there by documenting various undocumented aspects of Ektron CMS400.Net's esync platform. Perhaps someone at Ektron will write a better explanation than this, but for now, I have not been able to locate anything better.

This is not a "how to" setup and configure esync. There are plenty of articles and manuals written to assist with your eSync setup. This article is meant to be a deep dive into the inner workings of esync, in hopes of assisting other developers, system administrators, etc, that may run into similar esync failure scenarios.

CMS License

Esync requires a valid, current, non-expired, esync enabled license (with (S) or (EN) in the key.) If any of the servers configured in your esync system have an invalid license, esync will fail.

Web.config

1. eSyncEnabled: Set this key to true to enable content/folder sync if the eSync feature is available.
2. WSPath Must be set to the web service callback URL in the workarea (Workarea/ServerControlWS.asmx)
3. encodedValue The value of this <appSettings /> key must match the attribute value of the public(k) cert key for the respective server in the Ektron.ASM.EktronServices30.exe.config file of the sync server.

   AppSettings 

   <add key="encodedValue" value="%LONG_ENCODED_VALUE%" />

   publickCertKeys 

   <publickCertKeys>
    <add key="SERVERNAME_SyncClient.cer" encodedValue="%LONG_ENCODED_VALUE%" />
   </publickCertKeys>

    

Windows Service

The esync core process is driven by the Ektron Windows Services. If you have it disabled or it is not running for some reason, do not continue. Esync will not function without the service running.

The following files lie under the EktronWindowsService30 folder underneath the base installation directory.

1. Ektron.ASM.EktronServices30.exe.config - Contains valid esync certificate information for the servers that are part of the sync pair.
2. sitedb.config - Stores each CMS 400.Net site configuration that the Windows service will manage. Each site must have a unique WSPath or it will not show up as a unique site to be managed (this applies to SearchConfigUI instances as well incidentally.) You can safely clear this file as it is regenerated each time the Windows service is restarted. This can help determine why a site is not functioning properly.
3. log (folder) - If you haven't dug into the log folder, start. It contains error events that are not written to the event log that can help assist in troubleshooting failed esync processing.

Database Tables

The following tables are used in one way or another by the esync framework:

1. [AssetServerTable] - Stores a record for each site (domain) that connects to a specific CMS instance. For example, if you have multiple IIS web sites (local or not) using the same CMS database, a separate record will exist for each server that connects to and makes request against the specific CMS instance. The main thing to confirm with this table, is that a record with a valid callback URL (sometimes blank if the Windows service fails to catalog each server) for each esynced web site. If you have problems with any CMS processes that rely on the Windows service, you can safely truncate/delete the records from this table, restart the Ektron Windows Service, and regenerate the valid records.
   • [callbackUrl] - Callback URL the service uses to perform actions.
    
2. [scheduler] - Stores configuration options for each esync configuration instance.
   • [scheduledesc] - The current sync status of that particular instance (usually completed or running)
   • [triggeraction] - The configuration options for the specific esync instance (get to know this). Also stored in the Sync folder XML configuration files. I'm assuming this field is tied directly to the XML config settings somehow.
    
3. [perform_action] - This table is the engine of the Windows service. Any action the service is to perform, originates in this table (such as esync actions.)
4. [sync_resolve_tbl] - Undocumented at this time (anyone?)
5. [syncfolder] - Undocumented

Trigger Action

The triggeraction field contains the key configuration settings for the local and remote sync servers. If any of the paths in your *SiteConfigData are not set properly, or the target folders have been moved/relocated, you may get a:

Object reference not set to an instance of an object

error as well.

<ScheduleInfo>
<RemoteSite>server=%REMOTE_DB_HOST%;database=%REMOTE_DB_NAME%;Integrated Security=false;user=%DB_USER%;pwd=%DB_PASS%;</RemoteSite>
<LocalSite>server=%LOCAL_DB_HOST%;database=%LOCAL_DB_NAME%;Integrated Security=false;user=%DB_USER%;pwd=%DB_PASS%;</LocalSite>
<RemoteUrl>http://%REMOTE_URL%:8732/Ektron.Sync.SyncServices/SiteCommunicationService.svc</RemoteUrl>
<SiteUrl>http://%LOCAL_URL%:8732/Ektron.Sync.SyncServices/SiteCommunicationService.svc</SiteUrl>
<SyncDirection></SyncDirection>
<ConflictPolicy></ConflictPolicy>
<Files filter="none" />
<LocalSiteConfigData>
	<AssetLibraryPath>c:\%PATH_TO_ASSETLIBRARY%\AssetLibrary\</AssetLibraryPath>
	<AssetsPath>c:\%PATH_TO_WEB_ROOT%\assets</AssetsPath>
	<LocalAddress>%LOCAL_HOST%</LocalAddress>
	<LocalSiteAddress>%LOCAL_HOST%</LocalSiteAddress>
	<PrivateAssetsPath>c:\%PATH_TO_WEB_ROOT%\privateassets</PrivateAssetsPath>
	<SitePath>c:\%PATH_TO_WEB_ROOT%</SitePath>
	<UploadedFilesPath>c:\%PATH_TO_WEB_ROOT%\UploadedFiles</UploadedFilesPath>
	<UploadedImagesPath>c:\%PATH_TO_WEB_ROOT%\UploadedImages</UploadedImagesPath>
	<WebSitePath>http://%LOCAL_URL%</WebSitePath>
	<WorkareaPath>c:\%PATH_TO_WEB_ROOT%\workarea</WorkareaPath>
</LocalSiteConfigData>
<RemoteSiteConfigData>
	<AssetLibraryPath>c:\%PATH_TO_ASSETLIBRARY%\AssetLibrary\</AssetLibraryPath>
	<AssetsPath>c:\%PATH_TO_WEB_ROOT%\Assets\</AssetsPath>
	<PrivateAssetsPath>c:\%PATH_TO_WEB_ROOT%\PrivateAssets\</PrivateAssetsPath>
	<RemoteAddress>%REMOTE_HOST%</RemoteAddress>
	<SitePath>c:\%PATH_TO_WEB_ROOT%</SitePath>
	<UploadedFilesPath>c:\%PATH_TO_WEB_ROOT%\uploadedfiles\</UploadedFilesPath>
	<UploadedImagesPath>c:\%PATH_TO_WEB_ROOT%\UploadedImages\</UploadedImagesPath>
	<WebSitePath>http://%REMOTE_URL%/</WebSitePath>
	<WorkareaPath>c:\%PATH_TO_WEB_ROOT%\workarea</WorkareaPath>
</RemoteSiteConfigData>
<IsDownloadUpload>false</IsDownloadUpload>
</ScheduleInfo>

Sync Folder

ESync creates local folder (usually C:\Sync) to maintain file sync status. Each sync instance has it's own root folder. InetPub (or wherever you store your web roots) for the local server, and a folder for each sync server by server name.

ServerInfo.xml

Esync bindings are stored in the c:\sync\ServerInfo.xml file. This file is autogenerated by the Ektron Windows Services and based on the triggeraction setting in the database.

Esyncknow and Eknow Files

Under each sync sub-folder is a pair of esync knowledge files: replica.esyncknow and knowledge.esyncknow (*.eknow for older versions). Deleting all *.esyncknow (*.eknow) files may solve any SyncAssetLibraryFailed errors.

EkStatus Xml Files

The EkStatus folder usually lives under your web root. A separate ##.xml status file is created for each esync binding configured under synchronization in the workarea. Each time an esync is kicked off, the correlating ##.xml file is truncated and all logging is done within the file. This is one of the first places to check in the event of a failed esync. You can usually determined what action esync was trying to perform at the time of failure.

Conclusion

Ektron CMS 400.Net Esync Technology is by far one of the most robust Web CMS synchronization platforms on the market. A successfully configured, running, synchronizing implementation results in satisfied developers, content administrators, and ultimately, content stakeholders. I have found that most issues correlate directly to one of the items listed here. Any additional information from those of you that have experienced similar situations is also welcomed.

Happy syncing!

Other Resources

Martin on .NET eSync Reference