EngageCX 11.5 (Mantine) Sysadmin Guide

Getting Started

Overview

About EngageCX Platform

EngageCX provides a complete, end-to-end customer communication management solution that integrates every process involved in the creation of professional documents into a smart unified and easy-to-use platform.

Audience

This guide is designed to help system administrators to set up, configure and utilize the EngageCX Platform.

The System Administrator Guide is the primary source to follow when you start using the EngageCX Platform. This guide will help you understand how to configure various settings within EngageCX Platform.

Resources

After your platform is ready to be used, access the User Guide to learn how to add users, produce documents and use all the other features provided by EngageCX or visit Developer Guide to build an application that works with EngageCX Platform.

Contact Us

If you encounter any issue while using the EngageCX Platform, do not hesitate to contact us, at engagecxsupport@mhcautomation.com.

System Overview

Components

EngageCX Platform contains the following components:

• Enterprise Website: An EngageCX Website that provides access to the enterprise users to work with all the important EngageCX features. It is installed as a website on IIS (Internet Information Services). By default, the port number associated with the website is 8094.
• System Administrator Website: An EngageCX Website that provides access to the system administrators to manage environments or domain. It is installed as a website on IIS. By default, the port number associated with the website is 8095.
• Customer Portal Website: An EngageCX Website that provides access to your customers from where they can see all individual documents. It is installed as a website on IIS. By default, the port number associated with the website is 8096.
• EngageCX Publishing Engine: A server component that performs XML/JSON conversion to various output formats. It is installed as a service on Windows Services.
• EngageCX Data Engine: A server component that performs data aggregation from multiple data sources. It is installed as a service on Windows Services.
• EngageCX Analytics Engine: A server component used to create dashboards and digital experience documents. It is installed as a service on Windows Services.
• Backend Services: Backend Services involves different windows services for jobs, schedules and triggers.
• Document Repository: Repository for all documents and files within EngageCX Platform.
• Search Engine: An EngageCX component that allows administrators to enable the search feature across environments.
• Licensing Engine: An EngageCX component that allows administrators to manage EngageCX product keys.

Files & Folders

System files for EngageCX solution are placed in the following locations:

Application Installation Folder

This is where the product is installed. The installation directory contains all the binaries for the websites, backend services or components. In a default installation, this is C:\Program Files\EngageCX\<Product Name>.

Application Data Folder

This directory contains the configuration files for the EngageCX Components. In a default installation, the configuration files are located under C:\ProgramData\EngageCX.

Main Configuration File

The main configuration file is EOS4.config and it is loaded on start-up by all websites and main EngageCX Service (EngageCX Omni System 4 Service). It contains system settings which enable additional functionalities, such as distributed configurations and high availability. Any changes made to the main configuration file require a restart of both the main EngageCX Service (e.g. from Windows\Task Manager\Services) and websites (e.g. using iisreset).

The configuration file location is %Application_Data%\EngageCX\EOS4.config.

By default, you will notice that inside the config file you can find the IP Addresses and port numbers of all EngageCX Services and Websites. All of the IP Values mentioned throughout should be taken to mean “the IP through which this service can be accessed”. Usually, this is the intranet IP of the machine hosting the component. If a component is load balanced, then it’s the IP of the load balancer. Essentially, if someone were to specify all IPs explicitly on each machine, the list of IPs should be the same across all the machines.

To change the default values, you will need to log in as a system administrator and navigate to the Domain Settings:

• To change EngageCX Website values, visit the URLs section.
• To change EngageCX Services values, visit the Services section.

Components Configuration Files

Publishing, Data, and Analytics services have separate configuration files named the same as the corresponding executable and located in the Application Data folder, respectively:

• EngageCX Publishing Engine:
  • Configuration File: PublisherSvc.config
  • Configuration File Location: %Application_Data%\EngageCX\PublisherSvc.config
• EngageCX Data Engine:
  • Configuration File: DASSvc.config
  • Configuration File Location: %Application_Data%\EngageCX\DASSvc.config
• EngageCX Analytics Engine:
  • Configuration File: BISvc.config
  • Configuration File Location: %Application_Data%\EngageCX\BISvc.config

Any changes made to the configuration files require a restart of the associated service, from the Windows Task Manager.

Domain

An EngageCX system is comprised of three entities: domain, environment, and workspace.

EngageCX Solution provides the following hierarchy:

• The EngageCX domain contains one or more environments.
• Each environment contains one or more workspaces.

The domain refers to the entire EngageCX Platform setup - it is the top-level node. An installation of EngageCX Software, whether it's across one or multiple machines, will contain a single domain.

---

Environments

The domain contains multiple environments, each with its own set of users and features. An environment may be necessary for your organization in order to provide a sequential structure for your projects management needs. This is also where enterprise users log into and perform all of their work.

The purpose of environments is to have completely separate EngageCX instances within the same installation, which may be useful in some scenarios. Here are some examples of when you might consider multiple environments:

• DTAP (or similar) setups – a different environment for each stage of a development process (Development, Testing, Acceptance, Production);
  • These environments are more or less clones of each other, with projects being worked on in Development, then being published through Testing, Acceptance and eventually Production.
  • In this type of scenario, a user will likely have access to multiple environments.
  • For performance and stability reasons, it’s highly recommended that the Production environment is part of a different EngageCX domain/installation altogether.
• Multi-tenant setups – a different environment for each customer (or “tenant”)
  • This type of setup is intended to separate your customers into their own environments because it doesn’t make sense for any overlap to exist;
  • A good practice is to give each user an account with their corporate email as the username; this way, customers will be naturally separated: @company1.com to the Company1 environment, @company2.com to the Company2 environment, etc.
  • Built-in EngageCX authentication is recommended for this type of setup.
• Single purpose environments – a “one-off” environment to try a specific feature, perform a demo or a training session.
  • Creating a new environment for trying out a new feature allows you to properly isolate your work from other operations being performed on the server.

Workspaces

Workspaces are subdivisions of an environment, containing files, jobs, and settings. They are only visible in the Enterprise Home website, to enterprise users logged into an environment.

The purpose of workspaces is to allow you to better organize your assets into meaningful categories, e.g. per department. You can also assign different permissions to workspaces so that certain users or groups will only see the workspaces you allow them to see.

Workspaces mostly act as top-level folders, however, there are subtle differences. To determine a file, a workspace and a path within that workspace must be provided – the workspace name is not a part of the path, but a different parameter altogether. This pattern rings true for other assets: jobs require a job ID and workspace name, tasks require a task ID and workspace name, etc.

Communications are a special case: while defined at the environment level, each communication references a workflow file internally, which belongs to a specific project. Furthermore, a communication will only depend on its workflow’s (static) dependencies, which must also belong to that same workspace, thus indirectly associating the communication with a single workspace. This means workspace permissions will affect which communications a user can effectively run, which is why the following security rule is enforced: if a user does not have access to a workspace, then communications referencing that workspace cannot be seen by that user.

In-place review and approval for assets is also enforced at the workspace level, meaning that all the assets in that workspace will be subject to the configured review and approval workflow – except for the workflow file itself, which by design must also belong to that workspace.

Lastly, workspaces may only be created by environment admins and will, by default, only be visible to other admins. Permissions may be set so that other users/groups can see or even manage that workspace. When a user has Manage rights to a workspace, they will have full control over that workspace, regardless of any permission enforced on individual assets.

You can read more information about Workspaces in the EngageCX User Guide.

Licensing

Product Keys

EngageCX solutions cannot be used until they have been licensed. When you download and install the EngageCX platform, you are given the rights to use it through the product keys you have purchased. Each product key dictates what features or components are available and how long can it be used.

EngageCX offers two types of licenses: server-side licenses or environment-based licenses.

Server-side licenses can be installed and managed from the Sysadmin Website, under the Licensing page. These incorporate users access to multiple EngageCX features or components. For example, for a full instance of EngageCX platform, you will have to request from your Account Executive four product keys, one for the EngageCX Platform features (providing access to multiple functionalities, such as communications, forms, customer portal, channels, etc.) and other three product keys for the EngageCX native engines, representing the Publishing Engine, Data Engine or Analytics Engine.

The server-side licenses can be further divided into volume-based keys or CPU-based keys. Volume-based product keys are tailored to the size of the assets you want to generate within the EngageCX Platform. CPU-based product keys come with limits to the number of CPU cores that are available.

Multiple EngageCX Components can use the same product key, but they will share the product key limits. For example, a Publishing Engine license with limits for Page Count restrict to 1000 pages can be shared by two Publishing Engine workers installed on two separate machines. Both workers can generate documents until the 1000 pages limit is reached by one of the servers. In the same way, a Publishing Engine license with limits of 16 LCPU can be used to activate 4 Publishing Engine workers running on 4 separate machines with 4 LCPU each.

Environment-based licenses can be installed and managed from the Enterprise Website. These provide access to the EngageCX Studio tools. To learn how to install and use these types of licenses, please visit the Licensing chapter from the EngageCX User Guide.

Licensing Server

In distributed environments, in order to license individual remote domain components, you need to configure the domain licensing server for each component.

For EngageCX components, access the Domain Services page from the Sysadmin Website. Then, click on the IP Address next to Licensing Services and add the address and port number of the server that hosts the EngageCX Licensing component.

For individual engine components (Publishing Engine, Data Engine or Analytics Engine), open the Management Console tool, access Engine Settings\Miscellaneous of the needed engine and update the Licensing Server Address parameter with the correct IP Address.

Install

In this section, you can learn how to install server-side licenses within the System Administrator website.

Online Installation

If your server has an Internet connection, we recommend using Online Installation for your product keys. Below you can find step by step instructions on how to install a product key online.

1. Sign in to the Sysadmin website and access the Licensing tile.
2. In the Product Keys page, click on the Sign-in button.
3. Next, enter your EngageCX Account credentials and select Sign-in. Notice the green mark that indicates that you are connected with your EngageCX account.
4. Once you are connected to the EngageCX Account, select the +Add License button, at the top-right hand-side.
5. Within the Add Keys dialog, select the keys you want to install, then click on the Install licenses button.

Your product key(s) is now installed and ready to use on your EngageCX Domain.

Offline Installation

If your server is offline or cannot otherwise communicate with our licensing server, you can use Offline Installation. Below you can find step by step instructions on how to install a product key offline.

1. Sign in to the Sysadmin website and access the Licensing tile.
2. Select the +Add License button, at the top-right hand-side.
3. In the Add Key dialog, copy the string generated in the Step 1 box.
4. Next, in a web browser, access your EngageCX account, then select the corresponding Key Id from the Product Keys tab.
5. In the license dialog, select the Install Product Key dialog, paste the string into the Activation Key box, then click Install.
6. Next, copy the activation string, then go to your EngageCX domain page and paste the string into the Step 2 box. Once you're ready, select Finish.

Your product key(s) is now installed and ready to use on your EngageCX Domain.

Notice the Product Keys page that displays meaningful information about your product keys, such as the date on which the license has been activated, the date until the key can be used or usage statics about CPU or utilized volume.

Uninstall

The uninstall process is very similar to the install process, providing both, an online and offline method.

Online Uninstallation

1. In the Product Keys page of the Sysadmin Website, find the product key you want to uninstall, then click the Delete button next to its name.
2. Next, you will be prompted to confirm your selection.

Your product key is now uninstalled from your EngageCX Domain.

Offline Uninstallation

1. In the Product Keys page of the Sysadmin Website, select the Delete button next to the product key you want to uninstall.
2. If EngageCX Platform is not synchronized with EngageCX Account, you will be switched to the Offline Uninstallation. It will provide an uninstall key which you need to copy and use on the account website.
3. Next, sign in to your EngageCX Acount, find the license that you are uninstalling and click its Key ID in the list.
4. In the opened dialog, select Uninstall Product Key and paste the string in the empty box, copied at point 2. Click Uninstall to complete the process. Note that if you skip this step, the product key will continue to appear as being used and you cannot install it on another machine unless manually freed by EngageCX Support.

Your product key is now uninstalled from your EngageCX Domain.

Decommissioning an EngageCX Server

If you’re backing up a server with the goal of decommissioning it, then you must uninstall the product keys on that server before proceeding. This operation should be performed as the last step, after backing up.

System Configuration

System Administrators

EngageCX Domain contains its own system-wide users called system administrators, or sysadmins. These users have full access to the System Administration website, giving them the following permissions:

• Create, edit or delete environments.
• Create, edit or delete users with full access within any environment (also called environment admins).
• Change domain-level settings.

Sysadmins cannot directly log into any environment; however, they can easily gain access to it by creating a new environment admin for that environment. This is because there is no overlap between sysadmin users (stored at the domain level) and regular users (stored at the environment level).

During the software installation, a default username called sysadmin with the password sysadmin is added to the system. For the first login to EngageCX Platform, you will have to use these credentials.

To add other system administrators:

1. Sign in to the Sysadmin Website and select the Users tile.
2. Select the New User button, at the top-right corner.
3. Fill in the form fields. You will have to enter:
   • A unique username for the domain administrator to use when signing in.
   • A strong and secure password.
   • A valid e-mail address for the administrator. All e-mails from the system will be sent to this address.
4. Once you're ready, select Ok.

The system administrator will appear on your Users page.

Environments

Creating a new environment

1. Sign in to the Sysadmin Website and select the Environments tile. From Environments, you can view or manage all existing environments.
2. Select the New environment button, at the top-right corner of the Environments page.
3. Within the New Environment dialog, fill in the form with the mandatory fields:
   • A unique name for the environment.
   • Username and Password for the environment administrator. An administrator can administer multiple environments.
   • An e-mail address.
4. Once you're ready, select Create.

The Edit Environment dialog will appear on your screen from where you can either navigate through tabs to start editing environment settings, either select Ok to configure it later.

Initializing the new environment

Enabling Environments

By default, each new environment is enabled. To enable or disable an environment, go to the Environments page.

• To enable, check the Enabled option, next to the environment you want to edit.
• To disable, uncheck the Enabled option, next to the environment you want to edit.

Sending Welcome E-Mails

When a new user is added to an environment, you may want to send them a friendly welcome e-mail to notify it about their new EngageCX account. Within EngageCX Platform, you can use automation to send or not welcome e-mails to new users, based on your necessities. For each environment, the Sysadmin Website provides an option for the domain administrator users to enable or disable welcome e-mails for the new users created.

To enable/disable welcome e-mails, go to the Environments page and access the environment you want to edit.

• To enable, check the Send welcome email when user is created option.
• To disable, uncheck the Send welcome email when user is created option.

Enabling Environment Modules

Functionalities in EngageCX Solution are grouped and placed in modules so you can easily select the desired module to access all applicable features available to you. To gain access to each module, you will need to visit the Enterprise Website and choose from the list available under the EngageCX Platform welcome page.

To enable/disable an environment module:

1. Sign in to the Sysadmin Website and select the Environments tile.
2. Select the environment you want to edit from the Environments page.
3. Next, access the Environment tab from the Edit Environment dialog. From the Environment tab, you can view a list with all the environment modules available. Check/Uncheck the module(s) you want to use for the selected environment.

Setting Up Environment Administrators

The first user created during the environment creation is mandatory. It is created along with the environment and it is also called environment administrator. Environment admins have unlimited permissions in their own environment. By design, it’s impossible to enforce restrictions on an environment admin within the environment they are managing.

Environment Admins are the only users who have access to the Admin page of the Enterprise Website, as they by default, are included in the Administrators group that has Manage Environment permissions.

Environment admins can also manage access and publish assets to the Customer Portal website, change the accounts and customers schema, design new communications and share them (with enterprise users or customers).

To set up new administrators for an environment:

1. Access the Environments page and select the environment you want to edit.
2. Go to the Administrators tab in the Edit Environment dialog. The Administrators tab will display the existing administrators and their last login, and also allows you to enable/disable one admin or reset the password.
3. To create a new environment administrator, select the +New button.
4. In the Configure Admin dialog, fill in the mandatory fields:
   • Select the Authentication type: EngageCX Authentication or Windows Authentication.
   • An admin username and a password, respectively the domain admin user.
   • An e-mail address.
5. Once you're ready, select Create.

The admin user will appear now on your Administrators list.

Authentication

Authentication is the process through which system administrators grant a user access to the EngageCX Platform. Authentication to the EngageCX Enterprise Website can be accomplished in different ways, such as built-in users created through the EngageCX Platform, using an external system that stores user's credentials, such as Active Directory or accessing EngageCX Platform through Single Sign-On.

Users can log in to the Enterprise Website using one of the following methods:

• EngageCX Authentication
• Authentication using Active Directory credentials
• Single Sign-On

EngageCX Authentication

This type of authentication contains all the EngageCX Platform built-in users created by an environment administrator.

To add a new user to the Enterprise Website:

1. Sign in to the Enterprise Website and access the Admin module.
2. Select the Users tab.
3. Click the +New User button, at the upper-right side.
4. For each user, you will have to provide an e-mail address, username and password. Optionally, you can enable or disable the user, add the user to groups or provide different permissions. Please visit the Users and Groups section of the EngageCX User Guide to learn more about Users and Groups.

Active Directory Authentication

One of the most common ways to authenticate to EngageCX Platform is by using Active Directory users. This allows your users to use the same credentials to log in to the EngageCX Platform as they use with their computer or other services, and also allows you to keep all information in a central location, preventing you for losing data. When a user signs in using an Active Directory, EngageCX will validate their username and password through the Windows principles in the operating system. If you intend to share environments between users, using an external system to store user credentials, such as Active Directory is a good practice.

Using Active Directory users with EngageCX requires you to enable the Use Active Directory to authenticate users option available in the Domain\Authentication page of the EngageCX Sysadmin Website.

Once the property is enabled, AD users will automatically be granted access to the EngageCX Platform when they log in. Upon logging into the EngageCX Platform with an AD user, the system will automatically synchronize with the Active Directory by creating an associated user inside the EngageCX System. Note that only the required information about the user (such as the Name and e-mail address) will be stored in the EngageCX Platform. Sensitive information, such as the password, will not be stored.

Logging in using an AD user requires the following username structure:

Domain\UserSyntax

Authorization

By default, after logging into the EngageCX Platform, the AD User will not have any permission. Permissions can be provided by mapping EngageCX Groups to AD Groups.

To map the two groups:

• Sign in to the Enterprise Website and access the Admin module.
• Select the Groups tab.
• Select the needed group from the list. Additionally, you can click on the +New Group button to include new groups.
• In the Group Dialog, enter the group(s) you may want to synchronize under the Active Directory Groups field.
• To provide different group permissions, simply, scroll down in the Group page and enable the needed permissions.

Single Sign-On

Single Sign-On (SSO) is an authentication process that allows users to enter one set of credentials and access multiple applications. The process authenticates the user for all the applications they have been given rights to and eliminates further prompts when they switch applications during a session.

An EngageCX environment can be configured to use:

• Single Sign-On using Windows Authentication
• Single Sign-On using SAML or WS-Fed

Single Sign-On using Windows Authentication

Windows SSO uses the Active Directory user that is currently logged into the computer to access the EngageCX Platform. The same authorization and synchronization principles described in the Authentication using Active Directory are applicable for Windows SSO.

Configuration

To use Windows Authentication, you will need to make the following settings in IIS Manager:

• From the Connection Tree View, navigate to the EngageCX Website that you wish to enable windows authentication.
• Double click on the Configuration Editor button, under the Management section.
• From the Configuration Editor dialog, select
  system.Webserver\security\authentication\windowsAuthentication
• Unlock the configuration by selecting the Unlock Section button.
• Change the value of the enabled property to True.
• Repeat the steps from above to unlock configuration for the anonymousAuthentication property, as well:
  • From the Configuration Editor dialog, select
    System.Webserver\security\authentication\anonymousAuthentication
  • Unlock the configuration by selecting Unlock Section
  • Make sure that the enabled property is set to true.

Login

To log in to Enterprise Website with windows authentication, you need to access the following URL:

{Enterprise_Website_URL_and_Port_Number}/windows/login?environment={environmentName}

Single Sign-On using SAML or WS-Fed

Single Sign-On consists of using a single set of credentials to log into multiple applications. Setting up the Single Sign-On solution in EngageCX Platform, provides authorized access to users through a simple and easy process. EngageCX comes with a friendly setup assistant and a series of well-defined steps for Single Sign-On configurations. The Single Sign-On process can be enabled either for EngageCX Enterprise users, either for Customer Portal users.

EngageCX Platform acts as a service provider(SP) for SSO. When setting up SSO, a trusted relationship between the Identity Provider and the EngageCX Platform will be created. This enables users to authenticate to the Identity Provider website, then access EngageCX Solutions in a secured way.

EngageCX offers two ways to use Single Sign-On:

• SSO with Security Assertion Markup language (SAML 2.0)
• SSO with Web Services Federation (WS-Federation)

In a nutshell, setting up a Single Sign-On connection through EngageCX involves the following steps:

• Set up your Identity Provider using EngageCX Information.
• Configure EngageCX Single Sign-On using information received from your IdP.
• Verify the Single Sign-On configuration.

Single Sign-On using SAML

• When you set up the Single Sign-On connection with SAML protocol, you will have to provide to your IdP the following information:

  ACS URL	This indicates the location to which the SSO Tokens will be sent. Access the Single Sign-On dialog wizard, go to the Setup IDP step and select Copy to Clipboard, next to the ACS URL box, then forward the link to your IdP. For example, the link should like this: https://EngageCXServer:PortNumber/Security/ConsumeSAMLToken?environment=EnvironmentName
  Single LogOut	When the Single Sign-On is enabled, logging out from EngageCX Website will bring users back to their EngageCX login page. To enable log out, the Single Logout URL that needs to be configured should look like this: http://ecrionserver:8094/Security/LogOut

• Once the Identity Provider has finished configuration of the Single Sign-On process, to create the setup within EngageCX Enterprise Website, you will have to follow the SSO wizard provided by EngageCX. For more details, please visit the Single Sign-On page from the EngageCX User Guide to learn how to configure it.

• Once the configuration is ready on both sides, open a web browser and navigate to the Single Sign-On URL. It should look like this: http://EngageCXServer:PortNumber/security/login?environmentName=envName You will be redirected to the IdP Sign-in page. Log in using your IdP credentials. If everything is working properly, you will be redirected to the EngageCX Enterprise Website.

Setting Up SSO with WS-Federation

• Setting up the Single Sign-On with WS-Federation protocol, will require to work with you your Identity Provider to create a relying party trust connection. While creating the Relying Party Trust, you will have to forward the following information to your IdP:

  ACS URL	This indicates the location to which the SSO Tokens will be sent. Access the Single Sign-On dialog wizard, go to the Setup IDP step and select Copy to Clipboard, next to the ACS URL box, then forward the link to your IdP. For example, the link should like this: http://EngageCXServer:PortNumber/Security/ConsumeSAMLToken?environment=EnvironmentName
  EngageCX URL	If you want to enable Single Sign-On for Enterprise Users, you will have to provide the Enterprise Website URL to your IdP. If you want to enable Single Sign-On for Customer Portal Users, you will have to provide the Customer Portal Website URL to your IdP.

• Update the EngageCX web.config file:

Go to the EngageCX Installation folder (\EngageCX\Engage 2018), navigate to the EngageCX Website on which you want to enable SSO and open the Web.config file. The file needs to be updated as follows:

a. Comment the <customErrors> lines:

    <customErrors mode="On" defaultRedirect="~/Error">
        <error redirect="~/Error/NotFound" statusCode="404"/>
        <error redirect="~/Error/InternalServer" statusCode="500"/>
    </customErrors>

b. At the end of the configuration file, add the system.IdentityModel, as follows. Note that it should be included between the </runtime> and </configuration> tags.

    <system.identityModel>  
        <identityConfiguration>  
            <audienceUris>  
    <!--The value indicates the URL to the EngageCX Website on which you enabled Single Sign-On (Enterprise or Customer Portal)-->
                <add value="https://ecrionserver:portnumber" /> 
            </audienceUris>  
    <certificateValidation certificateValidationMode="None" />  
    <issuerNameRegistry type="System.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry, System.IdentityModel, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089">  
        <trustedIssuers>  
    <!-- Add the Certificate Thumprint and the Certificate Name (e.g. Subject) used in the Relying Party Trust configured by your Identity Provider -->
            <add thumbprint="********" name="*****"/>
        </trustedIssuers>  
    </issuerNameRegistry>  
    </identityConfiguration>  
    </system.identityModel>  
    <system.identityModel.services>  
    <federationConfiguration>  
    <!-- Issuer = the IdP Server URL
         Realm = the IIS EngageCX Website URL, e.g.  https://ecrionserver:portnumber
         Reply = the IIS EngageCX Website URL, e.g. https://ecrionserver:portnumber  -->
            <wsFederation passiveRedirectEnabled="true" issuer="https://idpserver" realm="https://ecrionserver:portnumber" reply="https://ecrionserver:portnumber" requireHttps="true" />
            <wsFederation passiveRedirectEnabled="true" issuer="https://idpserver" realm="https://ecrionserver:portnumber" reply="https://ecrionserver:portnumber" requireHttps="false" />
            <cookieHandler requireSsl="false" />  
    </federationConfiguration>  
    </system.identityModel.services>

• Once you're ready, save the configuration file, then access the EngageCX Enterprise Website and go to the Single Sign-On page to add the information received from your IdP to the SSO wizard.

Other Authentication Settings

From the EngageCX Sysadmin Website, you can also manage other important authentication settings. To access the authentication page, you need to follow the steps below:

1. Sign in to the System Administrator Website and access the Domain tile.
2. Select the Authentication option under the Settings group.

The Authentication page allows you to configure the following:

Use Active Directory to authenticate users	Check this option if you want to toggle Active Directory logins to the EngageCX system.
Force new users to change their password on first-time login	This option will force a new user to change the password at the first log in. It is not available for users that authenticate with Active Directory or SSO. The option is useful for two reasons, it will simplify the process of adding new EngageCX users for system administrator and also adds a security benefit.
Max session duration	In addition to the property from above, you can also specify the session duration, in seconds (0 represent infinitely) of the new user’s login. After the set period ends, users will be logged out from their Environment.
Captcha enabled	Checking this option will enable Google reCaptcha. The keys retrieved by configuring reCaptcha on Google website are necessary to be added here to invoke Google reCaptcha.

Services

Configure Domain Services

To perform management and operational tasks on an EngageCX distributed environment, an administrator must ensure that all the IP Addresses and Port Numbers of the remote servers that host EngageCX Components are correct and are pointing out to the right EngageCX service, allowing EngageCX to establish a stable and reachable connection between its components. These connections have to be configured from the Domain Services page. Initial services values (for Publishing Engine, Data Engine, Analytics Engine, etc.) are also called default workers.

A typical use case when you have to update the Domain Services can be when you installed all EngageCX components on a server, (e.g. having IP Address X.X.X.X), lesser the Search component, which is isolated on a separate server (e.g. having IP Address Y.Y.Y.Y). To access the Search component, from the server that contains the Admin Website, you will have to update the Search Services with the corresponding IP Address (e.g. for our case, you will have to enter the following address - Y.Y.Y.Y) and Port Number of the server hosting the Search component.

To access the Domain page:

1. Sign in to the Sysadmin website and access the Domain tile.
2. Select the Services option under the Settings group.

By default, no nodes are configured, in which case EngageCX will look for the services at the address specified by the initial values in the main configuration file. Within the Services page you can configure the following:

• Publishing Engine
  • Select the IP Address next to the Publishing Engine to configure the IP Address and the port number on which the publishing engine will run.
  • The default Port Number is 40017.
• Date Engine
  • Select the IP Address next to Data Engine to configure the IP Address and the port number on which the data engine will run.
  • The default Port Number is 40021.
• Analytics Engine
  • Select the IP Address next to the Analytics Engine to configure the IP Address and the port number on which the analytics engine will run.
  • The default Port Number is 40023.
• Backend Services
  • Select the IP Address next to the Backend Services to configure the IP Address and the ports for services related to the backend.
  • The default Port Numbers are, as follows:
    • Workflow Port: 40015.
    • Triggers Port: 40020.
    • Scheduler Port: 40022.
    • Alert Port: 40025.
    • Distribution Port: 40024.
    • Notification Port: 40029.
    • Crawler Port: 9100.
    • Background Port: 40026.
    • Backup Service Port: 40030.
• Repository Services
  • Select the IP Address next to the Repository Services to configure the IP Address and the ports for services related to the repository.
  • The default Port Numbers are, as follows:
    • Storage Port: 40014.
    • Repository Port: 40016.
• Search Services
  • Select the IP Address next to the Search Services to configure the IP Address and the port number for the search service.
  • The default Port Number is 40028.
• Licensing Services
  • Select the IP Address next to the Licensing Services to configure the IP Address and the port number for the licensing service.
  • The default Port Number is 40035.

For each change, select Save to apply the changes and refresh the page.

Configure Backend Services

Accessing the Backend Service configuration page, many options are enabled for your services that run in backend.

1. Access the Domain page.
2. Select Configure next to Backend Services.
3. Enable/Disable from the available options within the configuration page:
   • Analytics Crawler - if enabled, the service will crawl the environment activity like document productions, distributed tickets, promotion ads and also will prepare the database for environment dashboards.
   • CRM Synchronization - if enabled, services within the CRM Synchronization will handle the synchronization of accounts/contacts with connections defined in Environment Settings.
   • Background Alerts - if enabled, alerts keep users updated by notifying them through email whenever a report is defined on a view and an important process is encountered within that view.
   • Environment Healthcheck - if enabled, the service computes and verifies the information from the environments and keeps the application running efficiently and flawlessly.
   • Task Notification - enable the option and the users are allowed to set reminders for their manual tasks.
   • Engagement - if enabled, engagement module's role will perform actions defined in Customer Journey and Touchpoints due to Engagement Services.
   • Domain health check - if enabled, the Domain Health Check will be required to delete the expired tokens from the Enterprise Portal and Sysadmin Website, in order to free storage; this option is also responsible for the defragmentation of indexes within the database and cleaning up the system log file.
   • Reclaim free space - if enabled, the service verifies the repository for files marked as deleted and releases the disk that was previously allocated to those files; the reclaim schedule can be configured by clicking Change, next to this option.
   • Check Database Defragmentation - when enabled, the option maintain the database performance, reorganize and rebuild fragmented indexes; the database defragmentation schedule can be configured by clicking Change, next to this option.
   • Reorganize - if enabled, this option reorganizes all indexes from the database greater than your given Fragmentation tresh parameter.
   • Rebuild - if enabled, this option rebuilds all indexes from the database greater than your given Fragmentation tresh parameter; in case the Reorganize option is enabled also, the rebuild operation will be performed between the two values of the Fragmentation tresh.
   • Clean up Expired Tokens - if enabled, the option deletes all the expired tokens from Enterprise, Sysadmin and Customer Portal; the clean up expired tokens schedule can be configured by clicking Change, next to this option.
   • System log maintenance - if enabled, the system log file accumulates information for the previous running Domain and Environments background services; the system log schedule can be configured by clicking Change, next to this option.

Configure additional services at environment level

EngageCX also provides you with options for using different Publishing Engine, Data Engine or Analytics Engine per environment. The initial connections, set up in Domain Services, are also called default workers, while connections set up at environment level, are called multiple workers. Multiple Publishing, Data and Analytics nodes may be used by the same EngageCX server to boost throughput. The nodes will be selected using round-robin. This functionality is native to EngageCX Software and does not require an external load balancer.

To set up multiple workers per environment:

1. Sign in to the Sysadmin website and access the Environments tile.
2. Next, select the environment you want to edit, then navigate to the Connections tab.
3. By default, default workers are visible. To configure a new connection, select the +New Connection button, then choose the engine you want to configure: for a server that hosts Publishing Engine, select Reporting Server, for a server that hosts Data Engine, select DA Server, and for Analytics Engine select the Analytics Server.
4. Next, fill in the form fields. You will have to provide:
   • A unique name for the connection.
   • The IP Address of the server that hosts the component you want to point out.
   • The corresponding Port Number that will be used to communicate with the server.

The machine containing the EngageCX Service will need to have in its main configuration file the following line:

RepositoryAddress=<EngageCX Service IP>

The IP used above must be the IP as seen from the machine(s) where the Publishing, Data and/or Analytics nodes are installed.

Search

For each environment, you may enable or disable the Search module. In a new environment, the search will be off, by default. Below you can find step by step instructions on how to configure Search in an environment.. Note that the configuration steps should be repeated for every environment.

Configuring Search

1. Sign in to the Sysadmin Website and access the Environments tile.
2. Select the environment you want to edit, then navigate to the Search tab.
3. Select the Configure button.
4. Within the Search Configuration dialog, select the search engine:
   • Database: use the database configured during installation for search.
   • Elastic: use an Elastic Search instance.
5. Configure additional crawling options by checking the following options:
   • Crawl Job Output: will crawl the generated files, i.e. the files under Jobs; this could significantly increase crawl time if you generate many documents;
   • Crawl Document Content: will also use full-text search, so as to crawl the contents of documents; having a large collection of documents will significantly increase crawl time.
   • Enable Search for Portal Website.
6. Once you are finished, select Save. The Search bar will be available in the Enterprise Website, at the top right side of the window.

Long crawl times don’t affect the system’s performance. Instead, what this means is that new and modified items will take longer to appear in the search results due to the fact that the service takes a long time to index them.

Full Crawl

A Full crawl is required the first time when the Search database is configured. Once a Full Crawl is started, it can either find no results, if the EngageCX database is empty, or it can display status information. To run it, click on the Full Crawler dropdown next to the Configure button and select Start. Information about the current configuration, crawler status, and indexed items will appear on the page. When the drop-down says Full Crawler (finished), your search is configured.

Users logging into the environment (on the Enterprise Home website) will now see the search bar at the top right of each page, on the navigation bar. To learn more information about the Search bar and Search center, please visit the Search chapter from EngageCX User Guide.

E-Mail

If you are trying to set up e-mail notifications or amazon connections, then the settings below should help you get up and running in no time.

Domain e-mails

System Administrators can configure an e-mail connection to use it for e-mail notifications. For example, when new accounts are created, the user will retrieve a welcome e-mail, for which EngageCX Platform will use the e-mail connection configured here. Or, when this connection is configured, users will be notified when new tasks are assigned.

To configure a domain e-mail:

1. Sign in to the Sysadmin website and access the Domain tile.
2. Select the e-mail option under the Settings group.
3. Fill in the form fields. You will have to enter:
   • A server hostname or an IP Address.
   • A port number. By default, the port number is 25.
   • A username and a password.
   • An e-mail address that will be used when sending e-mails using this connection.
   • Decide if the connection is encrypted or not.

Amazon

If you intend on setting up an Amazon connection through EngageCX Platform, you will have to set Amazon in the EngageCX Domain Settings.

To configure Amazon:

1. Sign in to the Sysadmin website and access the Domain tile.
2. Select the Amazon option under the Settings group.
3. Fill in the form fields. You will have to enter:
   • The Amazon AWS access key.
   • The Amazon AWS secret access key.
   • The Amazon AWS region.

While Amazon is configured in EngageCX Domain, environment users will be able to configure e-mail SES Connections and SMS Connections in the Enterprise Website. e-mail SES is useful if you want that e-mails configured in Enterprise Website to have a better status, such as delivered, complained or rejected.

Miscellaneous

URLs

From URLs page, you can configure or update the URL used to access the EngageCX Websites: Enterprise, Customer Portal or Sysadmin. These are used in both, single or distributed installation. If you deployed EngageCX components across multiple servers, to ensure a reliable communication between instances, you have to update the corresponding URLs. Each URL needs to reflect an existing website. For example, if you want to change the port of a website, you must ensure that the same configurations are done in IIS/HA, as well.

Aside from this, these websites also have other roles. For example, the Enterprise URL is used to send e-mails when a new user is created. Or, Portal URL is used to distribute e-mails that contain links to shared files for your organization customers.

To access the URLs page:

1. Sign in to the Sysadmin website and access the Domain tile.
2. Select the URLs hyperlink under the Settings group.

Each URL must contain the IP Address or the domain name of the server hosting the website, as well as the port number on which the website is available.

By default, EngageCX Websites are available at the following ports:

• Enterprise Website: port 8094
• Customers Portal Website: port 8096
• Sysadmin Website: port 8095

EngageCX Studio

EngageCX Studio is a powerful software, integrated into the EngageCX Platform that comes with multiple tools that will help you to create dynamic documents, uniforms outputs, powerful dashboards or synchronize local files with the EngageCX platform. The product suite provided by EngageCX Studio is formed by four products:

• Publisher, a visual design tool used to design professional document templates, which integrates well with the other EngageCX products. These templates are used at runtime by EngageCX server software to generate documents dynamically from data in high volumes.
• Modeler, a visual design tool used for designing a singular powerful data source from combining, cleansing, and transforming your enterprise data from wherever it resides in a graphical environment. Having the ability to view where your data is coming from and change mappings help speed up the development process.
• Analyst, a powerful dashboard design application for visualizing, filtering, analyzing and interpreting enterprise data.
• Additionally, with the installation tool, EngageCX Studio will also install the EngageCX Drive component, that allows you to synchronize your local files with the EngageCX Solutions assets.

To download the design software, you will have to access the Enterprise Website and go to the Developer\Software page. Please visit the Developer chapter of the EngageCX User Guide to read more information about it. For more details on how to use each EngageCX Studio product, please visit the EngageCX Studio Documentation documentation.

EngageCX Solutions allows the administrators to handpick the build version available in the Enterprise Website, from URLs page.

To configure the EngageCX Studio version:

1. Sign in to the Sysadmin website and access the Domain tile.
2. Select the URLs option under the Settings group.
3. Next, you can choose to use the latest version available of EngageCX Studio, by checking Use latest version, or click the empty box and enter the URL to the EngageCX Studio tool.

Restrictions

A job is one of the most important element when creating documents through EngageCX Platform. It refers to a process (e.g. workflow) that is executing or has finished executing. Jobs can be run from the Enterprise Website.

Each time when running a job, a new access token is created. The access token has limited availability and this can be managed from the Job revocable token validity option. If the job will exceed the time you have set up, your job will fail. For example, you have created a workflow that contains a manual step. You can use the token validity option to restrict the time other users can solve that manual step.

Note that the same validity is imposed on the token generated through API Keys.

To change the validity time of an access token:

1. Sign in to the Sysadmin website and access the Domain tile.
2. Select the Restrictions option from the Settings group.
3. Enter the new value, in seconds, under the empty box.

Below there are some configurations that will give to the sysadmin more control over the distribution of services within SMTP connections.

To change the number of parallel clients per SMTP connection:

1. Sign in to the Sysadmin website and access the Domain tile.
2. Select the Restrictions option from the Settings group.
3. Enter the new value under the corresponding box.

To change the retry count for a failed SMTP connection:

1. Sign in to the Sysadmin website and access the Domain tile.
2. Select the Restrictions option from the Settings group.
3. Enter the new value, in milliseconds, under the corresponding box. The provided value will represent the number of retries whenever the SMTP connection fails.

To change the wait time between retries of reloading a SMTP connection:

1. Sign in to the Sysadmin website and access the Domain tile.
2. Select the Restrictions option from the Settings group.
3. Enter the new value, in milliseconds, under the corresponding box. The provided value will represent the time to wait until the next retry will be performed.

Number of Threads

For each environment, you can specify how many threads to use for EngageCX services to run the jobs. By default, each environment will use a small instance of 4 threads. To change the number of threads, simply select the needed value from the drop-down menu.

Note that, adding multiple threads doesn't speed up the processing of a single document. It will enable users to process multiple documents at the same time. If the server has adequate resources, then processing multiple documents should scale linearly.

Maintenance

Domain Health Check

The Domain Health Check is required to delete the expired tokens from the Enterprise Website and Sysadmin Website, in order to free storage space by using three specific operations such as SanitizeRepository, ZapRepository and CompactStorage. It is also responsible for the defragmentation of indexes within the database and cleaning up the system log.

By default, these operations are set to true, but they can be manually disabled from the main configuration file. The options can be switched off by using the following parameters:

CleanupExpiredTokensEnabled = false <!-- Disable the parameter for deleting the expired tokens from the Enterprise Portal and Sysadmin Website --> 
ReclaimFreeSpaceEnabled = false <!-- Free the storage space by executing the three operations: SanitizeRepository, ZapRepository and CompactStorage -->
CheckDatabaseDefragmentionEnabled = false <!-- Fragment the database indexes -->
CleanUpSystemLogEnabled = false <!-- Clean up the System Log -->

Configuring Database Settings

Ecrion enables a page which provides the capability to configure a retry for database errors. Basically, if you have some options described below configured and a deadlock occurred, the system will retry the operation. By default, no retry is done.

1. Login to the Sysadmin Website and access the Domain tile.
2. Select the Database Details hyperlink to navigate to the Database page.
3. Enter the new value under the corresponding box for SQL Connection Retries. The value represents the number of retries whenever the Database connection fails.
4. Provide the value for SQL Wait Time Retry, in milliseconds, under the corresponding box. The provided value will represent the time to wait until the next retry will be performed.

Storage

As the Storage is designed to support continuous operations, Ecrion provides a series of features to help system administrator to maintain it at a high-level.

There are two ways of maintaining the Ecrion Storage:

• By accessing the Storage Page.
• By using the Storage Tool.

Storage Page

Ecrion provides the Storage Page that allows you to monitor and perform additional administration tasks on your storage folder.

1. Sign in to the Sysadmin website and select the Domain tile.
2. Under the Summary section, you can see the Storage space and the percentage of the space you can save after running the compact command. Select the Storage Details hyperlink for more details and additional tasks.
3. The Storage page provides information regarding the storage location and checks disk space. In addition, you can perform operations in case of storage breakage, such as:
   • Repair Now: If the Status shows errors, proceed with selecting the Repair Now button. This operation will start a process in the background that will verify if there are any corrupted data in the storage folder, and will try to fix the files.

     Important Note

     We highly recommend contacting Ecrion Technical Support to discuss the best options for your organization before running the repair storage command.

     
   • Reclaim Now: The option allows you to free up the Ecrion storage by deleting old data you do not longer need. You will be prompted to confirm your selection to start the compact process. When the process is ready, you will be able to see a list with all the storage data file that has been compacted.

Storage Checker Tool

Another way to manage the Ecrion storage is by using the Storage Checker tool. To have access to the Storage Checker tool, you need to check the Storage Checker Utility, Maintenance Utility and Logs Migration Utility option, available in the Document Repository Settings step of the installation wizard.

The tool can be found in < Installation Folder >\Windows Service\EOSUtility\StorageChecker\StorageUtility.exe

The Storage tool uses the following general syntax:

StorageUtility.exe
        [-command checkStorage|compactStorage|repairStorage|encryptStorage]
        [-u <sysadmin username>]
        [-p <sysadmin password>]
        [-logLevel None|Normal|Debug]
        [-outputFilePath <Path>]
        [-configFile <config File Path>]

Quick Reference

The table below provides a quick reference to the various parameters and options available.

Parameter	Occurence	Description
-command	Required	Runs the specified command.
-u	Required	Specifies the system administrator username.
-p	Required	Specifies the system administrator password.
-loglevel	Optional	Sets the log level events to be reported.
-outputFilePath	Optional	Specifies the location of the generated log files.
-configFile	Optional	Specifies the path to the configuration file.

Storage Commands

The tool has four functionalities: check, compact, repair or encrypt.

Check Storage

The Check Storage command verifies if there are any invalid < version of > documents present in the storage and provides access to detailed storage information such as storage size, encrypted or unencrypted size and compacting storage size.

Usage example for checking storage:

StorageUtility.exe -command checkStorage -u sysadmin -p sysadmin 

Compact Storage

Compact Storage command verifies the storage for files marked as deleted by Ecrion (either from UI or API) and releases the disk space that was previously allocated to those files. The tool also defragments the storage.

This operation is performed automatically at the end of each day on the server where Ecrion is running. However, if you would like to perform this operation manually, please see below:

Usage example for compacting storage:

StorageUtility.exe -command compactStorage -u sysadmin -p sysadmin

Repair Storage

Repair Storage command allows you to repair damage data of your storage folder. For example, if you encounter a power outage that led to corrupted data, you can use the repairStorage command to retread the storage.

The Repair Storage command comes with two options: users can just read a full report of their corrupted data, by adding the -readonly flag, or they can directly start repairing the storage data.

Usage examples for repairing storage:

To obtain a report with all the .dat files that can be repaired in your storage folder:

StorageUtility.exe -command repairStorage -u sysadmin -p sysadmin -readonly

To start repairing the storage data, use the following command:

StorageUtility.exe -command repairStorage -u sysadmin -p sysadmin 

Encrypt Storage

Storage encryption is a controlled-based solution that provides the capability to encrypt the storage data, ensuring protection over your Ecrion Storage assets.

The encrypt storage command should be used when you want your Storage data to be encrypted. Another important use case of the storage encryption applies if you want to migrate a single Ecrion instance in an HA environment, it is necessary to encrypt your storage data first.

Usage example for encrypting storage:

StorageUtility.exe -command encryptStorage -u sysadmin -p sysadmin -readonly

Username and Password

Storage Utility provides a password-controlled mechanism for administering storage operations. Each time when running a storage command in CLI, you will have to specify the username and the password of the Ecrion Domain, as follows:

StorageUtility -command <enter command> -u sysadmin -p sysadmin

Storage Utility Log

Storage Utility allows you to enable logging when performing operations to the storage data. Enabling logging allows you to record different events that happen when you run a command.

Logging can be enabled by configuring the level of the events you want to track, and also a path to the file that will store that information.

The available log levels are: None, Normal or Debug.

When enabled, Storage Utility will display the events details in the console or in the output file, if specified.

Enabling logging is possible by using the -logLevel parameter, as follows:

StorageUtility -command <enter command> -u <username> - p <password> -logLevel Debug 

Output Location

When running a command on the Storage Data, you can choose how would you like to view the results. Storage Utility allows you to view all the results directly in the Command Line interface console or you can save the output results to an external file.

To append the output to an external file, you will need to specify the file location on the disk drive, as follows:

StorageUtility -command <enter command> -u <username> -p <password> -outputFilePath C:\out\file.txt 

Configuration File

Storage Utility allows you to specify the Ecrion configuration file to be used. By default, on a single-deployment installation, Storage Utility will read the configuration settings from the default configuration file location, which is %Application_Data%\Ecrion and it is not necessary to use this parameter.

In cases when you want to perform storage commands from a remote server, Storage Utility will require reading its settings from a configuration file in order to run. This should be a copy of the Ecrion configuration file (EOS4.config) from a machine running one of the Ecrion websites.

To perform remotely storage commands, you must point the tool to the configuration file via the -configFile parameter (the file provided will tell the Storage tool which storage folder to use).

To use the -configFile parameter, use a syntax as follows:

StorageUtility -command <enter command> -u <username> -p <password> -configFile %Application_Data%\Ecrion\EOS4.config 

Backup

Backup Process

There are three ways for backing up Ecrion files:

• Using the System Administrator Interface.
• Using the Command Line.
• Performing a Manual Backup.

Managing Backups using the Sysadmin Interface

The easiest way to create backups is by accessing the Backup page available under the system administrator interface. The Backup page allows you to configure settings, schedule periodic backups, view old backups or run backup manually.

Before Backup

Before you start running a backup, it may be necessary to configure the backup settings first. In the section below you can learn how to shape the backup configuration to meet your organization needs.

Prerequisites

Backup requires .NET Framework 4.5 and SQL Server Command Line Utilities.

Configuring Backup Settings

1. Login to the Sysadmin Website and access the Domain tile.
2. Select the Backup Details hyperlink to navigate to the Backup page.
3. Next, select Configure to start configuring backups. Note that modification will be automatically saved, on blur input event and a feedback message will be shown.

Within the Backup Settings page you can configure the following:

Backup Location

In the Backup Location box, you can enter the local or network path to the Backup Folder destination. To verify if the backup can be done in the specified folder, click on the Test button. If everything works successfully, you will notice this message: Test was successful.

When changing the backup folder location, the Ecrion Database and Ecrion Service must have write access to that folder.

After running the backup, you will be able to see the following files in the backup folder:

• The SQL Backup file;
• The Storage archive file;
• The Backup manifest file that specifies the directory structure and backup description.

Full Backup Script

The Full Backup Script box displays commands to create a full backup of your Ecrion data, for both, database and storage. At any time, system administrators can edit the backup script, to meet their organization needs.

The backup script uses two commands, sqlcmd, for the Ecrion database backup, and eosbackup, for the storage backup. You can customize the scripts by adding CLI commands or by using the System Placeholders, visible in the right side.

Creating an On-Demand Backup

Below you can find step by step instructions for creating backups from system administrator interface.

1. Login to the Sysadmin website and access the Domain tile.
2. Select the Backup Details hyperlink to navigate to the Backup page.
3. Use Backup Now, to start a manual backup process. Note that while a backup is running, the Backup Now button will be disabled and the caption will be changed to Running backup... You cannot start a new backup until the current backup is finished.
4. The process can take from several seconds to some hours depending on database and storage sizes. Once the backup is complete, the new backup will show up in the list of available backups.
5. Optionally, you can select the Log page to access the Backup Log page where additional information is displayed. The backup log can also be used for troubleshooting.

Scheduling an Automatically Backup Process

1. Login to the Sysadmin website and access the Domain tile.
2. Select the Backup Details hyperlink to navigate to the Backup page.
3. Select the Change hyperlink, to start configuring an automatic backup process. You will need to set up days and hours for when you want your backup to be run automatically.
4. When you're ready, check the Enabled option to start the backup schedule, then click Ok.

Creating Backups using the Command Line Tool

Another way to perform a backup is by using the Ecrion backup tool.

The default location is : <Installation Folder>\Windows Service\EOS Utility\EOSBackup\Tools.EOSBackup.exe.

The tool will backup and restore Ecrion Database and Ecrion Storage. As in the user interface, it can also backup and restore files in/from a shared network folder or an Amazon S3 folder.

Syntax:

Tools.EOSBackup.exe
    [ -backup2 | -restore | -getbackups | -examples ]
    [ -u <sysadmin username> ]
    [ -p <sysadmin password> ]
    [ -backupName <backupName> ]
    [ -backUpFolder <networkFolderPath> ]
    [ -configFile <EOS4 config file> ]
    [ -backupScript <backup script> ]
    [ -restoreScript <restore script> ]
    [ -backupDescription <backupDescription> ]

Steps:

1. Navigate to your installation folder (e.g. %Installation_Path%\Ecrion\Engage 2018 (64 bit).)
2. Find the EOSBackup subfolder under Windows Service\EOS Utility\EOSBackup.
3. Open a command prompt to this location.
4. Run the command below to create a backup for your files, using the default location. Note that you will need to provide the username and password used to access the Ecrion Domain. Optionally, you can add a simple description that will appear in the backup manifest file. Tools.EOSBackup.exe -backup2 -u sysadmin -p sysadminpassword -backupDescription "some description"
5. When the backup is complete, a message will be displayed, confirming that Ecrion has successfully written its data to the file you specified.

Performing a Manual Backup

Before attempting a manual backup, you will need to stop all the Ecrion services and websites.

To perform a manual backup, follow the steps below:

• Back up the Storage Folder, located by default at <%Application_Data%\Ecrion\EOSStorage>.
• Back up the Ecrion Database.

We strongly recommend saving a copy of your main configuration files (EOS.config and PublisherSvc.config mandatory, DASSvc.config and BISvc.config, if necessary) along with the backup for future reference.

Restore

Before Restoring

As a best practice, we recommend disabling user access to the system by stopping all Ecrion websites for the duration of the restore (using IIS Manager).

Prerequisites

Before you restore Ecrion data, it might be necessary to:

• Create at least one backup of your data before proceeding with the restore processes.
• Make sure the machine that runs the restore has .NET Framework 4.5 and SQL Server Command-Line Utilities.

Restore Process

There are three ways for restoring Ecrion data:

• Using the System Administrator Interface.
• Using the Command Line.
• Performing a Manual Restore

Restoring a Backup using the Sysadmin Interface

1. Log in as a System Administrator and access the Domain module.
2. Select the Backup Details hyperlink to navigate to the Backup page.
3. Select Restore, to start a (manual) restore process. Note that while the restore is running, the Restore button will be disabled and the caption will be changed to Restoring... You cannot start a new restore process until the current restore is finished.
4. The process can take from several seconds to some hours depending on database and storage sizes. Once the restore is complete, the restore hyperlink will become available.
5. Optionally, you can click Log to access the Backup Log page where additional information is displayed. The backup log can also be used for troubleshooting.

Restoring a Backup using the Command Line

1. Navigate to your installation folder (e.g. %Installation_Path%\Ecrion\Engage 2018 (64 bit)).
2. Find the EOSBackup subfolder under Windows Service\EOS Utility\EOSBackup.
3. Open a Command prompt to this location.
4. Run the command below to see all the backups available: Tools.EOSBackup.exe -getbackups -u sysadmin -p sysadminpassword
5. Run the command below to restore a specific backup (e.g. backup with number 20180228120843): Tools.EOSBackup.exe -restore2 -u sysadmin -p sysadminpassword -backupName 20180301101600
6. When the restore is complete, a message will be displayed, confirming that Ecrion has successfully finished the process.

Performing a Manual Restore

Before attempting a manual restore, you will need to stop the Ecrion services and the Ecrion Websites.

To perform a manual restore:

• Restore the Storage Folder from a previously created backup.
• Restore the Ecrion Database from a previously created backup.
• Start the Ecrion Websites from IIS Manager.
• Start the Ecrion services from Windows Services.
• Sign in to the Ecrion Website and ensure that the environments and project files exist and are functioning properly.

SQL server permissions for Backup/Restore

You should be aware that certain permission are needed in order to successfully perform SQL database backup and restore. In order to successfully perform this operations, the login used by Ecrion Server to connect to the database should have this permissions. You can find more information about the required permissions for backup here and for restore here.

Monitoring

System Status

The System Status page is a good way of monitoring and finding any major issue related to the EngageCX Services or EngageCX Storage.

To access the System Status page, you will have to sign in to the Sysadmin Website and select the System Status hyperlink, available in the Domain tile.

The System Status page will provide a view of all the EngageCX Services and real-time information regarding their status. Here you can inspect and ensure what services are functioning properly and which are not. EngageCX Platform performs automated checks on every service component to identify issues and return the results under the Health column. If the service is available and reachable, it will be marked by a green check icon, and in the Additional Information column you will be able to view the last start time of the service. If the service is not reachable or there is an issue related to it, you can view a red exclamation mark, and the error encountered in the Additional Information column.

At the bottom of the System Status page, you can inspect Storage Statistics about the utilization metrics, such as versions, warnings, disk size, and activity. These statistics will get you a picture of the overall EngageCX storage.

Background Services

Within Sysadmin Website, you can monitor background services, which are services created and maintained internally by EngageCX. Achieving visibility on background system tasks or services that use CPU, RAM or Database resources outside of document creation will improve production environment monitoring, troubleshooting or hot fixing (for example, some services can be disabled or configured to run at a reduced frequency).

To access the monitor page, sign in to the Sysadmin Website and select the Background Services monitor hyperlink, available in the Domain tile.

The Background Services Monitor page provides a summary view of the progress and completion of the EngageCX Background Services. Additional information is shown, such as the environment in which this service is running, their last start and execution time, or the current status, which can be Finished OK, Running or Finished with errors. You can also extend the monitoring period by selecting the filter button, at the top-left corner.

Enable/Disable Background Services

EngageCX Platform allows you to configure the running frequency of the background services and also enable or disable some of the services on an environment.

To enable/disable environment services:

1. Sign in to the Sysadmin Website and select the Environments tile.
2. From the environments list, select the environment on which you want to configure background services.
3. Next, navigate to the Services tab. Here, you can check on or off the Enabled button, next to the service name to enable or disable it on the current environment. Note that you cannot disable the Health Check service on any environment. Additionally, enter the time in seconds within the Frequency box to determine how often the selected service will run.

Offline Storage Diagnostics

When invalid index from storage occurs, the Offline Storage Diagnostics tool should be used in order to obtain a diagnosis report of the storage status. Being an offline tool, a successful execution requires the EngageCX Service (EOS4Svc) to be disabled.

The tool can be found in
<%Installation_Folder%>\Windows Service\EOSUtility\OfflineStorageDiagnostics\Tools.OfflineStorageDiagnostics.exe.

The Offline Storage Diagnostics tool uses the following general syntax:

Tools.OfflineStorageDiagnostics.exe
        [-u <sysadmin username>]
        [-p <sysadmin password>]
        [-repair <storage files will be repaired>]
        [-numberOfThreads <by default, 1>]
        [-dontCheckEncryption <the validity of encryption will not be checked>]
        [-dataFiles <data files to be repaired]
        [-nobackup <erase data files with invalid records>]
        [-configFile <config file path>]        

Quick Reference

The table below provides a quick reference to the various parameters and options available.

Parameter	Occurrence	Description
-u	Required	Specifies the system administrator username.
-p	Required	Specifies the system administrator password.
-repair	Optional	Specify the storage files to be repaired if invalid.
-numberOfThreads	Optional	Sets the number of threads. By default, the value is 1.
-dontCheckEncryption	Optional	Specify the validity of encryption to not be checked.
-dataFiles	Optional	Specify the data files to be repaired.
-nobackup	Optional	Specify all the data files with invalid records to not be backed up.
-configFile	Optional	Specifies the path to the configuration file.

Storage Parameters

Offline Storage Username and Password

Each time when running a storage command in CLI, you will have to specify the username and the password of the EngageCX Domain, as follows:

Tools.OfflineStorageDiagnostics.exe -u <username> -p <password> 

Offline Repair Storage

The tool is about the diagnosis of the storage, but it is capable also of repairing the damaged files by using teh -repair command, as follows:

Tools.OfflineStorageDiagnostics.exe -u <username> -p <password> -repair

Number of Threads

The Offline Storage tool allows you to increase the number of threads in order to speed up the analyzing process of the storage status.

To use the -numberOfThreads parameter, use a syntax as follows:

Tools.OfflineStorageDiagnostics.exe
 -u <username> -p <password> -numberOfThreads <*number of threads*> 

Do Not Check Encryption

For a better accuracy of the results, this parameter should not be specified.

To use the -dontCheckEncryption parameter, use a syntax as follows:

Tools.OfflineStorageDiagnostics.exe
 -u <username> -p <password> -dontCheckEncryption 

Data Files

For non-encrypted data files, use the number for files separated by comma, , and for encrypted data files use the number for files prefixed with 'e' separated by comma also, ,: '1,2,3,e1,e2,e3'.

To use the -dataFiles parameter, use a syntax as follows:

Tools.OfflineStorageDiagnostics.exe
 -u <username> -p <password> -dataFiles <1,2,e1,e2,..>

No Back Up

If this parameter is used, after the repairing process, all the damaged data files will be erased from the storage.

To use the -nobackup parameter, use a syntax as follows:

Tools.OfflineStorageDiagnostics.exe
 -u <username> -p <password> -nobackup 

Config File

Offline Storage Diagnostics tool allows you to specify the EngageCX configuration file to be used. By default, on a single-deployment installation, Offline Storage Diagnostics tool will read the configuration settings from the default configuration file location, which is %Application_Data%\EngageCX and it is not necessary to use this parameter.

In cases when you want to perform offline storage repairing commands from a remote server, Storage Diagnostics tool will require reading its settings from a configuration file in order to run.

To perform remotely storage diagnostics commands, you must point the tool to the configuration file via the -configFile parameter (the file provided will tell the tool which storage folder to use). To use the -configFile parameter, use a syntax as follows:

Tools.OfflineStorageDiagnostics.exe
 -u <username> -p <password> -configFile %Application_Data%\EngageCX\EOS4.config 

Troubleshooting

Master Logs

Master Logs are the main logs of the EngageCX System. All EngageCX Components except native engines (analytics engine, data engine, publishing engine) log there.

Configuring Master Log

To configure master logs, you will have to navigate to the %Application_Data%/EngageCX folder and open the EOS4Svc.config file. Within the EngageCX configuration file, you can set up log level or log location.

Log Levels

Log Levels allow system administrators to decide what activities should display in the log file.

There are 4 logging levels you can enable:

• None: No logging will occur.
• Normal: Errors, warnings and information messages will be logged.This is the default value.
• All: Errors, warnings, information messages and various traces will be logged.
• Debug: Everything will be logged, including diagnostic information for troubleshooting.

To configure the Log Level you will have to use the LogLevel parameter. For example, to set the Log Level to Normal, you need to add the following line in the configuration file: LogLevel=Normal

Master Log Location

The default location for the EngageCX master logs is %Application_Data%/EngageCX/Log. To specify a new log folder, you will have to use the MasterLogFolder parameter, as follows: MasterLogFolder={Enter_Log_Path}

UI Configurations

Some Master Log's option can be also configured from the User Interface, such as log level.

Log Level

To enable/disable logging:

1. Sign in to the Sysadmin Website and access the Domain tile.
2. Select the Log option from the Settings group.
3. Select the required log level from the drop-down list.

Include error details in REST response

If you are using the public REST API, it may be necessary to check the Include error details in REST response. By checking this, more explicit information will be returned when an exception is thrown.

Log Maintenance

To create policies on deleting older logs, you will have to configure log maintenance from EngageCX Domain. Enabling the maintenance log, allows you to automatically delete master logs, helping you to preserve the disk space.

To configure Log Maintenance:

1. Sign in to the Sysadmin Website and access the Domain tile.
2. Select the Log option from the Settings group.
3. In the Log page, click the Configure Log Maintenance button.
4. Next, check Enabled in the Configure Log Maintenance. Then, enter the time whereupon you want to delete the old logs under Maximum log age in day's box and click Save.

EngageCX Platform will automatically delete logs older than the period you have set. If you want to delete the logs now, you can select the Run Delete Now button to start the process manually. If you go back to the Domain page, you will notice that the Maintenance Status has been updated in the Summary group.

Engine Logs

In EngageCX Platform, native EngageCX Engine components will generate separate logs. By default, these are stored on a disk drive, at the default location %Application_Data%\EngageCX\Log.

Logging can be enabled/disabled from the Management Console tool, for the following EngageCX Components: Publishing Engine, Data Engine and/or Analytics Engine.

To enable/disable logging:

1. Open the Management Console tool from Windows Start. Or go to the EngageCX Installation Folder, navigate to Engines\Bin and open ManagementConsole.exe.
2. Next, in the left-hand tree-view, go to the ServerManager\Configuration and select the component on each you want to enable/disable logging.
3. Expand Engine Settings, then access the Logging option.
4. Within Logging window, double-click on the Log Level option and select the log level you want to configure.

Dump stack trace on error

The stack trace is logged whenever an exception is thrown. This should be set to false, and must be turned on for troubleshooting, only when instructed by EngageCX Technical Support.

Log Folder

By default, all EngageCX log files are located in %APPLICATION_DATA/EngageCX/Log. To change the default location, you will have to follow the steps below.

For Publishing Engine

1. Open the Management Console and navigate to the EngageCX Publishing Engine tool.
2. Next, navigate to Engine Settings\Logging and double click on the Log Folder parameter.
3. Enter the path to disk drive location where you want to store the log files.
4. Make sure that the Restart the service to apply changes is checked so the Publishing service to be restarted to apply the changes.
5. Once you're ready, select Ok. To view the log files, double-click on the Log Files option.

For Data Engine

1. Open the Management Console and navigate to the EngageCX Data Engine tool.
2. Next, navigate to the Engine Settings\Logging and double click on the Log Folder parameter.
3. Enter the path to disk drive location where you want to store the log files.
4. Make sure that the Restart the service to apply changes is checked so the Publishing service to be restarted to apply the changes.
5. Once you're ready, select Ok. To view the log files, double-click on the Log Files option.

For Analytics Engine

1. Open the Management Console and navigate to the EngageCX Analytics Engine tool.
2. Next, navigate to the Engine Settings\Logging and double click on the Log Folder parameter.
3. Enter the path to disk drive location where you want to store the log files.
4. Make sure that the Restart the service to apply changes is checked so the Publishing service to be restarted to apply the changes.
5. Once you're ready, select Ok. To view the log files, double-click on the Log Files option.

Runtime Logs

Execution Logs

These logs are used to track brief information for everything that runs in EngageCX Platform. By accessing Execution Logs, you will be able to inspect both, jobs and some API calls like Direct Render. Please visit the Execution Log section from EngageCX User Guide to learn more information.

Synchronization Logs

These logs are used to track synchronization between Amazon S3 and EngageCX. Please visit the Synchronization Logs section from EngageCX User Guide to learn more information.

Backend Services Logs

Other EngageCX services like Analytics, Audit, Customer, Discussions, Scheduler, Triggers also provides logging. Usually the logging of this services is stored in the EngageCX database and are visible in each particular service module.

Event Viewer

EngageCX Platform allows users to enable event logs on an environment, permitting users to duplicate the jobs logs in the Windows Event Viewer tool. In this section, you can learn how to enable logging notifications on an environment.

Enabling Event Logs in Sysadmin Website

1. Sign in to the Sysadmin Website and access the Environments tile.
2. Select the environment on which you want to enable the event logging and navigate to the Logging Notifications tab.
3. Start by checking in the Logging Notification Enabled option, then fill in the form with the needed content:
   • Destination: select the destination of the event logging (the logging application) Currently, you can select Windows Events.
   • Event Source Id: set up a unique identifiable event ID.
   • Severities: select the appropriate security levels that will be logged.
   • Message: create a message log. You can use the placeholders, from the right side, to create the log message.

Inspecting Event Logs

1. Sign in to the Enterprise Website using the environment credentials on which you enabled logging notifications.
2. Navigate to the Communications module and run the project of which job you want to inspect.
3. When the communication has finished, you will be able to view the logs details into the Log page.
4. Next, open the Windows Event Viewer tool. In the left-hand tree view, navigate to Windows Logs\Application.
5. In the Application list, search for the Event ID you have set up. Once selected, notice that the logs displayed in the communication log page will be also visible here in the upper part of the window.

Common Errors

This section lists troubleshooting tips for common encountered problems.

400 Bad Request

Symptoms

When accessing an EngageCX Platform Website, you receive a 400 Bad Request error. This can manifest in a number of ways, depending on how EngageCX Software was installed:

• The website can only be accessed from the server itself using the localhost URL, but cannot be accessed from the outside using the hostname URL.
• The website can be accessed from the outside using the hostname URL, but not from the server using the localhost URL. The website can, however, be accessed from the server using the hostname URL.

Solution

This is because of the default bindings in IIS. These will match the hostname URL(s) configured during installation. By default, these are localhost, but they should actually be set to use the hostname of the server as seen from the outside. This is important because the hostname URL will be used in emails sent to users and customers. We also recommend accessing EngageCX Platform using the hostname URL, even if that access is being performed from the server itself.

To change the hostname for either of the websites, just re-run the installer and set the correct hostname for each of the websites: Enterprise Website, System Administration, Customer Portal.

You can also set up access to each website from any machine, regardless of the hostname, by setting the appropriate bindings in IIS. However, the recommendation is that the IIS bindings always match the hostname set during installation, for consistency.

500 Internal Server Error(500.19)

Symptoms

After installation, you receive a 500 Internal Server Error when trying to access EngageCX Website pages from a remote computer. On the server, the detailed error is 500.19 - Internal Server Error. The requested page cannot be accessed because the related configuration data for the page is invalid, like in the screenshot below:

Solution

Install the URL Rewrite module for IIS 7 or later: https://www.iis.net/downloads/microsoft/url-rewrite. You can also read more details on this in the Pre-Install Requirements chapter of this guide.

Missing Modules on Home Page

Symptoms

After creating a new environment, most of the modules on the home page are missing.

Solution

Enable this functionality in the System Administration website by clicking on the corresponding environment. New environments are automatically created with a minimal set of modules enabled. The sysadmin must then enable the functionality they need from the Edit Environment dialog:

License Not Found

Symptoms

License Not Found error when accessing one of the EngageCX Websites, or missing functionality.

Solution

Common license errors are:

• Missing suitable license for specific product or feature
• Suitable license found but doesn’t support the number of cores

Make sure you have the appropriate licenses installed and activated on the machine. You need a total of 8 distinct licenses for a fully functional setup, one for each of the components. Some components are optional, e.g. the Customer Portal website or the Analytics Engine.

If you are not sure whether you have the correct license(s) installed, please reach out to engagecxsupport@mhcautomation.com.