Kentico 8.2 1. Configuring Kentico ...... 5 1.1 Managing sites ...... 6 1.1.1 Installing new sites ...... 7 1.1.1.1 Creating new sites using the wizard ...... 7 1.1.1.2 Creating new sites from templates ...... 8 1.1.1.3 Creating web templates ...... 10 1.1.2 Setting domain names for sites ...... 11 1.1.3 Managing site licenses ...... 12 1.1.4 Setting up multiple websites ...... 12 1.1.4.1 Running multiple sites on a single domain ...... 16 1.1.4.2 Configuring nested websites ...... 17 1.1.5 Switching sites to off-line mode ...... 18 1.1.6 Configuring settings for sites ...... 19 1.1.6.1 Settings - Content ...... 21 1.1.6.1.1 Settings - Content management ...... 22 1.1.6.1.2 Settings - Media ...... 24 1.1.6.1.3 Settings - Blogs ...... 24 1.1.6.1.4 Settings - Translation services ...... 25 1.1.6.2 Settings - URLs and SEO ...... 27 1.1.6.3 Settings - Security & Membership ...... 30 1.1.6.3.1 Settings - Passwords ...... 33 1.1.6.3.2 Settings - Protection ...... 34 1.1.6.3.3 Settings - Authentication ...... 35 1.1.6.4 Settings - System ...... 37 1.1.6.4.1 Settings - Performance ...... 39 1.1.6.4.2 Settings - Emails ...... 42 1.1.6.4.3 Settings - Files ...... 43 1.1.6.4.4 Settings - Health monitoring ...... 45 1.1.6.4.5 Settings - Output filter ...... 45 1.1.6.4.6 Settings - Search ...... 46 1.1.6.4.7 Settings - Debug ...... 46 1.1.6.5 Settings - On-line marketing ...... 52 1.1.6.5.1 Settings - Contact management ...... 52 1.1.6.5.2 Settings - Email marketing ...... 57 1.1.6.5.3 Settings - Web analytics ...... 58 1.1.6.6 Settings - E-commerce ...... 60 1.1.6.6.1 Settings - Global objects ...... 65 1.1.6.6.2 Settings - Authorize.NET ...... 65 1.1.6.6.3 Settings - PayPal ...... 65 1.1.6.7 Settings - Community ...... 66 1.1.6.7.1 Settings - Avatars ...... 67 1.1.6.7.2 Settings - Chat ...... 68 1.1.6.7.3 Settings - Forums ...... 71 1.1.6.7.4 Settings - Friends ...... 71 1.1.6.7.5 Settings - Groups ...... 72 1.1.6.7.6 Settings - Message boards ...... 73 1.1.6.7.7 Settings - Messaging ...... 73 1.1.6.8 Settings - Social media ...... 73 1.1.6.8.1 Settings - Facebook ...... 73 1.1.6.8.2 Settings - Google+ ...... 74 1.1.6.8.3 Settings - LinkedIn ...... 74 1.1.6.9 Settings - Social marketing ...... 75 1.1.6.9.1 Settings - URL shorteners ...... 75 1.1.6.10 Settings - Intranet & Collaboration ...... 75 1.1.6.10.1 Settings - Events ...... 75 1.1.6.10.2 Settings - Projects ...... 75 1.1.6.11 Settings - Versioning & Synchronization ...... 76 1.1.6.11.1 Settings - Staging ...... 76 1.1.6.11.2 Settings - Object versioning ...... 76 1.1.6.11.3 Settings - Web farm ...... 78 1.1.6.12 Settings - Integration ...... 78 1.1.6.12.1 Settings - Integration bus ...... 78 1.1.6.12.2 Settings - Microsoft SharePoint ...... 79 1.1.6.12.3 Settings - REST ...... 79 1.1.6.12.4 Settings - WebDAV ...... 80 1.1.6.12.5 Settings - Data.com ...... 80 1.1.6.12.6 Settings - Salesforce.com ...... 80 1.1.6.12.7 Settings - 51Degrees.mobi ...... 82 1.1.6.12.8 Settings - Strands Recommender ...... 82 1.2 Managing files ...... 83 1.2.1 Storing files ...... 84 1.2.2 Importing files ...... 85 1.2.3 Uploading files ...... 88 1.2.4 Resizing images on upload ...... 89 1.2.5 Adding watermarks to images ...... 90 1.2.6 Administering files globally ...... 90 1.2.7 Editing file metadata ...... 92 1.3 Configuring page URLs ...... 93 1.3.1 URL format and configuration ...... 95 1.3.2 Setting page aliases ...... 97 1.3.3 Wildcard URLs ...... 99 1.3.4 Extensionless and custom URLs ...... 100 1.3.5 Linking pages and files ...... 102 1.3.6 Custom handling of URL path values ...... 103 1.4 Search engine optimization ...... 106 1.4.1 Configuring websites for SEO ...... 106 1.4.2 Google Sitemaps ...... 110 1.4.3 Managing robots.txt ...... 113 1.5 Optimizing website performance ...... 115 1.5.1 Loading data efficiently ...... 117 1.5.2 Configuring caching ...... 119 1.5.2.1 Caching page output ...... 121 1.5.2.1.1 Using output cache substitutions ...... 124 1.5.2.2 Caching files and resources ...... 126 1.5.2.3 Caching the data of page components ...... 127 1.5.2.4 Setting cache dependencies ...... 128 1.5.2.5 Debugging cache ...... 130 1.5.2.6 Reference - Cache settings ...... 132 1.5.3 Using code minification and compression ...... 136 1.5.4 Setting up web farms ...... 138 1.5.4.1 Web farm synchronization mechanisms ...... 139 1.5.4.2 Configuring web farm servers ...... 140 1.5.4.3 Troubleshooting web farms ...... 142 1.5.4.4 Debugging web farms ...... 143 1.6 Setting up search on your website ...... 144 1.6.1 Enabling search indexing ...... 145 1.6.2 Creating search indexes ...... 146 1.6.2.1 Defining page indexes ...... 149 1.6.2.2 Defining forum indexes ...... 154 1.6.2.3 Defining custom table indexes ...... 155 1.6.2.4 Defining on-line form indexes ...... 156 1.6.2.5 Defining user indexes ...... 157 1.6.2.6 Defining general indexes ...... 159 1.6.3 Monitoring search indexing tasks ...... 160 1.6.4 Adding search functionality to pages ...... 161 1.6.4.1 Setting up predictive search ...... 163 1.6.5 Configuring search assistance features ...... 167 1.6.6 Searching attachment files ...... 170 1.6.6.1 Configuring SQL search for attachment files ...... 172 1.6.7 Using search filters ...... 175 1.6.8 Smart search syntax ...... 178 1.6.9 Displaying search results using transformations ...... 179 1.6.10 Searching according to page permissions ...... 180 1.6.11 SQL search ...... 180 1.7 Scheduling tasks ...... 181 1.7.1 Configuring scheduled task execution ...... 181 1.7.2 Installing the Scheduler Windows service ...... 183 1.7.3 Reference - scheduled task properties ...... 185 1.8 Configuring SMTP servers ...... 186 1.8.1 Reference - SMTP server properties ...... 189 1.9 Managing email templates ...... 190 1.10 Working with widget dashboards ...... 191 1.10.1 Managing widget dashboard content ...... 192 1.10.2 Adding widget dashboards to the interface ...... 194 1.11 Using output filters ...... 199 1.12 Configuring time zones ...... 202 1.12.1 Managing time zones ...... 204 1.13 Working with object versioning ...... 205 1.13.1 Using object versioning ...... 207 1.13.2 Objects recycle bin ...... 208 1.14 Creating alternative forms ...... 209 1.14.1 Code names of automatically used alternative forms ...... 210 1.14.2 Displaying filters using alternative forms ...... 210 1.15 Health monitoring ...... 212 1.15.1 Registering performance counters ...... 213 1.15.2 Installing the Health monitoring Windows service ...... 215 1.15.3 Enabling health monitoring ...... 216 1.15.4 Monitoring using the Performance monitor ...... 217 1.15.5 Reference - default performance counters ...... 218 1.16 Adding cookie law consent to web pages ...... 220 1.16.1 Cookie levels ...... 220 1.16.2 Reference - Kentico cookies ...... 221 1.17 Banning IP addresses ...... 224 1.18 Configuring countries ...... 226 1.19 Working with system reports ...... 226 1.19.1 Creating reports ...... 226 1.19.2 Creating report categories ...... 240 1.19.3 Defining report parameters ...... 240 1.19.4 Storing data from reports ...... 242 1.19.5 Displaying reports on websites ...... 242 1.19.6 Subscribing to reports ...... 242 1.19.7 Example - creating a simple report ...... 246 1.19.8 Reporting security ...... 250 1.20 Configuring Windows Communication Foundation ...... 252 1.21 Configuring the administration interface URL ...... 254 1.22 Configuring the code editor ...... 254 Configuring Kentico Configure the Configure the Optimize your environment for system website content editing Sites Performance optimization Workflows Whether you run one or multiple sites, it is Learn which aspects Workflows define the useful to know how to affect the performance life cycles of pages. manage sites in the of your websites and Learn how to create system. Learn how to in what can you do to them and apply them to stall new sites, add site improve the pages. licenses, set domain performance. Setting up names, and more. web farms can also provide load balancing Page versioning for your website.
Configure versioning of Files pages with or without a Explore the ways of workflow. Set up lockin Search engine storing files in Kentico. g of pages for optimization (SEO) Choose whether to stor collaborative editing. e files in the database Help your website be or the file system, uploa visible in search d multiple files to your engines like Google. Media libraries websites, set up image resizing on upload. Configure custom storage for media Output filters libraries, custom file The output filters types or maximum file Page URLs enable the system to upload size. Learn how to set the automatically adjust the URLs for web pages in HTML code of pages Kentico. Adjust your before sending the WYSIWYG editor URLs so that they do code to browsers. not have extensions. Configure and personalize the WYSIWYG editor for Health monitoring content editors. Website search Set up performance The system provides monitoring for your built-in, index-based application. This can On-site editing search functionality. En help you find able search indexing, cr bottlenecks in the Allow content editors to eate search indexes an system. adjust page content on d add Smart search websites directly while web parts to your site. viewing the website in a live mode.
SMTP servers
Content notifications Connect the system to SMTP servers to allow Enable content editors Kentico to send out to receive notification emails. messages when pages are created, updated or deleted. Email templates
Create and manage WebDAV templates for emails, which are automatically Enable the content sent by the system. editors to collaboratively edit files stored on remote servers using the client Scheduled tasks applications (e.g., using Learn how to configure Microsoft Word) the system to installed on their local periodically perform computers. tasks. Object versioning
Configure the system to keep track of changes made to objects and learn how to work with the object recycle bin.
Alternative forms
Create alternative versions of various types of editing and input forms in the system.
Managing sites You can run any number of sites within a single instance of Kentico. Each site runs on its own domain name and stores content in a separate content tree. The websites share the same web project (code base) and database.
Creating sites
See Installing new sites.
Starting and stopping sties
You can stop or run individual sites in the Sites application. Use the following actions:
Start site Stop site
When you stop a site:
Visitors cannot access the live site Users cannot edit the site in the site-specific sections of the administration interface
To stop a live website with administration enabled, keep the site running and switch it to off-line mode.
Switching between sites on a single domain
You cannot start sites that use the same domain name (or domain alias) as another site that is already running. If you need to test multiple websites on a single domain, such as http://localhost, set this domain for all sites and switch between them using the Start site and Stop site actions.
You can run multiple sites at the same time using alternative host names that point to the same domain (for example http://localhost and http://127.0.0.1).
See also: Setting up multiple websites
Assigning objects to sites
Many objects in Kentico need to be assigned to specific sites in order to be available on the given sites. Site bindings allow you to limit where objects can be used when running multiple websites in the system. You can manage all types of site bindings for individual websites in a single location:
1. Open the Sites application. 2. Edit ( ) the site. 3. Open the Assigned objects tab.
You can assign the following objects to the site:
Classes SMTP servers Smart search indexes Modules Users CSS stylesheets Page templates Web part containers Page relationship types Polls
For example, after creating a new site, you can assign users from other sites in the system:
1. Select the Users sub-tab. 2. Click Add users. 3. Select the users that you want to add to the site. 4. Click Select.
Deleting sites
You can delete sites from the system in the Sites application.
1. Click Delete ( ) next to the site that you want to delete. The Site deletion confirmation dialog opens.
2. Enable or disable the following options:
Delete page attachment physical files - if checked, the deletion process removes files attached to the site's pages from the file system (stored in the
3. Click Yes. The system displays a log showing the progress of the deletion.
4. When the process finishes, click OK.
The list in the Sites application no longer includes the deleted site.
Installing new sites Use the New site wizard to add new websites to the system. You can access the wizard in the Sites application.
Step 1 - Choose default website
In the first step of the wizard, choose if you want to create the new site using a wizard or import a web template.
Create a new site using a wizard - creates a new blank site. Use web template - creates a new site based on a web template.
Click Next. Follow the links above to learn about the rest of the site creation process.
Creating new sites using the wizard This page describes how to add a new website to the system using the wizard. Start the New site wizard in the Sites application, and select Create a new site using a wizard in the first step.
Step 2 - Enter new site settings
Enter the following basic site properties:
Site display name - name of the new site displayed in the administration interface. Site code name - name of the new site used in website code. Domain name - domain name under which the new site will run. The domain must be unique for each website running in the system. Site culture - the default culture of the site.
Click Next to continue.
Step 3 - Object selection
In this step, select which objects will be imported along with your new site. Choose the categories displayed in the tree on the left side of the wizard.
You can leave the default settings and click Next to continue.
Step 4 - Import progress
A log appears, showing the progress of the site creation.
When the process finishes, click Next.
Step 5 - Select master page
Here you can select the master page template. The master page defines the basic visual structure of the website. You can switch to a different master page later at any time.
Select one of the layouts and click Next.
Step 6 - The website has been created successfully
You have successfully created the new website. Click Finish to return to the Sites application.
You can now begin developing the website or managing the website content.
Creating new sites from templates This page describes how to create a new website based on a predefined web template. Start the New site wizard in the Sites application and select Use web template in the first step.
Custom templates You can create your own web templates from existing sites.
Step 2 - Choose web template
You can choose from a number of web templates:
Dancing Goat showcases some of the Kentico's Integrated Marketing Solution from the point of a coffee selling business. Corporate site is a typical web presentation of a company. Used in most documentation examples. E-commerce site is an e-shop showing the possibilities of the Kentico E-commerce Solution. Community site is a sample community website demonstrating social networking capabilities of Kentico. Blank site is a blank template used for creating websites from scratch. and others.
Some of the templates are available in two versions, one using the portal engine and the other using ASPX page templates. Choose one of the listed web templates and click Next.
Step 3 - Enter new site settings
Enter the following basic site properties:
Site display name - name of the new site displayed in the administration interface. Site code name - unique identifier of the new site. Domain name - domain name under which the new site will run. The domain must be unique for each website running in the system.
Click Next to continue.
Step 4 - Objects selection
In this step, select which objects from the web template you want to import. Choose the categories displayed in the tree on the left side of the wizard.
The following options are available in the root of the tree:
Global object selection
Load default selection Select all objects - selects all objects included in the web template. Select only new objects - selects only those objects that do not already exist in the system (clears selection for existing objects). Deselect all objects - clears the selection for all objects in the web template.
Import settings
Assign all objects to the imported site (recommended) - if enabled, all imported site related objects will be assigned to the imported site. Run the site after import - if enabled, the system attempts to start the new site immediately after the import is finished. Delete incomplete site when import fails - if enabled, the system deletes the site if any part of the import process fails. Do not import objects where parent object is missing - if enabled, the import process skips any child objects whose parent objects is not present in the target system. Import tasks (recommended) - if enabled, any synchronization tasks included in the web template will be imported. Log staging synchronization tasks - if enabled, the system logs staging tasks reflecting all changes made by the creation of the new site. Check this option to synchronize the imported data to other servers connected through Content staging. Log integration tasks - if enabled, the system logs outgoing integration tasks for all changes made by the creation of the new site. Check this option if you want to transfer the imported data to a system connected via the System integration bus. Import files (recommended) Import code files - indicates if the new site includes code files that require compilation, i.e. files with the following extensions: cs, vb, aspx, ascx. You cannot import code files if your application is precompiled. Import custom assembly files - if enabled, the new site includes custom assembly files bound to notification gateways, translation services, payment options, integration connectors, scheduled tasks, advanced workflow actions, marketing automation actions and smart search analyzers from the web template. Custom assemblies are those whose names do not begin with the CMS. prefix. You cannot import assembly files if your application is precompiled. Import global folders - if enabled, the import process includes global files originally exported from the following folders: ~/App_Code/Global/ ~/CMSGlobalFiles/ ~/CMSScripts/Custom/ ~/App_Code/Controllers/ ~/Controllers/Global/ ~/Views/Global/ Import site folders - if enabled, the import process includes site-related files originally exported from the following folders: ~/App_Code/
You can leave the default settings and click Next to continue.
Step 5 - Import progress
A log appears, showing the progress of the site creation.
When the process finishes, click Next.
Step 6 - The website has been created successfully
You have successfully created the new website. Click Finish to return to the Sites application.
You can now begin developing the website or managing the website content.
Creating web templates The system allows you to save sites created in Kentico as web templates. You can then use the web templates as starting points for developing new sites. To save a site as a web template:
1. Export your site.
Important: You need to carefully consider which global objects you include in the site export package (such as modules, web parts, search indexes, etc.). When you create new sites based on the template, the system overwrites existing objects using the ones from the web template. We recommend that you only keep objects that are directly related to the site's design and content.
2. Open the ~\App_Data\Templates folder inside your web project directory. This folder stores all default templates, such as the Corporate or Community site.
3. Create a new folder for your web template. 4. Add a sub-folder named Data. 5. Extract the content of your site's export package into the Data folder. 6. Log into the Kentico administration interface and open the Web templates application. 7. Click New web template. 8. Enter the following details:
Display name - the name of the web template displayed in the new site wizard. Code name - serves as a unique identifier of the web template. Web template folder - specifies the path to the folder containing the template's export package: ~\App_Data\Templates\
Description - text describing the content and purpose of the web template. Thumbnail - allows you to upload a preview image. The system displays this image next to the template in the Choose web template dialog of the new site wizard. License editions / packages - select the editions of Kentico where the web template is supported. The system only offers the template if the license requirements are fulfilled on the given instance of Kentico.
9. Click Save.
Your new web template is now included in the list. You can create new sites based on the template.
Setting domain names for sites The Domain name is one of the basic properties that you assign when creating new sites. The system generates the URLs of the website's pages and other components using the specified domain name. Every website running in the system must have a unique domain name.
To set the main domain name for an existing website:
1. Open the Sites application. 2. Edit ( ) the site. 3. Type the domain into the Site domain name property on the General tab. 4. Click Save.
Domain name format
Enter the domain name without the http:// protocol and www prefix. Include the port number if it is different than 80.
Correct:
mycompany.com partners.mycompany.com mycompany.com:8080
Incorrect:
http://mycompany.com www.mycompany.com
Adding domain aliases
Domain aliases are alternative domain names that lead to the same website. You can add any number of domain aliases for each site. For example, if your website uses mycompany.com as its main domain and you also wish to assign the my-company.co.uk domain to the same website, you need to create a domain alias. Aliases can be particularly useful when building multilingual websites.
To create a domain alias for your website:
Note: You need to have a valid license for every domain alias. Domain alias licenses are free of charge if you already own a license for the main domain.
1. Open the Sites application. 2. Edit ( ) your site. 3. Select the Domain aliases tab. 4. Click New domain alias. 5. Type the alternative domain name into the Domain alias property. Use the same format as for the site's main domain name, without the protocol or www prefix.
6. (Optional) Set the Default alias path. Specifies the default page that the system displays when users access the site's root URL through the domain alias. Overrides the Settings -> Content -> Default alias path setting.
7. Click Save.
The site is now available under the alias's domain name.
Redirecting aliases to the main domain
You can configure domain aliases to automatically redirect users to another URL. When a visitor accesses the website through the domain alias, the system sends them to the specified URL instead.
If the only purpose of your domain aliases is to make the site available under multiple domain names, it is recommended to redirect the aliases to the website's main domain. This is a common Search engine optimization practice that prevents duplicate web content (i.e. having multiple URLs leading to the same content).
To set up redirection for your domain aliases:
1. Open the Sites application.
2. 2. Edit ( ) your site. 3. Select the Domain aliases tab. 4. Edit your aliases. 5. Type the target URL into the Redirect URL property.
Use macro expressions to dynamically redirect users to the correct page, for example: {%protocol%}://domain.com{%re lativepath%}
{% relativepath %} - resolves into the current relative URL path when the redirection takes place {% protocol %} - resolves into the current URL scheme name (protocol) when the redirection takes place
6. Click Save.
The system now automatically redirects all users to the site's main domain. For example, if your site's main domain is domain.com and you have domain.co.uk as a domain alias, users who access https://domain.co.uk/example.aspx are redirected to https://domain.com/example.a spx.
Managing site licenses Kentico requires a license key for every domain that your sites use. You cannot view or edit sites running on domains that do not have a matching license in the system.
Note: If you do not have a valid license for the current domain, only global applications are available in the administration interface.
To manage your system's licenses, open the Licenses application.
When you obtain a license key (full or trial) for a domain:
1. Click New license. 2. Copy the full license key into the field. 3. Click Save.
The Licenses page displays a list of all licenses added to your system, including the domain names, expiration dates and license editions.
How licensing works
License keys support all protocol and www prefix combinations for the specified domain. Every valid license key also allows you to use the local server's hostname (localhost and 127.0.0.1).
For example, if you add a license key for the example.com domain, you can use all of the following domains:
http://example.com https://example.com http://www.example.com https://www.example.com http://localhost http://127.0.0.x (where x is between 1 and 255)
If you use domain aliases (different domain names that point to the same website), such as example1.com or example.net, you need to add extra license keys for these domains.You can generate the domain alias license keys on the Kentico client portal. Domain alias licenses are free of charge if you already own a license for the main domain.
Setting up multiple websites Kentico allows you to run any number of websites from a single installation. The websites share the same web project (code base) and database. All sites run under a single web site in IIS.
Using separate installations for each site
It is recommended to run separate instances of Kentico for every website in the following scenarios:
Your websites contain a very large number of pages and high performance is a critical requirement. Your customers have very different requirements and you need to customize shared parts of the system, such as the administration interface or the structure of shared database tables. Your customers are very sensitive to security and you do not want to risk that other clients will get access to other websites because of an administrator’s mistake.
The following sections demonstrate how to set up multiple websites on an example of two sites:
mysite.com mysite2.com
Creating multiple sites in Kentico
1. Open the sites application. 2. Create two websites. You can either import existing websites or create new websites using the New site wizard.
3. Edit ( ) each website and set the Site domain name values (without the www prefix and http:// protocol). 4. Make sure both sites are running. You can check the site status on the main site list.
5. Make sure you have valid license keys for both domains in the Licenses application. Configuring multiple sites on a local IIS server
1. Open your Internet Information Services (IIS) Manager console (Start -> Control Panel -> Administrative tools -> Internet Information Services (IIS) Manager). 2. In the tree, right-click Sites and select Add Web Site.
3. Enter the following details:
Site name: mysite.com Physical path: disk path to the location of your site's web project (where the application's web.config file is stored). Host name: www.mysite.com 3.
4. Click OK. The site appears under the Sites node.
5. Right-click the site and select Edit bindings.
6. Click Add. 7. Enter the domain name of your second website as the Host name and click OK. 8. Add two more bindings for both sites without the www prefix. 8.
Your new IIS web site is now configured to handle all incoming requests for domains mysite.com and mysite2.com. You may need to ask your network administrator to redirect the domain in the DNS records to your website. When you open http://www.mysite.com and http://www .mysite2.com (or your own domain names) in a browser, you should see two different websites.
Testing domains
If you do not own the domains, you can test the configuration by modifying the server's C:\WINDOWS\system32\drivers\etc\host s file.
For this example, add the following lines to the end of the file:
127.0.0.1 mysite.com 127.0.0.1 www.mysite.com 127.0.0.1 mysite2.com 127.0.0.1 www.mysite2.com
Note: These are client settings, so the website will only work when accessed from a browser on the server machine.
Multiple websites on a single domain
If you cannot use multiple domain names for your website, you can differentiate websites by subfolder (virtual directory). See Runni ng multiple sites on a single domain for more details.
Running multiple sites on a single domain This page describes how to run multiple websites in separate sub-folders on a single domain. In this scenario, you do not need to obtain new domains for each site.
Example - Installing two sites onto a single domain
1. Install a Kentico web project to the following folder: C:\inetpub\wwwroot\mykenticofolder. In the installer, choose Custom installation and Built-in web server in Visual Studio (does not create a virtual directory).
2. Open your Internet Information Services (IIS) Manager console (Start -> Control Panel -> Administrative tools -> Internet Information Services (IIS) Manager).
3. Create a new virtual directory named mykenticoweb. The name of the virtual directory must be different than the folder where you installed the web project. Set the Physical path to a non-website folder in the root of a local disk. Ideally, create an empty folder for this purpose, for example: c:\empty
4. Create two IIS applications under mykenticoweb named web1 and web2. Set the Physical path of both applications to the web site folder of the installed project (C:\inetpub\wwwroot\mykenticofol der\CMS in this example). Set the application pool according to the type that you specified in the installation of the Kentico web project.
5. Open your browser and type in either http://localhost/mykenticoweb/web1 or http://localhost/mykenticoweb/web2.
6. Log in to the Kentico administration interface and open the Sites application.
7. 6.
7. Install both sites. Set the Site domain name fields: Website 1: localhost/mykenticoweb/web1 Website 2: localhost/mykenticoweb/web2
Now when you go to http://localhost/mykenticoweb/web1, you will see website 1. If you go to http://localhost/mykenticoweb/web2, you will see website 2.
Synchronizing global data for the sites
To ensure the synchronization of settings and global objects between the two sites, you need to set up a Web farm environment.
1. Add the following keys to the
These keys enable web farms in general and disable synchronization of files, which is not needed since the applications already use the same physical folder. Notice that each application has a different web farm server name specified via a prefix in the name of the CMSWebFarmServerName key. This prefix must match the path that you set for the corresponding application in IIS, including the virtual directory.
2. Log in to the Kentico administration interface on one of the sites. 3. Open the Web farms application. 4. Create a web farm server for each application. 5. To prevent potential problems with conflicts during Smart search indexing, specify a different physical folder for each application's search index files through the following web.config keys:
Your websites should now work without any issues.
Configuring nested websites A nested website is a site that users can access through a URL sub-directory under the domain name of a different website. The following steps demonstrate how to create two Kentico sites that utilize nesting:
1. Install two Kentico web projects into separate folders. Choose folder names different than the virtual directory names you plan to use in the URL. This prevents collisions when setting up the IIS. For example: Inetpub/wwwroot/NestedWeb/Web1 Inetpub/wwwroot/NestedWeb/Web2
You now have two completely independent instances of Kentico, each with its own web project.
2. Open your Internet Information Services (IIS) Manager console (Start -> Control Panel -> Administrative tools -> Internet Information Services (IIS) Manager). 3. Create two applications under your web site:
[IIS web site]/KenticoCMS1 - set the Physical path to Web1 [IIS web site]/KenticoCMS1/KenticoCMS2 - set the Physical path to Web2 (the child website)
You now have two independent applications in IIS, one nested under the other. 3.
4. Edit the web.config of the nested application (Web2) and remove all module and handler definitions. This avoid duplicate module and handler definitions of the two applications.
If you have any additional custom keys in these configuration sections, ensure that they are not duplicated in the two web. config files, i.e. that they are only added in one of the two files.
// remove or comment out all keys in this section
// remove or comment out all keys in this section
The websites are now accessible via nested URLs. You can configure the websites independently without any issues.
Additional configuration for Staging
This section describes how to set up Content staging on nested websites.
Staging uses sections in the web.config that collide on nested websites. Config files are inherited within the IIS virtual directory structure (even when the projects are not nested on the file system), but you cannot have the same section of web.config twice in the config file.
If you configure staging from the KenticoCMS1 site to the KenticoCMS1/KenticoCMS2 site, the inner project may have issues with the configuration.
If you get the "The username token has already been added" error message, some of the configuration is duplicated. User name token authentication is defined in the policy file, which is referenced from the
You need to remove the whole
Staging between the nested sites should now work correctly.
Switching sites to off-line mode Kentico allows you to bring sites off-line. This can be useful if you need to make major modifications to your site and wish to hide it while the update is in progress. When in offline mode:
Visitors cannot access the live version of the website The site still remains running and editors and administrators can normally work through the administration interface.
To enable off-line mode for websites:
1. Open the Sites application. 2. Edit ( ) the site. 3. Open the Off-line mode tab. 4. Choose how to handle users who attempt to access the site while it is off-line:
Display following message - add the message content using the WYSIWYG editor. The system sets the HTTP response status code of the page to 503, so applications and crawlers who access the site should be able to correctly recognize the situation. Redirect visitor to following URL - enter the address of an alternate website or page to which users will automatically be redirected until the site is returned back on-line. 4.
5. Click Save. 6. Click Take the site off-line.
The site is now off-line. Visitors who access the site either see your off-line message or are redirected to the specified alternative page.
At any time, you can allow visitors to access the site again by clicking Bring the site on-line on the Off-line mode tab.
Configuring settings for sites You can configure settings for sites in the Settings application.
There are two basic types of settings:
Global - apply to all sites in the system, unless individual sites override the values. Site-specific - apply to the selected Site. The site settings load the global values unless you uncheck Inherit from global settings f or individual settings and enter different values.
Note: Some settings are only available as global settings.
Searching for settings
There is a very large number of settings in Kentico . To find a particular setting among all the categories:
1. In the Settings application, select the root of the settings tree (Settings). 2. Type the name of the setting or related words into the field at the top of the page. 3. Click Search. If you check Search in description, the search also finds settings that have the given text in their description (tooltip).
The page displays all settings that contain the search text in their name. You can edit the values of the settings directly. Resetting settings
To reset settings to their default values:
1. Select a category in the Settings application. 2. Choose (global) in the Site selector above the settings tree. 3. Click Reset these settings to default. 4. Click OK in the confirmation dialog. 5. Click Save.
All settings in the given category now have the default value defined in the Default value property of the corresponding keys.
Exporting the setting values
You can export the values of all settings in the selected category to a text file. Click Export these settings in the header of the setting page. Exporting settings can be useful, for example when consulting issues with Kentico support.
Loading the values of settings in code
The Kentico API allows you to check the values of settings in your code. You can load values of both the default and custom settings.
Use the following methods of the SettingsKeyInfoProvider class according to the data type of the required setting:
GetBoolValue GetStringValue GetIntValue GetDoubleValue
The methods accept a string parameter that identifies the setting in the following format:
Note: When loading global-only settings, only enter the code name of the required settings key in the parameter.
For example: using CMS.DataEngine; using CMS.SiteProvider;
...
string value = SettingsKeyInfoProvider.GetStringValue(SiteContext.CurrentSiteName + ".CMSDefaultAliasPath");
Getting setting values in macro expressions
Macro expressions allow you to:
Dynamically insert the values of settings into most fields in the Kentico administration interface Work with settings in macro conditions or other expressions with advanced logic
You can load values of both the default and custom settings.
Use the following expression to get setting values inside macros: Settings.
For example:
{% Settings.CMSStoreFilesInFileSystem %}
The macro returns the setting's value for the currently running site (or the global value for global-only settings). If you need to access the global value of a setting, you can use the following macro expression: GlobalObjects.SettingsKeys.
Settings - Content
Page not found
Page not found for non-published pages If checked, pages that are not published return a Page not found error (404) if they are viewed on the live site.
Page not found URL Specifies a custom page that will be displayed to users who encounter a Page not found error (404 HTTP status code). It can either be a physical aspx file in the web project or a dedicated page created in the site's content tree.
In both cases, you need to enter the URL of the page, for example:
~/SpecialPages/PageNotFound.aspx
This value could be used to specify the URL of a physical page file placed in the given location, or select a page with an alias path equal to /SpecialPages/PageNotFound.
The advantage of using a page for this purpose is that you can leverage all features of the portal engine. For instance, you can translate the page not found page on a multilingual website and the system will automatically display the appropriate culture version according to the currently selected language.
Log page not found exception If enabled, the system logs Page not found (404) http errors in the Event log application. You can recognize the errors by the "PAGENOTFOUND" event code.
Multilingual
Default content culture Used to select which culture should be the default language option of the website's content.
Combine with default culture Indicates if the default culture version of pages should be offered for pages that are not available in the currently selected language.
Combine files with default culture Indicates if the default culture version of files should be used for untranslated file pages.
Web site content
Default alias path Alias path of the website's default page. Metadata
Page key words prefix Specifies a prefix for all page keywords on the website.
Page description prefix Specifies a prefix for all page description on the website.
Page title format Specifies the page title format.
Example: {%prefix%} - {%pagetitle_orelse_name%}
Page title prefix Page title prefix used for all pages. Replaces the {% prefix %} macro in the page title format.
Control element Specifies the element that should be used instead of the standard element. Currently, the only options are span or div.
Related pages Multilingual websites Creating custom error handling pages
Settings - Content management On this page, you can edit the following settings related to content management and workflows:
General
New page order Specifies the default order used when inserting new pages. Possible values are:
First - new pages are added to the first position on the given level of the content tree. Last - pages are added to the end of the given content tree level. Alphabetical - pages are inserted to the appropriate alphabetical position based on their name.
Prompt to save changes on exit If enabled, users are notified when leaving a modified page in editing mode with unsaved changes.
Allow global categories Indicates if the use of global categories, i.e. categories shared across all websites in the system, should be enabled for the website selected in the Site drop-down list (or for all websites that inherit the setting if (global) is selected in the drop-down list).
Enable wireframing Allows users to create and edit wireframe schematics in the Pages application. Wireframes provide a way to easily plan out the structure, design and functionality of the website's pages directly in the content tree.
The system displays all existing wireframes even if this setting is disabled. However, users cannot make any modifications or create new wireframes.
On-site editing
Enable On-site editing Indicates whether the website's pages should be editable through a special interface directly on the live site. On-site editing allows authorized users to make changes to page content, manage pages and even configure the properties of web parts.
Enable On-site editing button When enabled along with on-site editing, the Edit page button is displayed in the corner of pages on the live site for users who are authorized as editors. Clicking the button opens the onsite editing interface.
If you do not wish to use this button, users can alternatively access on-site editing mode through links provided by the Edit page link or Admin actions web part, or by manually going to the following URL: http://
Mobile development Enable device profiles Enable this setting if you want to use device profiles on the website. Device profiles allow you to customize the layout and content of pages for specific devices. The system automatically assigns a device profile to each visitor according to the parameters of the device they use to view the page.
You can define device profiles in the Device profiles application.
Enable layout mapping If enabled, pages with shared page layouts automatically use replacement layouts according to the layout mappings set for individual device profiles.
To configure the layout mappings of a device profile, edit it in the D evice profiles application and open the Layout mapping tab.
Resize images according to device profile If enabled, the system automatically resizes images to match devic e profiles. This reduces the maximum side size of images to the larger of the dimensions set for the used device profile (Preview width or Preview height).
Note: The resizing only works for images loaded through one of the Kentico system pages (getattachment, getmetafile, getmedia, etc.). The feature cannot resize images that use web links or direct paths in their source.
You can disable the resizing for individual images by adding the re sizemode=1 query string parameter to the image source URL.
Content management UI
Check page permissions If enabled, only pages for which the current user has the Read per mission are displayed in the content tree (in the Pages application in the editing and listings modes and in various dialogs where the content tree is displayed).
In case that a user doesn't have the Read permissions for any page at all, a message is displayed instead of the content tree, saying that they are not authorized to modify any page. If a user has the Read permission for a child page but not for its parent, the child page is not displayed as well.
Max tree nodes The maximum number of pages that will be displayed under an unfolded page in the tree view. If the number of pages exceeds the maximum number, a link that takes you to the page list is displayed after the allowed number of records.
Display linked icon These settings indicate if special icons should be displayed in the content tree next to pages under the specified conditions. Display not translated icon Learn more about the icons in Configuring page status icons. Display redirected icon
Display published icon
Display version not published icon
Display not published icon
Display archived icon
Display checked out icon
Display wireframe icon
Workflow
Send workflow e-mails Indicates if the workflow e-mail notification should be sent.
Send workflow e-mails from E-mail address of the workflow e-mails sender. You can also use the Someone
Use automatic version numbering If you use workflow without content locking, automatic version numbering will be used by default.
Use check-in/check-out Indicates if content locking (check-in/check-out) should be used with page types that use versioning. Content locking allows content editors to lock the page for editing so that the other editors cannot modify the page at the same time. Version history length Specifies maximum number of versions in the page history. If the number of versions exceeds the specified maximum number, the older versions are destroyed.
Allow permanent preview links Indicates if page preview links remain usable even if page workflow cycle is restarted (when pages in Published/Archived workflow step are switched to the Edit step). If disabled, new preview links are generated in this situation and the original ones are no longer usable.
Settings - Media In this dialog, you can make settings related to the Media libraries module. The following settings are available:
General
Use permanent URLs If true, URLs of medial library files will be generated in permanent format (~/getmedia/
Max subfolders Maximal number of folders that can be displayed under an expanded folder node in the tree view.
Security
Media file allowed extensions Extensions of files which can be uploaded to media libraries. Divide the extensions by semicolons.
Check files permissions Indicates if the "See media library content" permission is checked when retrieving media files using permanent URLs.
Storage
Media libraries folder Folder where media library files are stored. You can use:
physical disk path - e.g. c:\myfiles\mysite virtual path - ~/UploadedFiles UNC path - \\server\folder
If no value is entered, the default location is: ~/
Use site-specific subfolders for custom media libraries folder This setting is applied only when a Custom media libraries folder is configured. If enabled, media library files will be stored in a sub-folder named as the site code name under the custom files folder, i.e.
Media file hidden folder Name of the folder where thumbnails of media files will be stored. This folder is hidden in the file system by default and thumbnails are generated within it.
Media file thumbnail suffix Suffix added to thumbnail files. The thumbnail files' names are in the following format:
HTML5 support
Render HTML5 media tags If enabled, the system renders HTML5
Media extensions to be rendered with HTML5 Specifies a list of media extensions to be rendered with HTML5 media tags. Enter a list of extensions separated by semicolons, e.g. .mp4;.ogg.
Settings - Blogs The Blogs settings category allows adjusting the following settings:
General Send blog emails from Email address that will be used as the Sender ('From') address of notification emails.
Enable blog post trackbacks If checked, specified blog posts are pinged after the new blog post is saved. Clear this setting if you are creating your site on the production server to avoid creating trackbacks to your production server.
Use external service for trackbacks Indicates if the external Scheduler Windows service should be used to process scheduled tasks which handle trackbacks.
Subscriptions
Blog unsubscription URL URL of a page on which the Blog post unsubscription web part is placed – this is a special web part used for handling unsubscriptions from receiving notifications about new blog posts.
Enable double opt-in for blog post comments Indicates if double opt-in should be enabled for blog post comments. When enabled, users are required to confirm their subscription by clicking a link that is sent to them in an email.
Double opt-in approval page path Path to the page that contains the Blog post subscription confirmation web part. The subscription confirmation link that will be sent to users will point to this page.
Double opt-in interval (hours) Amount of time in hours, during which the users have to confirm their subscription request.
Send double opt-in confirmation Indicates if an email confirmation should be sent to users after they approve a subscription. If double opt-in is disabled, these confirmation emails are always sent.
Related pages Configuring blogs
Settings - MetaWeblog API
Allow automatic summary If enabled, blog post summary will be created automatically from the beginning of the blog post text, and will be as long as the value of the Summary length property. This is applied only when a post is created - when editing an existing post, the summary is not updated.
Summary length Length of automatic blog post summary in characters.
Delete unused attachments If enabled, all blog post attachments which are not used in post text or have not been uploaded via WLW (i.e. have been uploaded via Kentico user interface) will be deleted when an existing blog post is modified and then published from WLW.
Related pages Blogs Configuring blogs
Settings - Translation services
General
Enable translation services Enabling this setting allows users to create new language versions of pages and localize text values via translation services. The available translation options are determined by the other settings in this category.
Allow attachment translation Determines whether the system submits file attachments for translation along with the main content of pages. Translation attachments file types May be used to limit which attachment file types can be submitted for translation. Entered as a list of allowed file extensions separated by semicolons, for example: txt;docx;pdf
If empty, all types of attached files are included in page translations.
Translate web part properties Determines if text values entered into the properties of web parts are also submitted for translation. This allows translation of content added onto pages via text web parts such as Static text.
Only properties that have the Translate field flag enabled in the web part definition are included. By default, this setting is disabled for the majority of web part properties. You can configure this for specific web parts in the Web parts application by editing their properties on the Properties tab.
When the translation is imported, the system creates a resource string for each property, containing the translated values in the given languages. The original text values of the properties are replaced by localization macros, which insert the appropriate resource strings.
Automatically import translated submissions If enabled, the system automatically inserts translated content into pages when the data is imported into submissions.
Warning: This overwrites pages immediately when a service finishes the translations, without the approval of administrators.
With this setting disabled, users need to manually process completed translation submissions in the Translations application.
Encoding to use Sets the character encoding type for the XLIFF pages used to transfer translation data in and out of the system. For example: utf- 8
Enable REST translation service Enables or disables the translation REST service, which may be used to retrieve the data of pages and other types of objects in XLIFF format. It is also possible to import translated XLIFF data via REST.
The translation REST service is not affected by the general REST settings, which can be configured in Settings -> Integration -> REST.
Manual translation
Translation submission export folder Specifies the path of the folder in the file system where the service creates the zip packages with the translation source data (XLIFF files and instructions) when pages are submitted for manual translation.
If empty, the ~/App_Data/Translations/Export/ folder is used.
Translations import folder Sets the path of the folder from which the system imports zip packages containing completed translations.
If empty, the ~/App_Data/Translations/Import/ folder is used.
Delete ZIP after successful download If enabled, the system deletes the zip packages containing finished translations after importing the XLIFF data (the submissions can be managed in the Translations application).
Translation via e-mail
Translation submission recipients Specifies the addresses to which the system sends translation assignments when submissions are created for the e-mail service. You can enter multiple e-mail addresses, separated by semicolons.
To assign different translator addresses for specific languages:
1. Open the Translation services application. 2. Create a Clone of the Translation via e-mail service for each additional language. 3. Edit the services and enter the appropriate translator addresses into the Translation submission recipients prope rty. This property overrides the E-mail sender setting. E-mail sender When sending translation assignment e-mails, the system automatically sets the sender to the address of the user who submitted the translation. The value of this setting is used if no user address is available, for example in the case of translations submitted automatically or via the API.
Microsoft Translator
Client secret Enter the Client secret received when registering the application for the Microsoft Translator on the Azure DataMarket.
Client ID Enter the Client ID that you specified when registering the application.
Google Translator
API Key Enter a valid API Key, used by the Google Translator service to identify the application's translation project. You can obtain the key from the Google APIs console.
Translations.com
Project Director URL The URL of your project that you received when setting up the service at Translations.com.
Client user name Sets the user name under which the application accesses the Translations.com service.
Client user password Enter the password matching the client user name.
Project short code A code string used to identify your translation project.
Related pages Configuring content for translation
Settings - URLs and SEO
URL format
Forbidden URL characters This setting allows you to list additional characters that should be replaced or removed in URLs (page aliases and URL paths).
The following characters are forbidden by default:
\/:*?"<>|&%.'#[]+=„“ and the space character.
If necessary, the default set of forbidden characters can be overridden through the CMSForbiddenURLValues web.config key.
Forbidden characters replacement Specifies the character that the system uses as a replacement for forbidden characters in URLs.
Allowed URL characters Determines which characters are usable in URLs by means of a regular expression. Any characters not specified are forbidden. If empty, only the characters specified by the Forbidden URL characters setting are prohibited.
When allowing special characters in the regular expression, they must be preceded by a backslash (\) as an escape character.
Example: Entering a-zA-Z0-9\^ as the value only allows alphanumeric characters and the caret symbol (^) to be used in URLs.
Note: this setting cannot be used to allow the default forbidden URL characters. Friendly URL extension Specifies the extensions that the system adds to page URLs.
Extensions must be preceded by the period character. You can add multiple extensions separated by semicolons (;). The first extension is used as the default option when generating links and page URLs. Additional extensions are supported in URLs when accessing pages. To allow extensionless URLs, enter a semicolon without any extension.
Sample value: .aspx;.html;.htm;;
Files friendly URL extension Specifies the extension that the system adds to file URLs.
Example: getfile/
If empty, the file URLs end with no extension: getfile/
Excluded URLs Specifies a list of URLs that are excluded from the URL rewriting engine. By excluding the URLs of physical pages stored inside the web project directory, you can improve their page load performance and also prepare scenarios with custom URL rewriting logic.
Warning: Do not exclude the URLs used by the regular pages in the website's content tree.
To disable URL rewriting for pages, enter the matching URL paths:
Use URL paths without the website's domain name or virtual directory. The paths must always start with a forward slash (/), without the virtual path designator (~). Entering a value excludes all URLs that start with the given path, including sub-directories and all possible extensions. You can enter multiple URLs separated by semicolons (;).
Sample values:
/Custom.aspx - excludes the ~/Custom.aspx page stored directly under the website's root. /Custom - excludes all pages whose URL path starts with /Cu stom, for example: ~/Custom.aspx, ~/Custom2.aspx, ~/Custo m/Page.htm /Custom;/Static - excludes all pages whose URL path starts with /Custom or /Static.
Page URLs
Default URL path prefix Defines a default URL path prefix that will be used for all URLs of the content pages. This prefix is rewritten to urlpathprefix query string parameter.
Use name path for URL path If checked, the name path of pages will automatically be copied into their URL path when they are saved.
Use permanent URLs If enabled, URLs of pages and page attachments will be generated in permanent format. If disabled, friendly URLs will be used. Learn more in Linking pages and files.
Remember original URLs when moving pages Determines if new page aliases should be created when a new page URL path or extension is set.
Automatically update page alias If enabled, the alias of a page is automatically updated to match any changes in the name of the given page in the default culture. Also, the page alias property will not be editable manually.
Search engine optimization (SEO)
Google sitemap URL Sets the URL where the website's Google (XML) sitemap can be accessed. The entered value is added to the website's domain to form the final URL. The internal path to the page responsible for generating the sitemap can be specified through the Google sitemap path setting. Google sitemap path Specifies the path of the page used to generate the website's sitemap. This page must contain the Google Sitemap (XML Sitemap) web part. If left empty, a full sitemap of the website is automatically generated by the ~/CMSPages/GoogleSiteMap.aspx system page.
This only sets the internal path of the sitemap. The actual URL where web crawlers can read the sitemap is determined by the value of the Google sitemap URL setting.
Robots.txt path Specifies the path of the page used to provide the website's robots. txt file. This page should contain a Custom response web part configured to generate the required robots.txt content.
Regardless of the selected page's location in the content tree, its output is returned whenever the
Allow permanent (301) redirection If enabled, the system uses permanent (301) redirection instead of standard temporary (302) redirection. This is highly recommended, because it allows web crawlers to properly react to any changes made on your website and pass page rank to the new or main URL.
Move ViewState to the end of the page If enabled, the system places the ViewState field at the end of the output code generated for pages. This helps search engine crawlers process more page content.
Use NOFOLLOW for user links If enabled, the system instructs search engine crawlers (robots) not to follow links posted by users on forums, message boards or in blog comments. This is achieved by including the rel="nofollow" attr ibute in the output code of all such link tags.
This precaution can help prevent user-generated links from damaging the search ranking of your website.
Default replacement page The entered page path is loaded as the default value of the Replac ement page field if users choose to specify an alternate page while deleting a page in the Pages application.
If necessary, users can override the default value and set a different replacement page path.
SEO - URLs
Use URLs with trailing slash Specifies how the rewriter handles trailing slashes in URLs. Possible options:
Leave the URL as is Always use URLs with a trailing slash Always use URLs without a trailing slash
Redirect page aliases to main URL Enabling this setting ensures that pages always have only one valid URL and other aliases are redirected to this main URL (for SEO purposes). The main URL of a page is determined either by its alias path, or custom URL path if one is specified.
Note: You can override this setting for individual page aliases through their Alias redirection property.
Redirect invalid case URLs to their correct versions Determines how the system handles the letter case of characters in URLs. Available options:
Do not check the URL case Use the exact URL of each page Redirect all requests to lower case URLs Redirect all requests to upper case URLs
Redirect pages to main extension If enabled, the system ensures that all page URLs use the current main extension. The main extension is the first one specified in the Friendly URL extension setting. Any URLs with a different extension are automatically redirected to a corresponding URL with the main extension.
Process domain prefix Determines how the rewriter handles the www domain prefix in the website's URLs. You can leave the domain as it was entered or have it rewritten to either always or never include the www prefix.
Note: That this setting does not apply for IP addresses and toplevel domains. Default page Allows you to redirect (permanent 301) all possible URLs that access the home page of your website to one single URL. Using a unified home page URL is highly recommended, because it prevents the duplicate content problem on your website's most important URL.
You can choose from the following options for the home page URL:
Not specified - supports all possible home page URLs and does not perform any redirection. Use domain root - always uses the base URL of the website's domain name. Use page defined by default alias path - always uses the URL of the paeg specified by the website's Content -> Default alias path setting. Use default page URL - always uses the default URL:
Important: This setting only works correctly if the website is hosted on IIS 7 or newer, and uses an application pool with an Integrated Managed pipeline mode.
SEO - Cultures
Force domain culture If checked, the system generates the domain name in page URLs based on the current content culture. Whenever a user switches to a different language on the website, the URL is redirected to the corresponding domain name.
You can assign cultures to domains by editing your site in the Sites application:
Set the culture of the website's main domain through the Visit or culture property on the General tab. To define domain names for other languages, create Domain aliases with an appropriately set Visitor culture.
Note: You cannot use this option in combination with language prefixes.
Use language prefix for URLs If enabled, the system generates page URLs with language prefixes. A language prefix is a subdirectory inserted into the URL. The name of the prefix matches the culture code (or culture alias) of the content culture selected on the website.
Example:
Allow URLs without language prefixes If enabled, URLs without language prefixes are allowed. Otherwise the system redirects such URLs to a corresponding URL that includes a language prefix.
Only applies if Use language prefix for URLs is enabled.
Related pages Search engine optimization Configuring page URLs Configuring URLs for multilingual websites Managing robots.txt
Settings - Security & Membership
General
Administrator's email Specifies the administrator's e-mail address. It is used in places where the administrator's e-mail address cannot be specified in the administration interface or in web part properties (e.g., user account confirmation page). Send membership reminder (days) Determines when the system should send email notifications about Memberships that will soon expire. The value sets how many days before the expiration date reminders should be mailed out.
These e-mails are only sent for memberships that were assigned with the Send notification flag enabled and for those that were purchased as a product with a limited duration.
Memberships are checked periodically using the Membership reminder scheduled task. The content of the notifications is based on the Membership - Expiration notification email template.
Deny login interval Interval in minutes during which kicked users cannot log back in to the site.
Share user accounts on all sites If enabled, user accounts created on one site will be shared among all the sites running on the installation. If disabled, new accounts will be assigned only to the current site and not the others.
Use site prefix for user names If enabled, user names only need to be unique for each site, not globally. It is possible to create users with names that are already taken on another site in the system.
When a user registers on the live site or is edited/created on a specific site (i.e. in the Users application), the system internally adds the unique identifier (GUID) of the given site as a prefix to that user's name.
Do not enable this setting if you wish to have accounts shared across multiple sites.
Warning: Use this setting only if you have your system's user/site organization planned according to the functionality described above. Reverting back to the default state where user names are globally unique would require a significant amount of effort and direct editing of your user database.
Registrations
Reserved user names Sets a list of users names that cannot be selected during registration. Entered user names must be divided by semicolons.
Registration requires e-mail confirmation Indicates if user registration should require confirmation via email ( double opt-in).
Registration confirmation page path Path to the page that contains the Registration e-mail confirmation web part. The registration confirmation link that will be sent to users will point to this page.
Registration requires administrator's approval Indicates if an administrator's approval is needed for a user to get registered.
Delete non-activated user after (days) When users register but do not activate their account, their account will be deleted after the entered number of days.
Require unique user e-mails If checked, users cannot enter an e-mail address during registration if the address is already used by another user's account.
On-line users
Monitor on-line users Enables monitoring of on-line users who are currently browsing the website.
Store on-line users in database If checked, records about on-line users will be stored in the database. This is necessary when running the system on a web farm.
Storing the data in the database also allows the system to provide more detailed information about anonymous users (guests) when using Contact management.
Update on-line users (minutes) Interval in minutes after which information about on-line users will be updated. When running the system on a web farm, you need to enter the same value which is set for the Sessions remove expired sessions scheduled task (you can read the value in the S cheduled tasks application -> edit Sessions remove expired sessions -> Task interval -> Every: X minutes).
Content Check page permissions Indicates if the website should check the user permission settings of pages and apply them. You can configure the permissions of pages in the Pages application on the Properties -> Security tab.
The following values are possible:
All pages - permissions will be checked for all pages on the website. No page - permissions will not be checked for any pages. Secured areas - permissions will be checked only for pages that are configured to require authentication.
Website logon page URL Specifies the URL of the page where users can sign in on the website in order to access its secured areas.
Note: This page is different from the one used to log into the administration interface.
Access denied page URL URL of the page that should be displayed when a user is not allowed to read a page.
Administration
Use SSL for administration interface Indicates if the pages of the administration interface should automatically use URLs that are secured by the SSL protocol (i.e. with the https URL scheme).
Automatically sign-in user when site changes If enabled, users will not need to enter their username and password when they switch between edited sites in the administration interface (using the Site drop-down list).
Enable code editing for site administrators Indicates whether users with the Administrator privilege level are automatically allowed to edit code on the website. If disabled, administrators can still edit code if they have the appropriate permissions assigned: Edit Code for the Design module or Edit SQL Queries for the Reporting module.
The restriction applies to ASCX code of page layouts and transformations (modifying the HTML version of the code is allowed regardless of the setting), and SQL queries, e.g. for objects in the Reporting module.
See Special security permissions.
UI personalization
Enable UI personalization Indicates if UI personalization should be enabled. If this is the case, users only see those parts of the UI that are allowed for the UI profile assigned to their roles. If disabled, the entire UI is visible for all users.
Reporting
Default report connection string Sets the database connection string that the system assigns to newly created reports. Existing reports also inherit the connection string value from this setting by default.
Only users who have the Set connection string permission for the Reporting module can change the connection strings of individual reports.
The system loads the list of connection strings from the
You can use reporting connection strings for the following scenarios:
Retrieving data from a Separated on-line marketing database Restricting the database-level permissions of reporting queries via a connection string with a limited database user
Related pages Security model overview
Settings - Passwords
Passwords
Send password e-mails from Sets the e-mail address from which password recovery e-mails will be sent.
Password format Selects the format used to store the passwords of users. They may either be saved in plain text or as the result of a security hash function. The recommended option that provides the best security is SHA2 with salt.
If you change the password format, please keep in mind that this only affects how future passwords are stored and existing passwords will remain unchanged. It is necessary to set all passwords again so that they are stored in the new format. For this reason, it is recommended to set the appropriate format directly after the installation, before you create user accounts or allow users to start registering.
Note: An empty string in the UserPassword field of the CMS_Use r database table is considered to be a blank password for both plain text and hashed password formats. If you forget the global administrator password, you can manually insert an empty value to reset it.
Password reset
Reset password requires email approval If checked, users who submit a password recovery request through a logon form will not receive their password directly, but will instead be sent an email containing a link to a page where they can manually set a new password.
If disabled, the system will send an email to the given user containing their current password if passwords are stored in plain text, or a newly generated password if hashing is used.
Reset password page URL Sets the URL of the page where users can change their password after they submit a password recovery request. The Reset password web part must be placed on the specified page to ensure that users can set a new password.
The value of this setting is used by the administration interface logon page and inherited by individual Logon form web parts if their own Reset password page property is not set.
If empty, the ~/CMSModules/Membership/CMSPages/ResetPas sword.aspx default page is used.
Reset password interval Sets the length (in hours) of the time interval during which users will be allowed to change their password after submitting a password recovery request (if the Reset password requires email approval setting is enabled). After the specified amount of hours, the link in the password recovery email will expire and become invalid.
Send email with reset password If enabled, users will receive another email containing their new password once they successfully reset it.
Password expiration
Enable password expiration Indicates, if user's passwords should be valid only for the number of days specified in the following setting.
If disabled, users' passwords never expire.
Password expiration period (days) Specifies the number of days after which the users passwords become invalid.
Password expiration behavior Specifies the behavior of the system after a user's password becomes invalid. See Password expiration for more information.
Password expiration warning period (days) Specifies the number of days for which should be a warning message displayed before the user's password expires. Send password expiration e-mail Indicates, if the system sends the users e-mails when their passwords expire.
Password policy
Use password policy Indicates if a security policy should be used to validate the passwords entered by users for their accounts. The details of the policy can be specified through the settings below. Passwords that do not meet the required conditions will be rejected.
Enabling this setting does not change the passwords of existing users, it only adds requirements that must be fulfilled by new passwords.
Force password policy on logon Indicates, if the system checks whether the users' passwords meet the configured password policy whenever the users try to log on. When the passwords do not meet the requirements, the users are forced to change the password.
If disabled, the policy is applied only to the passwords of newly registered users.
Minimal length Sets the minimum number of total characters required for user passwords.
Number of non alphanumeric characters Sets the minimum number of non alphanumeric characters (i.e. any character except for numbers and letters) that must be present in a password in order for it to be accepted.
Regular expression Can be used to enter a regular expression that will be used to validate user passwords. This regular expression is applied in combination with the other policy settings.
For example: ^(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).*$
This sample expression would require passwords to contain at least one lower case letter, upper case letter and number. The minimum amount of characters would be determined by the remaining policy settings.
Policy violation message Specifies a custom text message that will be displayed to users who attempt to enter a password which does not fulfill the requirements of the password policy. If left empty, a default message will be shown, informing about the minimum password length and number of non alphanumeric characters.
If you specify a regular expression for passwords, it is recommended to describe its requirements in this message.
If your site has multiple cultures (languages) assigned to it, you can enter a different message for each language via the Localize actio n.
Related pages Security model overview Securing user accounts and passwords Password strength policy and its enforcement
Settings - Protection
General
Display account lock information message Indicates if user friendly information about account lock should be displayed.
Enable Autocomplete If true Autocomplete for user name text box in login form is enabled.
Bad words
Check bad words Determines if bad word check should be performed.
Bad word replacement Default replacement text which will be used during bad word check. Bad word action Default action which will be performed during bad words check.
Banned IPs
Enable banned IPs Enables or disables banned IPs features.
Redirect banned IPs to URL If the IP address is banned the user is redirected to this page.
Flood protection
Enable flood protection Enables or disables flood protection, which prevents spam on forums and other community services.
Flood protection interval Value in seconds which represent the minimal interval between user's actions.
CAPTCHA settings
Control to use Determines the default CAPTCHA control that should be used for CAPTCHA verification throughout the system – in web parts and for the Security code form control. The following four types of controls are available:
Logic CAPTCHA - requires answering a logical question. Simple CAPTCHA - requires re-typing of a string displayed in an image. Text CAPTCHA - requires re-typing of a string into multiple fields. reCAPTCHA - requires re-typing of two words from which one is checked for correctness.
The behavior of these form controls throughout the system can be changed by modifying the settings of the individual controls.
reCAPTCHA private API key Private key for the domain you want to use reCAPTCHA on. You can obtain the necessary API keys at http://www.google.com/recap tcha.
reCAPTCHA public API key Public key for the domain you want to use reCAPTCHA on. You can obtain the necessary API keys at http://www.google.com/recap tcha.
Invalid logon attempts
Maximum invalid logon attempts Maximum invalid logon attempts before user account is locked. If set to 0, invalid logon attempts functionality is disabled.
Send unlock account e-mail Indicates if account unlock e-mail is sent when a user account is locked due to reaching maximum invalid logon attempts.
Unlock user account path Path to custom page for unlocking user account (if not set, system page ~/CMSModules/Membership/CMSPages/UnlockUserAccount.aspx will be used).
Screen lock
Enable screen lock Enables or disables screen lock feature, which locks the part of the browser with the Kentico administration interface.
Lock interval (minutes) Time (in minutes) that has to pass before the screen is locked. This value has to be greater than 0 and lower than session timeout.
Warning interval (seconds) Warning period (in seconds). Warning with countdown is shown for this number of seconds before the screen is locked.
Settings - Authentication On this tab, you can adjust settings related to the Multi-factor authentication.
The multi-factor authentication settings have global effect. They cannot be configured for individual sites.
Multi-factor authentication
Enable multi-factor authentication Indicates, if multi-factor authentication is enabled. Users can choose to enable multi-factor authentication when they register to your website. Display initialization token Displays an initialization token when a user tries to sign in to Kentico with multi-factor authentication for the first time. The user types the token into the Kentico Passcode generator mobile application.
Disable if you want to use customized multi-factor authentication (without the mobile application).
Multi-factor authentication is required globally Indicates if all users in the system including newly created users are required to use multi-factor authentication.
Settings - OpenID On this tab, you can adjust settings related to OpenID authentication.
General
Enable OpenID Indicates if OpenID authentication is enabled.
Assign new users to roles New users registered via OpenID will be assigned to these roles.
Required user data page URL of the page where the OpenID required data web part resides. If entered, then when a new OpenID user logs in to the site, their user account is not created automatically, but they are redirected to this page and required to enter some additional data (or merge with an existing account) using the web part.
Settings - Windows LiveID On this page, you can set up support for Windows Live ID authentication.
General
Enable Windows Live ID authentication Indicates if users should be allowed to log in to the website using their Windows Live ID credentials.
Application ID Identifier of your website. Enter the Client ID that you received when registering your website as a Live ID application.
Application secret Secret code that will be used to encrypt messages transferred between your website and the Live ID server. Enter the Client secret that you received when registering your website.
Assign new users to roles New users registered via Live ID authentication will be assigned to the roles specified here.
Required user data page URL of a page containing the Required LiveID user data web part. If entered, new Live ID users who log into the site will not have their user account created immediately, but will first be redirected to the specified page where they will be required to enter some additional data (or merge with an existing account) using the web part.
Related pages Configuring Windows Live ID authentication
Settings - Claims-based authentication On this tab, you can adjust settings related to Claims-based authentication.
Note: You may need to set up SSL for your site to use certain identity providers.
General
Enable WIF authentication Enables claims-based authentication.
Users need to log in through the identity provider specified by the settings below (for example Active Directory Federation Services or Access Control Service). Disables the standard authentication mechanisms in Kentico. Identity provider URL Specify the URL of your identity provider's WS-Federation passive endpoint.
You can find the value in the provider's configuration interface or WS-Federation metadata.
Examples:
https://adfs.net/adfs/ls https://accesscontrolnamespace.accesscontrol.windows.net/v 2/wsfederation
Security realm Enter a URI that identifies your website or application. You can use your website's domain name (and virtual directory if applicable) in most cases.
The value must be exactly the same as in the relying party config uration of your identity provider, including letter case, any trailing slashes and the protocol (http or https).
Allowed audience URIs URIs of allowed audience for the identity provider, separated by semicolons. The value must match the corresponding relying party settings of your identity provider, including letter case, any trailing slashes and the protocol (http or https).
To allow the authentication for all restricted sections of your website and the Kentico administration interface, use the base domain name of the website.
Trusted certificate thumbprint Enter the thumbprint of the certificate used to secure the communication between Kentico and the identity provider.
You can typically find the certificate thumbprint in the provider's Key/Certificate configuration.
Certificate validator Sets the validation mode used for the X.509 certificate specified in ______the Trusted certificate thumbprint setting.
Chain trust - accepts certificates whose chain of trust leads to a trusted certification authority. The certificate must be installed on the server hosting Kentico in the Local Computer -> Trusted People certificate store. Peer trust - accepts self-issued certificates. The certificate must be installed on the server hosting Kentico in the Local Computer -> Personal certificate store. Peer or chain trust - accepts self-issued certificates, or certificates with a chain that leads to a trusted certification authority. None - no validation of the certificate is done and the system accepts any certificate with the given thumbprint.
See Working with Certificates.
Settings - System
General
Default user ID Default user ID that is used when no current user is defined.
DB object schema Sets the database schema that is used for newly created database tables (e.g. for custom page types). The only values that make sense are either dbo or the current database user. If not specified, the current database user is the owner of the tables.
Object code name prefix A default prefix added to all object code names in the system. The prefix is added upon object creation.
Event log
Event log size The number of events stored in the Event log.
When exceeded by 10% (or a different percentage set by means of the CMSLogKeepPercent web.config key), the percentage of the oldest events is deleted from the log in a batch.
Set 0 if you do not want the system to log any events. Log metadata changes Indicates if changes of object and page metadata (i.e. when an object or page is created, edited or deleted) are logged in the Event log.
Log to database Indicates if events are logged to the database. Doesn't overwrite E vent log size set to 0.
Log to filesystem If enabled, the system writes the event log into the CMS\App_Data \logEvents.log file on the server's file system. Doesn't override Ev ent log size set to 0.
Log to trace Indicates if events are logged to trace. Doesn't overwrite Event log size set to 0.
Use EventLog trace listener Indicates if the system logs events in your Windows Event Viewer.
Use the Modify feature of the Kentico installer, if you haven't turned on the Registration of Kentico in Windows Event Log opt ion when installing Kentico.
E-mails
No-reply e-mail address Various types of automated e-mails will be sent from the e-mail address that is specified here.
Error notification e-mail address E-mail notifications about errors logged in the event log will be sent to the specified addresses. It is possible to enter multiple addresses separated by semicolons.
Send e-mail notifications from E-mail address used as the sender for e-mail notifications.
Scheduler
Application scheduler interval Determines how often the application checks if there are any tasks ready to be executed (in seconds).
By default, the scheduler is configured to check tasks only on page requests. You can set the minimum time between the checks to any interval. If it is configured to check automatically, you can set an interval of 1 to 30 seconds.
Setting 0 stops the scheduling of tasks.
Use external service Indicates if scheduled tasks that have the Use external service op tion enabled are processed by the Kentico Scheduler Windows service.
Note: for this to work, the service must be installed and running. If enabled and the service is not running, these tasks are not processed at all. If disabled, all scheduled tasks are processed by the application itself. You can install the service using Kentico Service Manager.
Service scheduler interval Determines how often the external Windows service checks if there are any tasks ready to be executed (in seconds).
You can set an interval of 1 to 30 seconds.
Setting 0 stops the scheduling of tasks.
Scheduled tasks enabled Scheduled tasks will only be executed if this setting is enabled.
Time zones
Enable time zones Indicates if time zone support is enabled.
Server time zone Specifies the time zone of the physical location of the server.
Site time zone Specifies the time zone for the selected site.
User interface
Hide unavailable user interface Indicates if the user interface is hidden for features unavailable due to license restrictions.
Max UI tree nodes Maximum number of nodes displayed under one parent node in the administration UI trees. Any additional tree nodes will be accessible via the click here for more... option, which automatically selects appropriate parent category. Remember listing, filter and state If enabled, listing pages in the user interface remember the preferences set by individual users, including:
filtering options sorting order the number of the selected page page size
Kentico improvement program
Send anonymous usage records to Kentico Enable to periodically send data about the system's usage to Kentico. The data will help Kentico analyze which parts of the system need improvement and allow us to better focus our development efforts.
All of the data is strictly anonymous and for internal use only. Please see How Kentico protects your privacy.
Settings - Performance
General
Enable output compression Enables compression for the HTML output code of all pages rendered by Kentico.
Output compression requires compliance from client browsers. Browsers that do not support compression always download uncompressed page output.
Applies globally for all sites in the system.
Server content caching
Cache page info (minutes) Sets the number of minutes for which the system caches page information (basic page properties and metadata). Kentico retrieves page information many times during the processing of a single page, so always set this value to at least 10 minutes.
When a page is modified, the system automatically clears the corresponding part of the page info cache. This type of caching cannot cause the website to display outdated information.
Cache content (minutes) Sets the number of minutes for which web parts/controls with data sources cache their content (typically retrieved from the Kentico database).
You can override this value for specific web part instances by setting their Cache minutes property. Using 0 as the value disables content caching for the given web part instance.
It is recommended to cache all possible content. You can use cach e dependencies to clear the cache on content changes. For most non-custom data sources, the default dependencies automatically ensure that web parts reload the cached content whenever the data is modified.
Use progressive caching If checked, the system optimizes access to uncached data so that concurrent threads only use a single data access operation and share the results. This leads to better performance if the website is under a heavy load, without the drawback of not having the latest data available.
Server file caching
Cache files (minutes) Sets the number of minutes for which the system caches images and other files on the server. Includes images, and web resources such as CSS stylesheets and JavaScript files.
The system always caches files for at least one minute to protect against brute force attacks. Kentico automatically removes files from the cache if they are modified, so file caching cannot cause the website to display outdated content.
Maximum file size to cache Specifies the maximum file size in kilobytes that is allowed to be cached. Setting a limit stops the file cache from using an excessive amount of memory. Redirect files to disk If enabled, the system redirects file requests for page attachments and content tree files to the corresponding physical file (if the requested file is stored in the file system).
Warning: The system stores files on the file system with GUID identifiers instead of names (to avoid conflicts). If you enable the R edirect files to disk setting, files downloaded by users have names in the GUID identifier format instead of the original file name.
Client-side file caching
Client cache (minutes) Sets the number of minutes for which client browsers are allowed to cache files (i.e. the length of the client cache expiration time). Client file caching includes images, and web resources such as CSS stylesheets and JavaScript files.
To ensure that files are always up-to-date in the client cache, set the value to 0 and enable the Allow client cache revalidation sett ing.
To completely disable client caching of files, set the value to 0 and disable client cache revalidation.
Allow client cache revalidation If enabled, browsers perform revalidation when requesting files that have expired in the client cache. Revalidation allows the client cache to refresh unchanged files without loading the file data from the server. If disabled, browsers always fully reload expired files.
Revalidation can have the following results:
If the server contains a newer version of the file than the client cache, the revalidation fails and the server returns the full file (standard 200 HTTP response). If the file is unchanged, the server returns a 304 Not Modified response. The client cache keeps the file and refreshes the expiration time. The client and server only exchange HTTP header information, which is significantly faster than fully reloading files.
Output caching
Enable output caching If checked, the system allows output caching. Output cache stores the full HTML source of pages. If unchecked, output caching is disabled on the whole website.
To enable output caching for pages, configure the Output cache p roperties of individual pages in the Pages application on the Prope rties -> General tab. Both the main website setting and page settings must be enabled to use output caching.
Cache output in file system (minutes) Specifies the number of minutes for which the system stores output cache in the file system. This provides persistent cache storage in case of application restarts.
If not set, only the standard caching mechanism (in memory) is used. If you enter a value, the system loads the output data of requested pages from the file system cache when it is not found in the memory cache.
To enable output caching in the file system for pages, configure the Allow file system cache property of individual pages in the Pages application on the Properties -> General tab.
Warning: Enabling the file system output cache may cause your website to serve outdated content. When clearing invalid output cache due to changes made to pages or other dependencies, the system only removes cache files if the corresponding cache item also exists in the memory. The file system cache remains outdated if the memory cache is not available when the invalidation occurs (for example after an application restart or if you have different expiration times set for the two caching types). Output cache variables Determines under which conditions the system stores multiple versions of the output cache for pages. Click Edit to change the default settings.
For example, the username variable ensures that the system stores a separate version of each page's output cache for every logged in user. If disabled, the output cache does not distinguish between users — if a page's output is cached for one user, the system may load the same content for all other users (depending on the remaining output cache variables).
You can enable or disable separate output cache for:
username - every logged in user (public users share the same output cache). sitename - every site in the system (leave checked unless your sites all have identical content on pages with the same path). lang - each language version of pages. browser - different types of web browsers. cookielevel - the cookie level preferences of visitors. deviceprofile - the device profiles detected for visitors. domain - the website domain name (check to disable output cache sharing between different domain aliases of sites). viewmode - the page view modes used by Kentico, such as e dit, preview or live site. Currently, the system only uses caching for the live site view mode.
The output cache always creates separate cache items based on the:
Page path (including the virtual directory and extension) Protocol in the request URL
Enable partial caching If checked, the system allows partial caching of web parts. The partial cache stores the HTML output of individual web part instances. If not checked, partial caching is disabled on the whole website for all web parts.
By default, web parts do not use partial caching. You need to enable partial caching for individual web part instances using the P artial cache minutes property.
Partial cache variables Determines under which conditions the system stores multiple versions of the partial cache for web parts. Applies globally to the partial cache of all web parts.
Click Edit to change the default settings.
For example, the lang variable ensures that each web part instance has a separate version of the partial cache for every language. If disabled, the partial cache does not distinguish between languages — if a web part's output is cached for one language, the system loads the same content for all languages (depending on the remaining partial cache variables).
You can enable or disable separate partial cache for:
username - every logged in user (public users always share the same partial cache). sitename - every site in the system (leave checked unless your sites have identical content). lang - each language version of pages. browser - different types of web browsers. viewmode - the page view modes used by Kentico, such as e dit, preview or live site. Currently, the system only uses caching for the live site view mode.
Resources (global settings only)
Allow resource compression If enabled, the system compresses JavaScript and CSS stylesheet web resources before sending them to the client browser. This reduces the amount of data that must be loaded. Uncompressed versions remain available for browsers that cannot process compressed data.
Minification of the given resource type must be enabled (via the All ow JavaScript/CSS minification settings) in order for compression to be applied. Allow JavaScript minification Indicates if JavaScript resources should be minified before they are served to the client browser. Minified code has a reduced size, which saves bandwidth and decreases response times, but may not be suitable for debugging.
Allow CSS minification Indicates if CSS stylesheet resources should be minified before they are served to the client browser.
CSS Styles (global settings only)
Resolve macros in CSS If checked, macro expressions can be used in CSS stylesheets to dynamically insert the content of other stylesheets.
To insert this type of macro, add an expression into the code of a stylesheet according to the following format: {%CSS["
Warning: If you wish to disable this setting, you first need to remove all occurrences of macros from your stylesheets. Unresolved macro expressions are not valid CSS code, so browsers cannot process stylesheets containing macros.
Allow CSS from components If enabled, CSS styles defined for individual page components (e.g. web parts, page templates etc.) are automatically requested by the page where they are placed. Otherwise, you either need to have all styles defined in the website's stylesheet, or link the styles of the required components into the stylesheets via CSS macros.
Combine CSS from components If enabled, pages load the CSS styles of all contained components via a single request. Otherwise different types of components each generate a separate request. The styles of multiple components of the same type (e.g. several web parts) are always retrieved by a single request.
Combining the CSS requests into one may improve the load time of individual pages and is recommended in most cases.
Related pages Optimizing website performance Configuring caching Using code minification and compression Designing websites using CSS
Settings - Emails
General
Email encoding Sets the character encoding used for emails sent by the system. By default, UTF-8 is used. It is recommended to leave the default encoding unless you encounter issues with extended characters in your emails.
Email format Format used for email messages. You can choose between HTML and Plain text. If Both is selected and an email template has both formats defined, HTML will be used for the email text and plain text will be included as an attachment.
Email processing
Enable emails If checked, email sending will be enabled. You can temporarily disable sending of emails by clearing this check-box, e.g. when performing administration tasks.
Enable email queue If checked, an email queue will be used when sending emails. This allows advanced email processing and automatic resending of mails that are lost due to errors. If disabled, emails will be sent directly to the SMTP server.
Using the email queue is highly recommended when sending out large amounts of emails over a short amount of time (email campaigns or other types of mass emails). Batch size Sets the maximum number of emails that can be transferred from the email queue to an SMTP server in one batch. If the specified value is smaller than the total amount of emails to be sent from the queue, a new batch is prepared and assigned to the next available server. This process is repeated until all emails are mailed out.
This setting affects all sites in the system, so it is only available if the (global) option is selected from the Site dropdown list.
Archive emails (days) Sent emails will be stored by the email queue for the number of days specified here. Such emails may be viewed in the Email queue application on the Sent emails tab.
If set to 0, emails will not be archived.
Default SMTP server
SMTP server The SMTP server specified here will be used as the default option when sending emails. Depending on the value selected in the Site dropdown list, the server will either be dedicated to a single website, or will be designated as a global server (i.e. it will accept emails from all sites in the system and also handle mails that are not related to any specific website).
This field must contain the domain name or IP address of the server. If the connection to the server should use a different port than 25, please include it in the name. Enter localhost if you wish to use the server provided by your local machine.
You can define additional servers that will be used if this one is busy in the SMTP servers application.
SMTP server user If the server requires authentication, you can enter the user name here.
SMTP server password If the server requires authentication, you can enter the password here.
Use SSL Indicates if the SMTP connection to the server should be secured by SSL. The server must be configured to use SSL in order for this to work.
Settings - Files
Storage
Store files in file system Indicates if files should be stored in the file system.
Store files in database Indicates if files should be stored in the database.
Generate thumbnails Indicates if the Kentico should generate image thumbnails on the disk when a resized version of the image is displayed. This option only applies if files are stored in the file system. It improves site performance.
Files folder The folder on the disk where page attachments and metafiles are stored. You can use:
physical disk path: e.g. c:\myfiles\ virtual path: ~/UploadedFiles UNC path: \\server\folder
If you do not specify any value, the files are stored in folder ~/
Use site-specific subfolders for custom files folder This setting is only applied when a Custom form files folder is configured. If enabled, attachment files will be stored in a sub-folder named according to the code name of the site where the form is placed, i.e.
physical disk path: e.g. c:\myfiles\mysite virtual path: ~/UploadedFiles UNC path: \\server\folder
If no value is entered, the files are stored in ~/
Use site-specific subfolders for custom form files folder This setting is only applied when a Custom form files folder is configured. If enabled, attachment files will be stored in a sub-folder named as the site code name under the custom files folder, i.e.
File import folder Path to the source folder where files to be imported by the File import should be uploaded before import. If no value is entered, ~/ CMSImportFiles is used by default.
Security
Upload extensions Specifies which extensions are allowed for uploaded files. You can restrict the types of uploaded files by entering a limited list of extensions separated by semicolons, for example: gif;jpg;doc;pdf
This allows you to block users from uploading potentially dangerous files, such as ASPX scripts. If no value is specified, uploading is allowed for all file types.
Check if files are published If checked, only files that are in the Published workflow step can be accessed from the live site when a workflow is applied to the page.
Check files permissions If checked, page permissions are applied to the files.
Image resizing
Automatic image resize on upload (width, height, max side size) Configures the system to automatically reduce the size of images when they are uploaded. The values are measured in pixels. The behavior depends on the values that you fill in:
No values are entered - images are not resized. Only width or only height - images are resized so that their width or height matches the entered value. The other dimension is also resized to preserve the image's aspect ratio. Both width and height - both dimensions of images are resized according to the specified values (if the given dimension is greater than the entered value). Aspect ratio is not preserved. Max side size - if one of the image's sides is larger than this value, the image is resized so that its larger side's dimension matches the entered value. Aspect ratio is preserved and width and height settings are not applied.
See Resizing images on upload for more information.
Watermark
Watermark image Allows you to specify an image file that the system adds as a watermark to images (according to the remaining settings in the category). There are two ways to set the watermark:
Enter the full relative path to a physical file on the server, for example ~/App_Themes/Default/Images/Powered_by_kentico .gif. You cannot use web links or images loaded using Kentico system pages, such as GetFile. Enter only the name of an image file located in the ~/App_The mes/Default/Images/Watermarks folder.
Watermark position Sets the position where the watermark is placed on the watermarked images.
Minimum image width for watermark Minimum width of an image to be watermarked.
Minimum image height for watermark Minimum height of an image to be watermarked.
Use watermark for page images If enabled, the system adds the watermark to images stored as page attachments. Use watermark for media files If enabled, the system adds the watermark to images stored in med ia libraries.
Use watermark for object attachments If enabled, the system adds the watermark to images stored as object attachments (metafiles).
Settings - Health monitoring On this page, you can configure settings related to the Health monitoring functionality. Health monitoring allows system administrators to observe and record the application's load and performance using an external application, e.g. the built-in Performance monitor in Microsoft Windows.
General
Enable health monitoring Indicates if Health monitoring is enabled. i.e. if monitored values are written to both General and Site performance counters related to this instance of Kentico. If disabled, no values are written to any of these performance counters.
Application monitoring interval Time interval (in seconds). In this periodic interval, the application reads monitored values and writes them to performance counters.
Use external service Indicates if external Windows service (Kentico Health Monitor) should be used to read and write monitored values to the Schedule d tasks in queue, E-mails in queue and Error e-mails in queue perf ormance counters. As these counters require database access to get their values, using the external service may optimize your application's performance.
Service monitoring interval Time interval (in seconds). In this periodic interval, the external Windows service reads monitored values and writes them to the performance counters. If you are using the Health Monitoring Windows service and change this value, it is necessary to restart the Windows service in order for the new value to be used.
Enable site counters Indicates if values are written to site specific performance counters. If disabled, values are written to general counters only.
Settings - Output filter The settings in this category allow you to adjust the Output filter, which performs additional changes to the final output code of pages before it is sent to the browser for rendering.
Applying output filters to your website
General
Excluded output form filter URLs May be used to disable the Form output filter for specific URL paths, which fixes the issue with nonworking postbacks on pages that use URL rewriting. It ensures that forms, dialogs and buttons will work correctly on pages managed by Kentico.
Excluded resolve filter URLs Allows you to disable the URL resolving output filter, which adjusts relative URLs so that they reflect the root URL of the website.
For example, ~/mypage1/mypage2.aspx would be changed to /my page1/mypage2.aspx (if the application is running in the root) or /Vi rtualDirectory/mypage1/mypage2.aspx (when using a virtual directory).
Only URLs inside src and href attributes are changed.
XHTML filter
Excluded XHTML filter URLs May be used to specify the URL paths of the pages that should be excluded from all functionality provided by the XHTML output filter.
Excluded XHTML attributes filter URLs Specifies the URL paths of the pages that should be excluded from the Tag attribute XHTML filter, which ensures that all attributes of HTML tags are generated in valid XHTML format.
Excluded XHTML JavaScript filter URLs Specifies the URL paths of the pages that should be excluded from the JavaScript tag XHTML filter, which ensures that the type and la nguage attributes are included in all
Resource requests with minification disabled
If minification is disabled, the system generates requests with a direct URL (for JavaScript files) or using the ~/CMSPages/GetCSS .aspx system page (for CSS stylesheets).
Requests in this URL format are always supported, but they do not perform minification or compression of resources. Enabling compression of page output
You can configure the system to compress the HTML output code of all pages rendered by Kentico.
Note: Output compression requires compliance from client browsers. Browsers that do not support compression always download uncompressed page output.
1. Go to Settings -> System -> Performance. 2. Check Enable output compression. 3. Click Save.
The setting applies globally for all sites in the system.
Setting up web farms Web farms distribute computing among multiple web servers that all provide the same content. Each server increases the number of requests that the web farm can serve, which allows you to scale the performance of the website. You can also use web farms to achieve high availability – if one of the servers in the web farm stops working, the other servers continue to run the site.
Native web farm support in Kentico provides the following features:
Synchronization of cache and content from a database to all web farm servers. Synchronization of changes made to the site settings on one of the servers to all other servers. Synchronization of files uploaded to the site between all servers. This is used only if you store uploaded files on the disk or on both disk and in the database.
The following image shows the structure of a web farm and how the synchronization works:
If you change some settings or upload a file using server 192.168.1.2, the other servers do not know about it in a standard scenario. However, if you are using web farm synchronization, the system automatically creates a new synchronization task in the database, and notifies the other servers to process their task. To learn more about how the synchronization works, see Web farm synchronization mechanisms.
To learn how to add web farm servers into the system and configure them, see Configuring web farm servers. Using Kentico on a web farm without configuring the web farm support
You can use Kentico on a web farm even without setting up the built-in synchronization mechanisms, especially if you do not store uploaded files in the file system. The only limitation in such scenarios is that if you change the settings or page content on one of the servers, the other servers may keep using the old version of the settings in their memory/cache until the web application is restarted or the cached content expires.
Please note: The web farm support doesn't replace load-balancing or web farm management tools.
To set up web farms:
1. Choose a synchronization mechanism. 2. Configure the web farm servers and enable web farm synchronization.
Web farm synchronization mechanisms When editors make changes to the content or physical files on a web farm server, the system logs the changes into the database as web farm tasks. This server then notifies other servers in the web farm to retrieve the web farm task data from the database and make appropriate changes in their file system or memory.
The system provides the following ways for notifying the other servers about changes in the web farm:
By request using URL notifications Using the database updater Using a scheduled task
When you are setting up a web farm, study the synchronization mechanisms properly and choose a single mechanism that suits your environment the best. Please do not use both URL notifications and database notifications at the same time. See the following table for a summary of the synchronization mechanisms.
Synchronization mechanism Advantages Disadvantages Suitable for
URL notifications Synchronization happens each Servers need to see each other Web farms with known number time a web farm task is created of servers High number of synchronizations can cause overhead
Database updater Works in every environment Web farms on Azure or Amazon services Can be used with automatic web farm configuration Web farms with dynamic number of servers
Scheduled task The synchronization period can High traffic projects where it is be adjusted possible to configure the Sched uler service Can be configured to run through an external service
Enabling a web farm synchronization mechanism after all mechanisms have been disabled
If you want to enable a synchronization mechanism after you have accidentally disabled all of them, the system will have no means of propagating the new settings through the web farm. Therefore, you need to restart the whole web farm in such situations:
1. Open the System application. 2. Click Restart all web farm servers.
The web farm is now using the new settings.
Web farm synchronization using URL notifications
Every Kentico instance contains a page that web farm servers can send HTTP requests to when generating web farm tasks. The other web farm servers don't get involved in the process until they are notified about the changes. When this happens, each server fetches its tasks and processes them accordingly. For this method to work, all servers in a web farm must be able to see each other.
Synchronization by request is not suitable for projects that are heavily edited. This is because a lot of tasks can be generated in a short time period, which means an excess traffic for the target servers and clearing of the cache too often (especially under heavy load). This method is recommended for projects with defined, static number of servers.
Synchronization by request is the default option on instances not running on Microsoft Azure.
To enable URL notifications synchronization mechanism:
1. 1. Navigate to Settings application -> Versioning & Synchronization -> Web farm. 2. Select the Update within request setting. 3. Configure web farm servers.
The synchronization by request mechanism uses the Server root URL value stored in the web farm server object.
Web farm synchronization using database notifications
With the database notifications mechanism (also called the database updater), the system uses the CMS_WebFarmServerTask database table to find tasks created for the current server. On the application side, a routine runs in a separate long running thread which continuously polls the database to find the tasks.
This mechanism is used on Azure by default and it does not require any configuration in this environment. The database updater is also the only supported option for automatically generated web farm servers. Use this mechanism in all environments where the number of web farm servers dynamically changes in time.
To enable the database updater mechanism:
1. Navigate to Settings application -> Versioning & Synchronization -> Web farm. 2. Select the Use web farm database updater setting. 3. Configure web farm servers.
Web farm synchronization using a scheduled task
Synchronizing web farm tasks using the scheduled task allows you to set the periodicity of the synchronization. This way, you can configure the system to process the web farm task in a batch, as opposed to synchronization by every request.
You can also set the scheduled task to run in a separate thread. By configuring the scheduler to run as an external Scheduler service, you can transfer the processing of web farm tasks outside of the website.
Synchronization using a scheduled task offers enhanced performance and wider possibilities of configuration at the cost of enabling the Scheduler service.
To use the scheduled task to process web farm tasks:
1. Make sure that the Update within request and Use web farm database updater settings in Settings -> Versioning & Synchronization -> Web farm are disabled. 2. Make sure that the Synchronize web farm changes scheduled task in Scheduled tasks application is enabled. 3. Configure web farm servers.
Modifying the synchronization interval
By default, the Synchronize web farm changes scheduled task is configured to run every minute. You can configure this interval to better suit the needs of your website:
1. Open the Scheduled tasks application. 2. Select (global) in the Site selector at the top of the page. 3. Edit the Synchronize web farm changes task. 4. Set the required task interval. 5. Make sure that the Task enabled check-box is selected. 6. Click Save.
Configuring web farm servers All web farm synchronization mechanisms, except for automatic configuration, require that all web farm servers are configured in the system. After you choose and enable a synchronization mechanism, start using web farm synchronization by performing the following steps:
1. Add web farm servers manually. OR Configure web farm servers automatically.
2. Enable web farm functionality. 3. [Optional] Perform further configurations.
Adding web farm servers manually
If you are running a web farm with a static number of web farm servers (regardless of the chosen synchronization mechanism), configure the web farm servers manually in your system.
1. Open the Web farm application. 2. Click New server. 3. Fill in the following fields: Server display name - a descriptive name for the server displayed in the administration interface. Server root URL - the URL of the root of the website on the server, such as http://192.168.1.2/Kentico. You can check the availability of the server by clicking Check server availability. Note that the URL must start with the protocol (http or https). Server enabled - allows you to manually enable or disable web farm synchronization for the particular server. 3.
4. Click Save to register the server. 5. Open the web.config file on the particular server and add the CMSWebFarmServerName key into the appSettings section:
Replace ServerCodeName with the server code name that the system created for the server (or the code name that you manually entered). Every server must contain only one such key with its own name.
Repeat the process for every server in your web farm.
Adding web farm license keys
Enter an appropriate license key for the internal URLs of all your web farm servers.
For example, if you use the web farm for domain name example.com and access the servers internally through URLs like:
http://192.168.1.2 http://192.168.1.3
Enter separate license keys for example.com, 192.168.1.2 and 192.168.1.3 in the Licenses application. You only need to add the licenses on one server and restart the other instances using the System application (click Restart application).
Configuring web farm servers automatically
If you are running a web farm with a dynamic number of web farm servers in a combination with the database updater synchronization mechanism, set your system to configure the web farm servers automatically.
This configuration is used on Azure projects by default.
1. Open the Settings application. 2. Select the Versioning & Synchronization -> Web farm category. 3. Enable the following settings: Generate servers dynamically Delete generated servers on application end
4. Click Save.
All servers with enabled web farm support add themselves into the list of servers when the application starts.
Enabling web farm functionality
After you define the web farm servers, enable web farm synchronization in the settings:
1. Open the Settings application. 2. Expand the Versioning & Synchronization -> Web farm category. 3. Check the Enable web farm setting. 4. Click Save.
You can perform additional low-level settings for web farm synchronization by adding the keys listed in Web.config file settings into the /confi guration/appSettings section of your web.config file.
Further configurations of web farm servers
Storing session state on a web farm
The default session state mode for ASP.NET applications is the InProc mode, which stores session state in the memory of the server. However, this mode is not supported on web farms, because requests for the same session can be served by different servers. This can cause unexpected behavior and data loss. For example, items stored in a shopping cart can disappear after making another request on the website.
To configure an Azure project to store session data, see Configuring an Azure project.
To configure your web farm to store session state data correctly, use one of the following modes: StateServer mode - stores session state in a separate process. SQLServer mode - stores session state in a SQL server database.
To use one of these modes, adjust the
Configuring servers for synchronizing macros
The system uses signatures to ensure the security of macro expressions. Macro signatures contain the user name of the macro's author and a hash of the given expression.
The hash function used to create the signatures appends a salt to the input. To ensure that macro expressions work correctly in a web farm environment, you need to configure all servers to use the same hash salt:
Set the CMSHashStringSalt key in the appSettings section of the web.config file to the same value on all web farm servers. For example:
The best option is to set the hash salt value before you start creating content for your website. Changing the salt causes all current hash values to become invalid. To fix existing macro expressions in the system after changing the hash salt, you need to re-sign the macros. See Working with macro signatures for more information.
SSL in a web farm environment
If you use an SSL offload device or accelerator as part of your web farm and your website is configured to require SSL for the administration interface or on specific pages, you may encounter problems with redirection loops.
For this type of scenario, you need to add some custom code to your website according to the instructions in SSL accelerator support.
Using port numbers to identify web farm servers
If your environment uses unique port numbers to identify web farm servers (for example with a load balancer that internally maps URLs to ports), the system generates certain types of URLs with the internal port number. Such URLs may not be processed correctly, leading to problems with related features (for example GetResource requests for files).
To resolve these problems, add the following key into the appSettings section of the web.config file on all servers:
The key ensures that the system generates all URLs without the port number (the default HTTP port is used).
Troubleshooting web farms Monitoring web farm synchronization tasks
You can monitor the web farm tasks in the Web farm application on the Tasks tab. The tab shows all synchronization tasks that are currently active (waiting to be processed).
In an ideal situation, this tab should not contain any tasks – this means that the web farm tasks are processed soon after they are created. The system automatically removes successfully processed tasks.
The Anonymous tasks tab displays a list of currently active (waiting to be processed) anonymous synchronization tasks. These tasks are logged by external applications (e.g. Windows services) to ensure that changes made by the external application are reflected in the web application cache. Tasks are logged as anonymous only if the application is NOT configured to run in a web farm. If it is configured to run in a web farm, these tasks are logged as standard synchronization tasks on the Tasks tab.
See also: Debugging web farms
Web farm tasks are not being processed
If the Tasks tab contains web farm tasks that fail to be processed, the cause can be one of the following:
No synchronization mechanism is enabled. Enable a synchronization mechanism.
The system is configured for more web farm servers than there really are. Check the Web farm application -> Servers tab and make sure that the number of configured web farm servers corresponds to reality. Delete excess servers or restart your application on servers that are missing from the list.
In case of the URL updater mechanism, the Server root URL settings are not configured properly. Check the Server root URL setting in Web farm -> Servers -> edit a server for each web farm server. In case of the database updater mechanism, the thread is not running. Check if the CMS.WebFarmSync.DbWebFarmUpdater thread is running in Debug -> Worker threads. See Debugging web farms for more information.
Servers contain licenses for domains with a different number of allowed web farm servers
When you enable web farm functionality on a Kentico instance, we recommend that you use only those website domains, for which you have licenses with the same number of web farm servers allowed. If you have a website which can be run on multiple servers, adding another website with fewer allowed web farm servers can cause "License web farm server count exceeded." errors.
These are the possible solutions for this problem:
Obtain additional licenses for your websites so that they can be run on the same number of web farm servers. Use completely separate infrastructures (different servers and databases) for each website.
Debugging web farms The system provides a debugging tool that shows the synchronization activity of web farm servers. Web farm debugging allows you to troubleshoot web-farm-related issues and find out if the synchronization works correctly.
Enabling the web farm debug
To use web farm debugging, open the Settings application and adjust the settings in the System -> Debug category:
Note: Web farm debugging is only functional if at least one web farm server is defined.
Setting Description
Enable web farm debug Enables web farm debugging and the Web farm tab in the interface of the Debug application.
Debug web farm operations of UI pages If enabled, the web farm debug includes operations performed via the administration interface. Web farm debugging must also be enabled.
Web farm debug log length Sets the maximum length of the web farm debug log, i.e. the number of requests for which the debug stores information. If empty, the value of the Default log length setting is used. Display stack information If enabled, the system tracks the code stack when debugging web farm tasks and displays the information in the Context column.
This information is only available in the debugging UI and on the live site, not in the debug log written into the logwebfarm.log file.
Log web farm operations to file If enabled, the system saves the web farm debug log into the logw ebfarm.log file in the ~/App_Data folder. This option does not require web farm debugging to be enabled.
Tip: You can also enable web farm debugging through the "debug everything" settings in the All section of the Debug settings category.
Viewing the web farm debug
To access the web farm debug, open the Debug application and select the Web farm tab.
The log displays the following information for the current web farm server:
Synchronization tasks created by the server for recent web requests Notifications sent to other web farm servers (NOTIFY Task type) Tasks processed as a result of notification requests from other servers in the web farm (DO: prefix in the Task type)
For example, when a web farm server handles a request that adds a new role object, the debug log shows:
The creation of a TOUCHCACHEITEM synchronization task (clears cached role objects) NOTIFY tasks for other servers in the web farm
On the target web farm servers, the debug shows the processing of the synchronization task:
To remove all records previously logged in the web farm debug, click Clear debug log.
Setting up search on your website Kentico provides an index-based search engine (Smart search), which allows users to search through the content of websites and various types of data within the system. The smart search is based on Lucene.Net (version 3.0.3) — a source code, class-per-class, API-per-API port of the Java Lucene search engine to C# and the .NET platform.
The smart search uses indexes to store information about the website content. When a user sends a search request, the system searches through the appropriate indexes, which results in significantly better performance compared to linear SQL query search.
To set up the smart search functionality on your website, you need to perform the following steps:
1. Enable smart search indexing in the system. 2. Create search indexes. Assign the indexes to your site and define their exact content. 3. Add smart search web parts onto the pages of your website. To learn more about the web parts, see Adding search functionality to pages and Using search filters. How the smart search works
The system stores the content of smart search indexes in physical index files on the server's disk. The index files are located in the ~/App_ Data/CMSModules/SmartSearch/
Pages, forums and other Kentico objects are reflected in the index file as index pages. The data structure of the index pages is suitable for being searched, resulting in significantly higher search performance compared to linear SQL search.
The index pages contain the same fields as the corresponding Kentico objects, based on the search settings of individual object types. Depending on these settings, the Index writer creates representations of objects in the index files. When an object included in the index is created, removed or has one of its fields modified, the system automatically schedules an Indexing task, which updates the corresponding index page. The Index searcher searches through the index file and returns relevant results.
Tip
You can find a list of all indexing tasks that are waiting to be processed in Smart search -> Tasks. Here you can:
Look for information if you encounter problems with new content not being indexed correctly Delete ( ) tasks from the indexing queue to stop unnecessary or problematic indexing
See also: Monitoring search indexing tasks
Example
The following model scenario explains the life cycle of a page in a search index file:
1. A user creates a new page. 2. Upon the page's creation, the system logs a new indexing task in the database. 3. The Smart search either runs the indexing task immediately or processes it later using a scheduled task. 4. When executed, the indexing task adds the new page to the appropriate search indexes. The system indexes the page's content based on the search field settings defined for the given page type. 5. A user arrives on the website and sends a search request via a Smart search web part. 6. The web part searches through the assigned indexes and returns results based on the found data.
Enabling search indexing To enable Smart search indexing for all websites in the system:
1. Open the Settings application. 2. Select the System -> Search category. 3. Check Enable smart search indexing. 4. Click Save.
Note: Your application must have the write permission for the ~/App_Data folder on the server's file system. This folder stores the search index files, so the system cannot create and update indexes without the required permissions.
See Disk permission problems to learn how to grant the write permission for the folder.
Scheduling the search indexing process
By default, the smart search creates and executes indexing tasks immediately whenever content covered by a search index is created, modified or deleted.
You can disable automatic running of indexing tasks upon creation by adding the CMSProcessSearchTasksByScheduler key to the /config uration/appSettings section of your application's web.config file:
When you set this key to true:
The system only logs the search indexing tasks into the database without running them. You need to process the tasks periodically, for example using the Execute search tasks scheduled task (runs every 4 hours by default). You cannot manually Rebuild indexes unless you also run the process that executes the indexing tasks.
Tip
You can find a list of all indexing tasks that are waiting to be processed in Smart search -> Tasks. Here you can:
Look for information if you encounter problems with new content not being indexed correctly Delete ( ) tasks from the indexing queue to stop unnecessary or problematic indexing See also: Monitoring search indexing tasks
Creating search indexes Indexes are the core of the smart search functionality. They store information about the searchable content and define the scope of searches. When a visitor submits a search request, the system looks through the appropriate indexes instead of the actual records in the database. Indexes organize data in a way that is suitable for searching, so the smart search retrieves results faster than linear searches, particularly for large volumes of data.
The following types of search indexes are available:
Index type Description
Pages Stores information about pages in the content tree
Pages crawler Directly indexes the HTML output of pages.
Forums Stores information about the content of discussion forums.
Custom tables Indexes records stored in custom tables.
On-line forms Indexes data that the website's visitors submit through forms.
Users Stores information about users in the system.
General Stores information about system objects of a specified type.
Custom Allows you to use your own customcoded search index. Stores any kind of data depending on the implementation.
Before you can start searching content, you need to create search indexes for your website:
1. Open the Smart search application. 2. Click New index. 3. Fill in the index properties. Most importantly, you need to select the: Index type - determines what type of content the search index stores Analyzer type - determines how the index breaks text into searchable tokens
4. Click Save to create the search index. The General tab of the index's editing interface opens. Here you can edit the same properties that you configured when creating the index.
5. Open the Sites tab and select the websites where you wish to use the index. You can implement multi-site search functionality by assigning the index to more than one website.
Note: If the index includes global objects that are not site-specific, the selection made on the Sites tab does not affect the index's content. However, you can only use the index (through Smart search web parts) on the assigned sites. 5.
6. If you are creating a Pages or Pages crawler type index, switch to the Cultures tab. Here you need to select which language versions of the website's pages are indexed. You must assign at least one culture in order for the index to be functional. If you have a multi-site index, you can select the cultures separately for each site.
7. Switch to the Indexed content tab and define the content covered by the index. The available options depend on the type of the index:
Defining page indexes Defining forum indexes Defining custom table indexes Defining on-line form indexes Defining user indexes Defining general indexes Creating custom smart search indexes
8. Go back to the General tab and Rebuild the index. The Index info section displays information about the current status and parameters of the index.
Once the system finishes building the index, you can start using the index on your website.
The Search preview tab allows you to test the functionality of the index.
Maintaining search indexes
You can manage existing search indexes using the actions available on the General tab of the index editing interface.
The system automatically updates search indexes to reflect all changes made to the indexed content. Over time, these updates can make indexes less efficient, particularly in the case of large indexes.
To restore optimal search performance for an index, defragment the index by clicking Optimize. You can enable the Optimize search indexes scheduled task to have the system automatically optimize all smart search indexes once per week.
The Rebuild action deletes the current index file and indexes all specified content again.
Use the rebuild action to apply changes made to the index's configuration. This includes modifications of the analyzer settings (Analy zer type, Stop words), all options on the Indexed content, Sites or Cultures tabs, and adjustments of the search field settings for the indexed objects. The system automatically optimizes the index after a successful rebuild.
Clicking the Rebuild action does not always guarantee that the index starts rebuilding immediately. The process may be delayed if another index is already being rebuilt or if the rebuilding tasks are configured to be handled by the scheduler.
Reference - Search index properties
You can configure the following options when creating new search indexes or editing existing indexes on the General tab:
Index property Description
Display name Name of the index displayed in the administration interface. Code name Serves as a unique identifier for the index (used internally in web part property values or the API). You can leave the default (automa tic) option to have the system generate a code name based on the display name.
Warning: The system also uses the code name for the physical index file. The fully qualified name of the file must be less than 260 characters long, including the directory path.
Index type Determines what type of content the search index stores:
Custom index - indexes any kind of data depending on the implementation. Custom tables - indexes records in custom tables. Pages - indexes the content of the pages in the content tree Pages crawler - indexes the HTML output of the website's pages. Forums - indexes the content of forums. General - indexes system objects of a specified type. General indexes allow you to search through any objects within the system. On-line forms - indexes data submitted by the website's visitors through forms. Users - indexes the data of users in the system.
Analyzer type Sets the type of analyzer that the index uses to tokenize text ______(divide text into searchable tokens). The analyzer processes both the indexed content and the search expressions entered by users. When running searches using the index, the system returns results for items that have at least one token matching the search expression.
The following analyzers are available:
Simple - divides text at non-letter characters (including numbers). Stop - divides text at non-letter characters (including numbers) and excludes all words in the selected Stop words dictionary. White space - divides text at whitespace characters. Standard - divides text based on language grammar (uses stop words, shortcuts, ...). Very efficient for English, but may not produce satisfactory results with other languages. Keyword - returns the entire text stream of indexed data fields as a single token. Useful for structured data fields like zip codes or IDs. Custom - allows you to assign a customwritten analyzer. This provides a way to perform text tokenization according to your own requirements. You need to specify the names of the assembly and class where the custom analyzer is implemented. See Creating custom smart search analyzers for more information. Subset - creates tokens for all possible substrings in words. Indexes with subset analyzers return results for all words that contain the search term. For example, searching for net match es words such as net, Internet, network, kinetic, etc. Starts with - creates tokens for all prefixes contained in words, including the whole word. Allows searching for all words that start with the search term. For example, searching for test matches words such as test, tests, tester, etc. Simple / Stop words / White space with stemming - divide text using the Simple, Stop or White space analyzer, and then reduce the tokens to word stems. Allows users to find words that have the same basic meaning as the search term, but different inflection (suffixes). Only works for English.
See also: Configuring search assistance features
Stop words Selects the stop word dictionary for Stop or Standard analyzers.
Stop words (such as 'and', 'or') are excluded from the index content and the analyzer uses them to divide text into tokens.
You can edit the content of the dictionaries or add new ones. The application stores the dictionaries as text files in the ~\App_Data\C MSModules\SmartSearch\_StopWords folder. Batch size Sets the maximum amount of records that the system retrieves in a single database query when rebuilding (or creating) the index. This property allows you to optimize indexing performance.
The default value is 10. Increasing the value reduces the amount of queries required for large numbers of records, which may improve performance, but also increases memory consumption.
The optimal value depends on the type (size) of the indexed objects and on the resources available in your hosting environment. When indexing large objects (e.g. pages), it is recommended to set a reasonably small batch size.
Crawler settings
When editing Pages crawler type indexes, you can configure the user account and domain name that the crawler uses to read pages:
Index property Description
User Sets the user account that the crawler uses to index pages. ______Reading pages under a user allows the crawler to:
Load user-personalized content for the given user Avoid indexing of pages that the user is not allowed to access
If empty, the index uses the default administrator user account.
On websites that use Windows authentication, you need to type the user name (including the Active Directory domain in format domain \username) and password.
Domain Sets the domain that the crawler uses when indexing sites. Enter the domain name without the protocol, for example: www.domain.c om
If empty, the crawler automatically uses the main domain of the site where the indexed pages belong.
For example, you can set a custom domain for web farm servers th at do not have access to the main domain.
Defining page indexes You can use two types of search indexes for the pages of websites (i.e. pages in the content tree):
Pages Index the following page data:
The content of text web parts placed on pages (Editable text, Static text and similar) Page metadata Selected fields of individual page types (see Configuring search settings for page fields)
Note: Pages indexes do NOT include the text of other pages or objects displayed through web parts (such as the content of News page displayed through a Repeater web part).
Pages crawler Directly parse the HTML output generated by pages, which allows the search to find any text located on pages. Crawler indexes provide more accurate searches of page content than standard Pa ges indexes. However, building and updating crawler indexes may require more time and resources, particularly in the case of large indexes and complex pages.
See also: Configuring page crawler indexes
To define which pages an index covers, specify allowed or excluded content:
1. Open the Smart search application. 2. Edit ( ) the index. 3. Select the Indexed content tab. 4. Click Add allowed content or Add excluded content. 5. Open the Sites tab and assign the websites where you wish to use the index. 6. Switch to the Cultures tab and select which language versions of the website's pages are indexed. You must assign at least one culture in order for the index to be functional. If you have a multi-site index, you can select the cultures separately for each site.
Adding allowed content
Allowed content defines which of the website's pages are included in the index. Specify pages using a combination of the following options:
Path - path expression identifying the pages that should be indexed. Page types - allows you to limit which page types are included in the index.
The following properties define types of additional content that you can include in Page search indexes. The settings are not available for Pa ges crawler indexes:
Include ad-hoc forums - includes the content of ad-hoc forums placed on the specified pages (if there are any). Include blog comments - includes blog comments posted for blog post pages. Include message boards - includes message boards placed on the specified pages.
Include attachment content - if checked, the index includes the text content of files attached to the specified pages. See Searching attachment files for more information. Include categories - if checked, the index stores the display names of Categories assigned to the specified pages. This allows users to find pages that belong to categories whose name matches the search expression.
Examples
Allowed content settings Result
Path: /% Indexes all pages on the site. Page types: empty
Path: /Partners Only indexes the /Partners page, without the child pages placed Page types: empty under it.
Path: empty Indexes all pages of the CMS.News page type on the entire site. Page types: CMS.News In this case, an empty path field value is equal the /% expression.
Path: /Products/% Indexes all pages of the CMS.Smartphone and CMS.Laptop page Page types: CMS.Smartphone;CMS.Laptop types found under the /Products section.
Adding excluded content
Excluded content allows you to remove pages or entire website sections from the allowed content. For example, if you allow /% and exclude / Specialpages/% at the same time, the index will include all pages on the site except for the ones found under the /Special-pages node.
You can specify the following options:
Path - path expression identifying the pages that should be excluded. Page types - allows you to limit which page types are excluded from the index.
Examples
Excluded content settings Result
Path: /Partners Excludes the /Partners page from the index. Child pages are not Page types: empty excluded.
Path: empty Excludes all pages of the CMS.News page type from the index. Page types: CMS.News In this case, an empty path field value is equal the /% expression.
Path: /Products/% Excludes all pages of the CMS.Smartphone and CMS.Laptop page Page types: CMS.Smartphone;CMS.Laptop types found under the /Products section from the index. Excluding individual pages from all indexes
You can also exclude specific pages from all smart search indexing:
1. Open the Pages application. 2. Select the given page in the content tree. 3. In Edit mode, open the Properties -> Navigation tab. 4. Enable the Exclude from search property. 5. Click Save.
Configuring search settings for page fields
Pages are often complex data structures with many different fields. Not all fields may be relevant to the search that you are implementing. Pa ge types allow you to adjust how the system indexes specific fields. We recommend indexing only necessary fields to keep your indexes as small (and fast) as possible.
Pages crawler search indexes directly index the HTML output of pages. As a result, crawler indexes are not affected by the field settings of page types.
To edit the field search settings for page types:
1. Open the Page types application. 2. Edit ( ) a page type. 3. Open the Search fields tab.
In the top part of the tab, configure how the system displays pages of the given type in search results:
Title field - select the page field whose value is used for the title of search results. Content field - the field whose value is used for the content extract of search results. Image field - the field that contains the image displayed next to search results. Date field - the field whose value is used for the date and time displayed in search results.
The table in the bottom section of the tab determines how the smart search indexes the page type's fields (as defined on the Fields tab). You can set the following search options for individual fields:
Content If checked, the content of the field is indexed and searchable in the standard way.
Searchable If checked, the content of the field can be searched using expressions in format:
See Smart search syntax for more information about field searches. This option must also be enabled for the field to be usable in Search filters.
Tokenized Indicates if the content of the field is processed by the analyzer when indexing. This allows the search to find results that match individual tokens (subsets) of the field's value. If disabled, the search only returns items if the full value of the field exactly matches the search expression.
The general rule is to enable tokenization for Content fields and not for Searchable fields.
Custom search name Relevant for Searchable fields. The specified value is used as a substitute for the field code name in
Note: If you enter a Custom search name value, the original field code name can't be used.
After you Save changes of the field settings, you need to Rebuild all indexes that cover pages of the given type.
When running searches using page indexes, the system returns results according to the field search settings of individual page types. The page type search settings are shared by all page indexes in the system. SKU (product) and general page fields
To configure the field search settings for E-commerce SKUs (products):
Warning: It is highly recommended to modify only the settings of custom SKU fields. Changing the settings of the default fields may prevent the system from searching through SKUs correctly.
1. Open the Modules application. 2. Edit ( ) the E-commerce module. 3. Open the Classes tab. 4. Edit the SKU class. 5. Select the Search tab. 6. Click Customize.
You can configure the search settings for fields just like for page types. The SKU fields are joined together with general page fields, such as fields that store the content of editable regions on pages (DocumentContent) or the content of text widgets (DocumentWebParts).
Important: The search settings of general fields affect all pages, even those that are not products.
Configuring page crawler indexes
Page crawler search indexes read the content of pages while logged in under a user account. You can configure the following properties for every page crawler index (on the General tab of the index editing interface):
Index property Description User Sets the user account that the crawler uses to index pages. ______Reading pages under a user allows the crawler to:
Load user-personalized content for the given user Avoid indexing of pages that the user is not allowed to access
If empty, the index uses the default administrator user account.
On websites that use Windows authentication, you need to type the user name (including the Active Directory domain in format domain \username) and password.
Domain Sets the domain that the crawler uses when indexing sites. Enter the domain name without the protocol, for example: www.domain.c om
If empty, the crawler automatically uses the main domain of the site where the indexed pages belong.
For example, you can set a custom domain for web farm servers th at do not have access to the main domain.
Note: Page crawlers only index the content of pages that are published on the live site.
By default, page crawlers also index pages that use redirection from the site's main domain name to a domain alias. To only allow indexing for pages that use the website's main domain, set the CMSCrawlerAllowSiteAliasRedirect key to false in your application's web.config file:
The key applies to all page crawler indexes in the system.
Customizing how crawlers process page content (API)
By default, the system converts the HTML output of pages to plain text before saving it to page crawler indexes:
Strips all HTML tags Removes the Head tag, Style tags and all JavaScript Converts all whitespace formatting to simple spaces
If you wish to index the content of any tags or exclude parts of the page output, you can customize how the crawlers process the HTML. You need to implement your custom functionality in a handler of the OnHtmlToPlainText event of the CMS.Search.SearchCrawler class. This event occurs whenever a page search crawler processes the HTML output of a page.
To assign a method as the handler for the OnHTMLToPlainText event, add a new class to the App_Code folder of your web project (or CMS App_AppCode -> Old_App_Code on web application installations). For example, you can define the content of the class as shown below: using System; using System.Web;
using CMS.Base; using CMS.Search; using CMS.Helpers;
[DocumentCrawlerContentLoader] public partial class CMSModuleLoader { ///
// Add your custom HTML processing actions and return the result as a string static string SearchHelper_OnHtmlToPlainText(string plainText, string originalHtml) { string outputResult = originalHtml;
// Removes new line entities outputResult = outputResult.Replace("\n", " ");
// Removes tab spaces outputResult = outputResult.Replace("\t", " ");
// Removes JavaScript outputResult = HTMLHelper.RegexHtmlToTextScript.Replace(outputResult, " ");
// Removes tags outputResult = HTMLHelper.RegexHtmlToTextTags.Replace(outputResult, " ");
// Decodes HTML entities outputResult = HttpUtility.HtmlDecode(outputResult);
return outputResult; }
} }
The OnHTMLToPlainText event provides the following string parameters to the handler:
plainText - the page output already stripped of all tags and converted to plain text originalHTML - the raw page HTML code without any modifications
Defining forum indexes When editing forum indexes on the Indexed content tab in the Smart search application, select which Forums the search index covers. You need to define allowed or excluded forums.
Adding allowed forums
1. Click Add allowed forums. 2. Use the Site name selector to choose the site whose forums you wish to index. If you select (all), all forums on all sites in the system will be indexed. Only websites assigned to the index on the Sites tab are available for selection.
3. If you selected a site in the previous step, click Select next to the Forums field. 4. Use the Forum group drop-down to select a forum group. The dialog lists the selected group's child forums. 5. To include a forum in the index, select the appropriate check boxes and click Select.
Alternatively, you can manually enter the code names of forums into the Forums field, separated by semicolons. All forums on the selected site can be added to the index this way, including group forums. The asterisk character (*) can be used as a wildcard for any number of characters. For example, entering *community* adds all forums that contain the string community in their code name to the index.
Adding excluded forums
You can exclude individual forums if you have all forums allowed for an index.
To exclude a forum, click Add excluded forums on the Indexed content tab. The procedure is the same as when adding allowed forums.
Defining custom table indexes When editing custom table indexs on the Indexed content tab in the Smart search application, you can see a list of custom tables included in the index. To add custom tables to the index, click Add custom table. You can also Edit ( ) the way listed custom tables are indexed or Delete ( ) them from the list.
When adding a new custom table to the index or editing an existing one, you have the following options:
Custom table - selects which custom table is indexed. Where condition - sets the WHERE clause of the queries that the system uses to load data from the custom table when building the index. Allows you to limit which records (rows) are included in the search index.
Note: You need to Rebuild the index on the General tab in order for changes to take effect.
Configuring search settings for custom table fields
Each custom table has a different set of fields and stores different types of data. You can configure exactly how the system searches through the fields of individual tables and how the data appears in the search results. We recommend indexing only necessary fields to keep your indexes as small (and fast) as possible. To edit the field search settings for custom tables:
1. Open the Custom tables application. 2. Edit ( ) a custom table. 3. Select the Search fields tab.
In the top part of the tab, configure how the system displays records from the custom table in search results:
Title field - select the custom table field whose value is used for the title of search results. Content field - the field whose value is used for the content extract of search results. Image field - the field that contains the image displayed next to search results. Date field - the field whose value is used for the date and time displayed in search results.
The table in the bottom section of the tab determines how the smart search indexes the custom table's fields (as defined on the Fields tab). You can set the following options for individual fields:
Content If checked, the content of the field is indexed and searchable in the standard way.
Searchable If checked, the content of the field can be searched using expressions in format:
See Smart search syntax for more information about field searches. This option must also be enabled for the field to be usable in Search filters.
Tokenized Indicates if the content of the field is processed by the analyzer when indexing. This allows the search to find results that match individual tokens (subsets) of the field's value. If disabled, the search only returns items if the full value of the field exactly matches the search expression.
The general rule is to enable tokenization for Content fields and not for Searchable fields.
Custom search name Relevant for Searchable fields. The specified value is used as a substitute for the field code name in
Note: If you enter a Custom search name value, the original field code name can't be used.
After you Save changes of the field settings, you need to Rebuild all indexes that include the given custom table.
When running searches using custom table indexes, the system returns results according to the field search settings of individual tables. The field search settings are shared by all custom table indexes in the system.
Defining on-line form indexes On-line form indexes allow you to search through the data that website visitors submit through forms.
Adding forms to indexes
After you create an on-line form index in the Smart search application, define which forms the index includes:
1. Assign the index to one or more websites on the Sites tab of the index editing interface. 2. Open the Indexed content tab and click Add on-line form.
a. Select the Site that contains the required form (if the index is assigned to multiple websites). b. Select the On-line form. c. (Optional) Set a Where condition for the queries that the system uses to load the form's data when building the index. Allows you to limit which form records are included in the search index. d. Click Save.
You can add any number of forms to a single on-line form index.
3. Switch to the General tab and Rebuild the index.
You can now assign the index to Smart search web parts and search through the data of forms.
Configuring search settings for form fields
Each form has a different set of fields and stores different types of data. You can configure exactly how the system searches through the fields of individual forms and how the form data appears in the search results. We recommend indexing only necessary fields to keep your indexes as small (and fast) as possible.
1. Open the Forms application. 2. Edit ( ) the form that you want to configure. 3. Open the Search fields tab. 4. Make sure that the Search is enabled box is checked. 5. Specify how the system displays the form's records in search results:
Title field - select the form field whose value is used for the title of search results. Content field - the field whose value is used for the content extract of search results. Image field - the field that contains the image displayed next to search results. Date field - the field whose value is used for the date and time displayed in search results.
6. Configure how the smart search indexes the form's fields. You can set the following options for individual fields:
Content If checked, the content of the field is indexed and searchable in the standard way.
Searchable If checked, the content of the field can be searched using expressions in format:
See Smart search syntax for more information about field searches. This option must also be enabled for the field to be usable in Search filters.
Tokenized Indicates if the content of the field is processed by the analyzer when indexing. This allows the search to find results that match individual tokens (subsets) of the field's value. If disabled, the search only returns items if the full value of the field exactly matches the search expression.
The general rule is to enable tokenization for Content fields a nd not for Searchable fields.
Custom search name Relevant for Searchable fields. The specified value is used as a substitute for the field code name in
Note: If you enter a Custom search name value, the original field code name can't be used.
7. Click Save. 8. Rebuild all indexes that contain the given form.
When running searches using on-line form indexes, the system returns results according to the field search settings of individual forms.
Defining user indexes When editing user indexes on the Indexed content tab in the Smart search application, you can limit which users are indexed. The tab allows you to set the following limitations for user indexes:
Include hidden users - if enabled, hidden users will be indexed. Enabled users only - if enabled, only enabled users will be indexed. Index users from all sites - if enabled, users from all sites will be indexed. If disabled, only users from the sites assigned on the Sit es tab will be indexed. Users in roles - if entered, only users from the entered roles will be indexed. Users not in roles - if entered, only users who are not in the entered roles will be indexed. Where condition - sets the WHERE clause of the queries that the search runs against the View_CMS_User view when building the index. Allows you to create custom conditions for limiting which users are indexed.
Configuring search settings for user fields
You can configure exactly how the system searches through the data fields of user objects, and how the information appears in the search results. We recommend indexing only necessary fields to keep your indexes as small (and fast) as possible.
To edit the field search settings for users:
1. Open the Modules application. 2. Edit ( ) the Membership module. 3. Open the Classes tab. 4. Edit the User class. 5. Select the Search tab. 6. Click Customize.
In the top part of the tab, configure how the system displays users in search results:
Title field - select the field whose value is used for the title of search results. Content field - the field whose value is used for the content extract of search results. Date field - the field whose value is used for the date and time displayed in search results.
Note: You cannot change the image field for users. The search results display Avatar images.
The table in the bottom section of the tab determines how the smart search indexes the user fields. The list contains fields from both the User and User - Settings classes. You can set the following options for individual fields:
Content If checked, the content of the field is indexed and searchable in the standard way.
Searchable If checked, the content of the field can be searched using expressions in format:
See Smart search syntax for more information about field searches. This option must also be enabled for the field to be usable in Search filters.
Tokenized Indicates if the content of the field is processed by the analyzer when indexing. This allows the search to find results that match individual tokens (subsets) of the field's value. If disabled, the search only returns items if the full value of the field exactly matches the search expression.
The general rule is to enable tokenization for Content fields and not for Searchable fields.
Custom search name Relevant for Searchable fields. The specified value is used as a substitute for the field code name in
Note: If you enter a Custom search name value, the original field code name can't be used.
After you Save changes of the field settings, you need to Rebuild all user indexes. The field search settings are shared by all user indexes in the system.
Defining general indexes General indexes allow searching through any type of objects used within the system. This includes items you may recognize from the administration interface, such as web parts, page templates, groups, sites etc.
When editing general indexes in the Smart search application, specify the content on the Indexed content tab by defining the following properties:
Object name - sets the type of objects searched by the index. The index stores information representing objects in the system of the specified type. When an object is created, removed or has one of its fields modified, the index automatically updates to reflect the changes. Where condition - sets a custom WHERE clause for the queries that retrieve data when building the index. Allows you to limit which records are included in the index.
After you select the object type, you need to configure which fields the index includes. Switch to the Search fields tab.
In the top part of the tab, configure how the system displays objects of the given type in search results:
Title field - select the object field whose value is used for the title of search results. Content field - the field whose value is used for the content extract of search results. Image field - the field that contains the image displayed next to search results. Date field - the field whose value is used for the data and time displayed in search results.
The table in the bottom section of the tab determines how the smart search indexes the object type's fields. These fields correspond with the columns of the database table that stores objects of the given type. You can set the following options for individual fields:
Content If checked, the content of the field is indexed and searchable in the standard way.
Searchable If checked, the content of the field can be searched using expressions in format:
See Smart search syntax for more information about field searches. This option must also be enabled for the field to be usable in Search filters.
Tokenized Indicates if the content of the field is processed by the analyzer when indexing. This allows the search to find results that match individual tokens (subsets) of the field's value. If disabled, the search only returns items if the full value of the field exactly matches the search expression.
The general rule is to enable tokenization for Content fields and not for Searchable fields.
Custom search name Relevant for Searchable fields. The specified value is used as a substitute for the field code name in
Note: If you enter a Custom search name value, the original field code name can't be used. The configuration of search fields is global for objects of the given type. If you have multiple general indexes for one object type (i.e. using the same Object name), changing the search field settings for one index also affects the others.
Click Set automatically to use the default search field configuration for the object type. Confirm changes by clicking Save.
General indexes and Sites
The content of general indexes is not affected by the selection made on the Sites tab. It only determines on which websites the index will be available for use (through smart search web parts).
If you wish to configure a general index to search only through objects assigned to a specific site, we recommend using the Where condition property on the Indexed content tab. For example, a general index with the Group Object name and GroupSiteID = 3 s et in its Where condition only indexes groups created under the site with a SiteID equal to 3. This approach is only possible for site-bound object types.
Monitoring search indexing tasks To view a list of all search indexing tasks that are waiting to be processed, open the Smart search application and select the Tasks tab. Indexing tasks keep smart search indexes up-to-date according to changes made to the website content.
The system automatically creates indexing tasks when:
A page or object covered by a search index is created, removed or has one of its fields modified An administrator Rebuilds or Optimizes a search index
If you encounter problems with new content not being indexed correctly, you can use the list of indexing tasks to investigate the issue. The list displays the following information for each indexing task:
Task type - the action that the task will perform with the data of the search index (Update, Delete, Rebuild, Optimize, Process) Object type - the type of object for which the task was created Search field - the index field used to find the correct data item inside the search index (_id in most cases) Task value - identifies the object related to the indexing task (through an ID or code name) Related object - the name of the specific object related to the indexing task Web farm server Task created - the date and time when the system created the indexing task Result - if an error occurs while processing the indexing task, you can view the error message details here
To clear the indexing queue or stop unnecessary indexing, Delete ( ) individual tasks.
Dealing with task errors
If an indexing task results in an error, the system stops processing subsequent search tasks. Once you resolve the error or delete ( ) the problematic task, you can run any remaining search tasks by clicking Process tasks above the list.
By default, the system executes indexing tasks immediately when they are created. The list of indexing tasks is usually empty unless there is a long-running rebuild task, or the application is generating a very large number of indexing tasks. You can disable automatic running of indexing tasks by adding the CMSProcessSearchTasksByScheduler key to the /configuration/appSettings section of your application's web.config file:
With the key set to true, the system creates search indexing tasks, but does not run them. In this case, you need to regularly process the indexing tasks using the Execute search tasks scheduled task. You cannot manually Process tasks when the key is enabled.
Adding search functionality to pages Kentico provides a set of smart search web parts that you can use to build a search interface on the pages of your website. Only the most important web part properties are mentioned here. For a complete list and explanations of the web part properties, click the help icon in the top right corner of the web part properties window.
You can find the smart search web parts in the Full-text search -> Smart search category.
Smart search dialog with results
The Smart search dialog with results is an all-in-one web part that:
Allows users to search Displays the results
The following properties are the most important for setting up the smart search:
Property name Description
Indexes Determines which index the search uses. You can select multiple search indexes. Transformation name Name of the transformation that displays the search results.
There are two default transformations suitable for this purpose:
CMS.Root.SmartSearchResults CMS.Root.SmartSearchResultsWithImages
Search options Sets the level of syntax that is allowed in search expressions:
Basic - users are allowed to input special syntax, but cannot search specific fields. None - users can only enter text, everything is processed as a part of the search expression. Full - all search options can be used, including field searching.
See: Smart search syntax
Search condition Sets a condition that is added to any submitted search expressions. The condition is built using the smart search syntax, i.e. special symbols (+ -) and field conditions.
For example: +articleid:[(int)25 TO (int)150]
Search results order Defines the order in which search results are displayed.
You can specify one or more search fields (separated by commas) according to which the results will be sorted. Use the ##SCORE## macro to order results by their score (relevance). The default order is ascending — you can reverse the order by adding the DESC keyword (e.g. articleid DESC).
If you encounter the "Field
Smart search dialog
The Smart search dialog allows visitors to submit search requests and select the Search mode.
You need to place the dialog on a page together with the Smart search results web part. The combined functionality of the two web parts is nearly identical to the Smart search dialog with results. Using separate web parts allows you to place the dialog and results into different locations on the page.
If you enable the dialog's Show only search button property, the web part only displays the submit button without the search textbox and mode selector. This functionality is intended for scenarios that utilize Smart search filters to specify all of the search parameters. You can add the textbox separately from the search button by connecting a Smart search filter web part in textbox mode.
Smart search box
The Smart search box allows visitors to submit search requests. The search box is useful for pages that have limited space and are not primarily dedicated to searching. For example, you can add a search box to your website's main header. The web part handles search requests by redirecting users to a different page, where the Smart search results or Smart search dialog with results web part displays the results.
You can configure the Smart search box to display results instantly while users type the search text. See Setting up predictive search for more information.
Smart search results
The Smart search results web part displays the results of search requests sent from Smart search box or Smart search dialog web parts.
To connect the search box or dialog to the search results: Search dialog - place the dialog on the same page as the search results, copy the Web part control ID of the search results web part into the dialog's Result webpart ID property. Search box - enter the relative URL of the page containing the search results into the search box web part's Search results page URL property.
You can configure the Smart search results using the properties described for the Smart search dialog with results.
Smart search filter
The Smart search filter web part allows users to set parameters that affect the scope of the search or the order of the displayed results. You can also use the search filter to add a separate search textbox to pages.
See Using search filters for more information.
Setting up predictive search Predictive search displays results immediately while users type search expressions. Seeing the results before submitting the search allows users to:
Find out if the entered keywords are relevant Quickly navigate to results without going through a dedicated search page
The predictive search functionality is implemented into the Smart search box web part. When a user stops typing in the search box for 0.5 seconds, the web part runs a search request for the current text. The predictive search finds results using a set of assigned search indexes. A list of the top results appears directly below the search box. Users can open links to the relevant pages by selecting individual results of the predictive search.
Enabling predictive search
To turn on predictive search for a Smart search box:
1. Open the Pages application. 2. Edit the page containing your Smart search box on the Design tab. 3. Configure the Smart search box web part (double-click). 4. Check the Enable predictive search property. 5. Assign one or more search indexes through the Indexes property (in the Predictive settings category).
Note
The predictive search can use different indexes than the standard search. The functionality of the main search is always determined by the indexes assigned to the Smart search results web part on the target search results page.
You need to rebuild all search indexes that you plan to use for the predictive search after upgrading to Kentico version 8.
6. Click OK.
The search box now displays predictive results when users type search expressions. You can customize the appearance or behavior of the predictive search.
Using the predictive search
When entering text into a search box with predictive search enabled, the results appear shortly after you stop typing. By default, the predictive search separates results into groups. The groups represent the indexes where the search found matching results.
You can navigate directly to the pages linked by individual results of the predictive search:
Click the results in the list
OR
Move between results using the up/down arrow keys, and link to the selected item by pressing Enter
Alternatively, you can submit the search request and view the results page like with a standard search box.
Customizing the predictive search
To adjust the basic behavior of the predictive search, configure the properties of the Smart search box web part:
Min. characters (Predictive settings category) - sets the minimum number of characters that users need to type into the search box to trigger the predictive search. Max. results (Predictive settings category) - sets the maximum number of search results that the predictive search displays. Enable arrow key selection (Predictive results category) - if enabled, users can move between the predictive search results using the up and down arrow keys, and link to the selected result by pressing Enter.
Additionally, you can configure the predictive search just like standard smart search web parts:
Set the Search mode Add conditions to the search (Search condition) Determine the order of the results (Search sort) Set page filtering options
Predictive result groups
Groups help organize the search results if the predictive search uses multiple indexes. The default groups separate the results into sections with captions that match the Display name of the related search index.
To disable the default grouping, uncheck the Group results by index property of the Smart search box web part (in the Predictive results cat egory). It is recommended to disable grouping if your predictive search only uses one search index.
Result content and appearance
Modify the design of the predictive search results through the properties in the Predictive results category of the Smart search box web part.
The content of individual results is determined by the transformation assigned in the Search result transformation property. To allow users to open links for selected search results, include one element with a properly defined href attribute in the transformation code. The URL automatically opens when users select one of the predictive search results using the up/down arrow keys and press Enter.
You can change the following special result items by entering custom HTML content:
More results content - placed after the last search result if the maximum number of predictive results is reached. Use the {0} forma tting expression to get the URL of the full search result page assigned to the search box. No results content - displayed when the predictive search does not find any results.
To define CSS styles for the predictive search, edit:
the website's main CSS stylesheet OR the component CSS of the Smart search box web part (the default styles are here)
To change the names of the default CSS classes applied to the results, set the following properties of the Smart search box web part (in the Predictive results category):
Predictive results CSS class - specifies the name of the CSS class assigned to the block element that contains the predictive search results. Selected result CSS class - specifies the name of the CSS class applied to the element containing the selected predictive search result.
Tracking predictive search requests
You can enable or disable tracking for the predictive search through the properties in the Predictive tracking category of the Smart search box web part:
Log internal search activity - if enabled, the system logs every predictive search request as an Internal search on-line marketing activity. Track web analytics search keywords - if enabled, the site's web analytics log all text submitted to the predictive search as part of the On-site search keywords statistic.
Note: Tracking of predictive search requests may generate a large volume of irrelevant data (activities, keywords). The frequency of the search requests depends on the typing patterns of your website's visitors. Keywords often include incomplete words or fragments.
Example - Customizing the design of predictive search results
The following example shows how to change the appearance of highlighted results in the predictive search on the sample Corporate site. The customization also inserts the name of the related search index directly into individual result items (instead of using categories).
Configuring the Smart search box web part
1. Open the Pages application for the sample Corporate site. 2. Select the website root page in the content tree (Corporate Site). 3. Open the Design tab and double-click the Smart search box web part. 4. Check the Enable predictive search property. 5. Select one or more Indexes (in the Predictive settings category). 6. Uncheck Group results by index (in the Predictive results category). 7. Click New next to the Search result transformation property (in the Predictive results category). Create the following ASCX transformation: 7.
8. Click Save and close the dialog. 9. Save & Close.
Modifying the Smart search box CSS styles
1. Open the Web parts application. 2. Select the Smart search box web part in the tree (Full-text search -> Smart search). 3. Open the CSS tab. 4. Comment out the following default classes:
/* .predictiveSearchResults .selectedResult { text-decoration: underline; }
.predictiveSearchResults a { text-decoration: none; } */
5. Add the following class definitions:
.customPredictiveResultItem { line-height: 160%; margin: 2px; }
.customPredictiveResultItem a { display: block; color: black; text-decoration: none; }
.customPredictiveResultItem.selectedResult { color: white; background-color: #326CA6; }
.customPredictiveResultItem.selectedResult a { color: white; text-decoration: none; }
6. Click Save.
Result
If you now try searching using the box in the header of the Corporate site, the results found in the assigned search indexes appear while typing.
Each result shows the name of the related search index. Selected predictive results are highlighted using a colored background instead of the original underline effect.
Configuring search assistance features The smart search provides several features that can help users find relevant results.
Setting the search mode
The search mode determines how the search handles expressions with multiple words. The following options are available:
Any word - finds items that contain at least one of the words in the search expression. Any word or synonyms - works like Any word mode, but also finds items that contain synonyms of at least one word in the search expression. Only works for English by default. See Configuring the synonym search for more information. All words - finds only items that contain all of the words in the search expression (anywhere in the text). Exact phrase - finds items that contain the exact search expression, including word order.
To set the search mode, you can either:
Assign a fixed Search mode for your Smart search box or Smart search dialog web parts Allow users to select the search mode for every search request (available for the Smart search dialog if the Show search mode pro perty is enabled)
Enabling typo-tolerant search (fuzzy searching)
You can configure the smart search to return results for words that are only approximate matches. Typo-tolerant searching allows users to get correct results even if there are misspelled words in the search expression. For example, searching for code also matches words such as core or node.
The system evaluates approximate matches based on Edit Distance (the number of required character substitutions, insertions or deletions). Note:
The typo-tolerant search only works for search requests that use the Any word Search mode. Typo-tolerant search may prevent advanced search syntax from working correctly (for example field search). When using typo-tolerant search, we recommend setting the Search options property of the search result web part to None.
To enable the typo-tolerant search:
1. Configure the web part that you use to get and display search results (Smart search dialog with results or Smart search results). 2. Check Typo tolerant search in the Search settings category. 3. Click OK.
The search now finds words that are similar in spelling to the search terms.
Configuring the synonym search
Search requests that use the Any word or synonyms search mode allow users to find a wider set of results based on synonyms.
The synonym search works by expanding all words in the search expression into a list of synonyms. For example, when searching for the words "search assistance", the synonym search expands the expression to: "search explore hunt hunting look lookup research seek assis tance aid assist help"
The system looks up the synonyms inside index files stored in the ~\App_Data\CMSModules\SmartSearch\_Synonyms folder. By default, Kentico contains a synonym index for English based on the WordNet lexical database.
Setting the relevance of synonyms
You can change the relevance (result score) that the search assigns to items found through the synonym search. Add the CMSSearchSyno nymsWeight key into the appSettings section of your application's web.config file, for example:
The key's value must be a decimal number ranging from 0 to 1. A larger number assigns higher relevance to synonyms. If you set 1, the score of synonyms is equal to words in the original unexpanded search expression. The default value is 0.9.
Enabling synonym search for non-English languages
To extend the synonym search for languages other than English, you need to create a Lucene search index containing the synonym data. You can use the following approach:
1. Obtain a WordNet synonym database for the required language. The database must be in Prolog format.
You can find a list of WordNet projects at http://globalwordnet.org/.
2. Download the Lucene.Net Source (Apache-Lucene.Net-3.0.3-RC2.src.zip). 3. Unzip the Lucene.Net package. 4. Use the src\contrib\WordNet\Syns2Index\Syns2Index.cs class to generate the synonym index. You can run the class by debugging in Visual Studio, or using the Visual Studio Command Prompt. Specify the Prolog database file (.pl extension) and the output directory for the index files as parameters, for example:
Syns2Index wn_s.pl IndexOutput
5. Compress the synonym index files into a zip archive. The name of the zip file must match the culture code of the given language. You can use neutral culture codes to represent languages in general (such as fr) or the codes of specific countries/regions (such as fr-FR).
6. Place the synonym index zip file into the ~\App_Data\CMSModules\SmartSearch\_Synonyms folder in your Kentico web project.
The search expands words into synonyms according to the website's culture (language). The supported languages depend on the synonym index files that are present in your web project.
Setting up substring search and word stemming
Substring search and word stemming are assistance features that allow users to find results for: Words that contain the search terms Closely related words
To enable word stemming or substring search, you need to index content using the appropriate analyzers. The smart search uses analyzers to divide text into searchable tokens. Every smart search index has its own analyzer. The analyzers process both the indexed content and the search expressions entered by users. The search classifies words in the search expression as a match if they share at least one token with the indexed content.
To change the analyzer type of a search index:
1. Open the Smart search application. 2. Edit ( ) the index. 3. On the General tab, select the Analyzer type. 4. Click Save. 5. Rebuild the index.
Substring search
If you create your search indexes using substring analyzers, the search returns results for items that contain the search terms inside larger words or text sequences. Select one of the following analyzer types:
Analyzer type Description
Subset Indexes with subset analyzers return results for all words that contain the search term (the analyzer creates tokens for all possible substrings in words).
For example, searching for net matches words such as net, Interne t, network or kinetic.
Starts with Allows searching for all words that start with the search term (creates tokens for all prefixes contained in words, including the whole word).
For example, searching for test matches words such as test, tests, tester...
The Subset and Starts with analyzers use the following steps to process text:
1. Divide text into "words" 2. Create search tokens for the substrings inside the words (according to the analyzer type)
By default, the words created in the first step may contain the following characters:
word characters (upper and lower case letters, numbers, underscores) at symbols (@) periods ( . )
Any other characters split the text into separate words. This allows the analyzers to correctly create substring search tokens for text entities such as e-mail addresses and internet domain names.
To customize how the analyzers separate text into words:
1. Write a regular expression matching all characters that you want to allow inside words. 2. Add the CMSSubsetAnalyzerWordRegex key into the appSettings section of your application's web.config file, and set the regular expression as the value, for example:
The sample expression above allows the dollar sign in addition to the default characters. As a result, search indexes with Subset or Starts with analyzers can now find expressions such as: $Var
Note: After changing the value of the CMSSubsetAnalyzerWordRegex key, you need to Rebuild your search indexes that use Sub set or Starts with analyzers.
Word stemming
Stemming is the removal of suffixes from words. If you create your search indexes using stemming analyzers, the search matches words that have the same basic meaning, but different inflection. For example, users can find:
Inflected words when searching for a stem (program -> programs, programming) Word stems when searching for inflected words (trusted, trusting -> trust) Any words that share the same stem as the search terms (conditional -> conditions) Stemming does not find matches for all words that share the same morphological root — only words that have an identical or very similar meaning. For example, the words "flawed" and "flawless" do not have the same stem. Please keep in mind that word stemming does not work perfectly for all word combinations.
The smart search stemming analyzers are based on the Porter Stemming Algorithm.
The stemming analyzers process text in two steps:
1. Divide text into tokens (words) using a base analyzer. 2. Reduce the tokens into their stem form.
You can select three variations of stemming analyzers, each with a different base analyzer:
Analyzer type Base analyzer description
Simple with stemming Divides text into tokens at non-letter characters.
Stop words with stemming Uses a predefined collection of stop words to divide text.
White space with stemming Divides text at whitespace characters.
When users search for text using an index with a stemming analyzer, the analyzer also processes the search expression. As a result, the search finds all items containing words that share the same stem.
Note: The default stemming analyzers only work for English text.
Searching attachment files The smart search allows users to search through the content of files uploaded as page attachments.
The attachment search only works for files that are connected to pages through one of the following methods:
Attachment files added to pages through fields with the Data type set to File or Attachments in the page type definition Attachments uploaded in the Pages application on the Properties -> Attachments tab of pages
Choosing which file types are searchable
By default, the attachment search supports the following file types:
txt csv pdf docx xlsx pptx xml html htm
Note: The search does NOT work for:
Legacy MS Office formats: doc, xls, ppt Encrypted PDF files
You can limit which of the file types are searchable for individual websites:
1. Open the Settings application. 2. Select the System -> Search category. 3. Fill in the Allowed attachment file types setting. Enter a list of allowed file extensions without dots, separated by semicolons. If you leave the setting empty, the search works for all of the available file types.
4. Click Save.
If you wish to search other file types, you need to:
Implement a custom search text extractor
OR
Use the SQL attachment search
Enabling indexing for page attachments
The attachment search is a part of the functionality of standard Page indexes. To set up the attachment search for your website:
1. Open the Smart search application. 2. Create or edit a Page search index. 3. When defining the search content on the Indexed content tab, check Include attachment content for the index's allowed content. 4. Click Save. 5. Switch to the General tab and Rebuild the index.
While building the page index, the smart search processes the allowed pages, extracts the text of any attachment files and includes it in the content of the index (along with the other page data). When users perform a search using the index, the system returns results for pages whose attachments match the search expression.
Updating the search content of attachments (Upgrades and Hotfixes)
Kentico stores the text content extracted from page attachments in the database. When rebuilding page indexes, the search loads the "cached" attachment text from the database. The system only processes the file text directly for attachments that do not have any search content saved.
If you apply a hotfix or upgrade that changes how the search indexes attachment files, you need to clear the attachment search content:
1. Open the System application. 2. Select the Files -> Attachments tab. 3. Click Clear attachment search cache.
You can then Rebuild your page indexes, which updates the attachment content according to the new functionality.
Configuring the attachment search
You can adjust how the system indexes attachment files by adding keys to the appSettings section of your application's web.config file.
The indexed content always includes:
File metadata (title, tags, author name etc.) Comments (for example in MS Office files)
Limiting the maximum size of indexed files
Indexing of very large files can be resource intensive and have a negative impact on your website's performance. To prevent the system from indexing files larger than a certain size, add the CMSSearchMaxAttachmentSize key:
They key sets the maximum allowed file size in kB. The search ignores page attachments whose size exceeds the value.
Indexing of XML content
When indexing the content of XML files, the search does NOT include the following content by default:
Comments The values of tag attributes
You can enable indexing for such content by adding the following web.config keys:
Enabling character encoding detection for text files
By default, the search can read text files (txt and csv) that use the following character encoding:
UTF-8 The default Windows encoding (the operating system's current ANSI code page)
If you encounter problems when indexing text files with a different encoding type, you can enable automatic encoding detection:
The system then attempts to detect the encoding type for each file, and use the correct option when reading the content during the indexing process.
Note: Correct encoding detection is not guaranteed for all files. Automatic detection also slightly increases the time required to index text files.
Configuring SQL search for attachment files You can use the SQL search to find results in the content of page attachment files uploaded into the database.
Important: To search common file types (TXT, CSV, HTML/XML, PDF, MS Office open xml formats), use the attachment search fe ature of smart search page indexes. Only use the SQL search if you need to search file formats that are not supported, such as the legacy MS Office formats: DOC, XLS, PPT
The SQL attachment search uses the standard Microsoft SQL Server full-text search engine. The search is available for all supported versions of SQL Server:
SQL Server 2008 SQL Server 2008 R2 SQL Server 2012
Prerequisites:
Full-text search support must be installed on your SQL Server. The full-text search is available for all editions of Microsoft SQL Server, including the Express Edition with Advanced Services. Your Kentico website must be configured for storing files in the database (Settings -> System -> Files -> Store files in database).
Use one of the following guides to configure your Kentico database for SQL search of attachment files:
Manually configuring full-text search on MSSQL Server Enabling full-text search on MSSQL Server - Script
Supported file types
The standard full-text search engine delivered with Microsoft SQL Server can search the following file types:
TXT HTML DOC XLS PPT
If you want to search other types of text files, you need to install appropriate IFilter libraries. You can download or purchase IFilter libraries from third-party vendors.
Manually configuring full-text search on MSSQL Server
Use the following steps to configure your Kentico database for full-text search in file attachments:
1. Start Microsoft SQL Server Management Studio. If you cannot use SQL Server Management Studio on your database server, you can configure the full-text search through a script instead.
2. Locate your Kentico database. 3. Unfold the Storage sub-folder, right-click Full Text Catalogs and click New Full-Text Catalog. 3.
4. Type a Full-text catalog name and click OK.
5. Right-click the new full-text catalog and choose Properties. 6. In the Full-Text Catalog Properties dialog, click the Tables/Views tab. 7. Assign the CMS_Attachment table to the catalog. a. Check the box next to the AttachmentBinary column b. Set the Language for Word Breaker to English or another value c. Set the Data Type Column to AttachmentExtension 7.
8. Click OK.
You can now combine the SQL attachment search with smart search results or enable attachments for the SQL search.
Enabling full-text search on MSSQL Server - Script
If you cannot use SQL Server Management Studio to configure the full-text search, run the following script against your Kentico database:
-- Allows IFilter library loading exec sp_fulltext_service 'verify_signature', 0 exec sp_fulltext_service 'load_os_resources', 1
-- Creates the Full Text Catalog exec sp_fulltext_catalog 'KenticoCMSCatalog','create'
-- Adds the CMS_Attachment table to the catalog exec sp_fulltext_table 'CMS_Attachment','create','KenticoCMSCatalog','PK_CMS_Attachment'
-- Sets the data column of the CMS_Attachment table in the catalog exec sp_fulltext_column 'CMS_Attachment','AttachmentBinary','add',NULL,'AttachmentExtension'
-- Populates the catalog exec sp_fulltext_table 'CMS_Attachment','start_full'
You can now combine the SQL attachment search with smart search results or enable attachments for the SQL search.
Combining the SQL attachment search with the Smart search
Once you have the SQL server set up, you can configure your smart search result web parts to run SQL searches through the content of page attachments.
Enable SQL attachment searching through the properties of the Smart search dialog with results or Smart search results web part: Property name Description
Enable SQL attachment search If checked, the web part runs an SQL attachment search for every search request and combines the results with the results provided by the assigned indexes.
WHERE condition WHERE condition used to limit the scope of the attachment search for the web part. You can use the condition to:
Specify which pages have their attachments searched Use the columns of the CMS_Attachment table to search only attachments of a specific type, for example: AttachmentExtens ion = '.txt'
ORDER BY expression ORDER BY expression that determines the order of pages retrieved by the attachment search in the results.
When users perform a search and the system finds a match in the attachment of a page, the given page is added to the search results. The attachment results are always interlaced with the other results provided by the specified smart search indexes. This behavior is by design and cannot be modified.
The attachment search is performed by the SQL server, so it is not affected by the settings and restrictions of the used search indexes. To limit the attachment search scope, enter an appropriate value into the WHERE condition property of the used web part. For example, if you have a search results web part using a page index that is limited to the /News/% section of your website, you need to add the following WHE RE condition to ensure that the attachment search is also restricted to these pages: NodeAliasPath LIKE '/News/%'
The search only returns pages if they are directly connected to the matching attachment through one of the following methods:
Attachment files added to pages through fields with the Data type set to File or Attachments in the page type definition. Attachments uploaded in the Pages application on the Properties -> Attachments tab of pages
Enabling attachment search for the SQL search
Perform the following steps if you wish to search attachments using the SQL search:
1. Open the Page types application. 2. Edit the Root page type. 3. Select the Queries tab. 4. Edit the searchattachments query and uncomment the following part of the code:
SELECT View_CMS_Tree_Joined.*, View_CMS_Tree_Joined.NodeName AS SearchResultName FROM CMS_Attachment INNER JOIN View_CMS_Tree_Joined ON View_CMS_Tree_Joined.DocumentID = CMS_Attachment.AttachmentDocumentID WHERE (##WHERE##) AND (([AttachmentName] Like N'%'+ @Expression + N'%') OR ([AttachmentTitle] Like N'%'+ @Expression + N'%') OR ([AttachmentDescription] Like N'%'+ @Expression + N'%')) OR (FREETEXT(AttachmentBinary, @expression)) ORDER BY ##ORDERBY##
The SQL search automatically includes the results from the attachment search.
Using search filters The Smart search filter web part allows users to limit the range of objects that will be searched (conditional filter), or define the order of the search results. You can connect any number of filters to the Smart search dialog or Smart search dialog with results.
The behavior of the smart search filter is primarily defined by the properties described below.
You can find information about the other properties by clicking the help link in the corner of the web part properties dialog.
Property Description
Search dialog web part ID Enter the Web part control ID of the Smart search dialog or Smart search dialog with results web part that you wish to connect to the filter. Filter mode Sets the user interface type of the filter. Possible choices are:
Drop-down list Checkboxes Radio buttons Text box
Filter auto postback Indicates whether the search results automatically refresh (via postback) whenever a user selects a different filtering option. Not applicable when using the text box Filter mode.
Values Determines the available filtering options. See the Defining filtering options section below for details.
Query name Allows you to create the filtering options dynamically using a query (instead of the Values property). Enter the full code name of the query or Select a query. The query must return the appropriate values depending on the type of the filter.
For example, for a standard conditional filter, the query needs to load three columns in the following order:
The following is a sample query that loads all page types as conditional filtering options:
SELECT TOP 1000 '+classname', ClassName, ClassDisplayName FROM CMS_Class WHERE ClassIsDocumentType = 1
Filter clause Sets a clause that overrides the logical values specified for filtering options. Possible choices are:
None - no clause is added and the original logical values set for individual filtering options are used. Must - indicates that the conditions in all filtering options must be fulfilled (adds the + symbol). Must not - indicates that the conditions in all filtering options must not be fulfilled (adds the - symbol). Conditions are inverted compared to the Must option.
Filter is conditional If true, the filter limits the scope of the objects that are searched (where condition). If false, the filter determines the order in which the search results are displayed (order by condition).
You can find examples of search filters on the sample Corporate Site on the Examples -> Web parts -> Full-text search -> Smart search -> Smart search filter and Faceted search pages.
Defining filtering options
The most important part of configuring Smart search filter web parts is the definition of the filtering options offered to users. In most cases, you will set the options through the Values property of the web part. If you wish to use the Query name property to load the options dynamically, the rules described below also apply to the results retrieved by the query.
The format of the filtering options depends on the type of the filter.
Conditional filters
In the case of conditional filters, define one option per line in format:
Index field name;Value of the field;Displayed text
You need to specify the logical meaning of each filtering option by adding the + or - symbol as a prefix:
+ The search only returns objects whose value in the field matches the value specified in the second part of the filtering option's definition. - The search excludes all results whose value in the field matches the value specified in the second part of the filtering option's definition.
To create filtering options that check the values of multiple index fields, use the following syntax: (Field1:(Value1) OR Field2:(Value2));;Text
If you wish to use the same value for all fields in the condition clause, you can insert the value using the {0} expression: (Field1{0} OR Field2{0};Value;Text
When entering integer or double type fields as filter options, you need to specify the type of the value:
+DocumentCreatedByUserID;(int)53;Administrator
Examples:
;;All +classname;cms.smartphone;Smartphones +_created;[{%ToSearchDateTime(CurrentDateTime.AddDays(-7))%} TO {%ToSearchDateTime(CurrentDateTime)%}];Past week +_content;product;Results related to products +(documenttags{0} OR _content{0});product;Results related to products -(issecurednode:(true) OR requiresssl:((int)1));;Exclude secured pages
Search result order filters
When creating filters that change the order of the results (i.e. the Filter is conditional property is disabled), define options in the following format:
Index field name;;Displayed text
The order is determined according to the values in the specified field.
Examples:
##SCORE##;;Score documentcreatedwhen;;Creation date SKUPrice DESC;;Price descending
Text box filter mode
Text box filters do not offer any selection options, so the Values property instead determines which index fields the system searches when a user enters an expression into the text box. You can specify multiple fields, each one on a new line. Like with standard conditional filters, the + and - symbols determine whether the search returns results that contain the text box value in the given field, or only those that do not.
For example, if a text box filter has +DocumentTags in the Values definition, visitors can enter the names of page tags into the text box and perform a standard search. The filter modifies the retrieved results to contain only pages that are marked by the specified tags.
Use the following syntax to create OR conditions that are fulfilled if the text box value matches at least one of multiple fields: (Field1{0} OR Field2{0})
For example: +(DocumentTags{0} OR _content{0})
The {0} expression represents the value that users type into the text box filter. The search internally converts the expression to Field:(value) i n the resulting condition.
Tip: To create a text box filter that behaves like a regular search box, use +_content as the only field name.
You can also use text box filters to determine the order of the search results. In this case, disable the filter web part's Filter is conditional pr operty and leave the Values property empty. Users can then enter the name of the field used for ordering into the text box. This scenario is not recommended for use by regular visitors on the live site.
In order for the filter to work correctly, the data fields used in the option definitions must be set as Searchable in the smart search field configuration of the given object type.
You can also create filtering options for the fields that are marked as Content by using _content as the field name. Such conditions are fulfilled if the value is found in any of the content fields.
Filtering without search text (Faceted search)
You can implement a faceted search based exclusively on filters. Faceted search allows users to get search results simply by selecting filtering options, without the need to enter and submit search text. To achieve this result, Configure the properties of the web part that you use to display search results (Smart search results or Smart search dialog with results) according to the following instructions:
1. Make sure that the Search text required property is disabled. 2. Leave the Block fieldonly search property disabled, unless you wish to force users to use a filtering option that works with standard 2. content fields (i.e. filtering options that have _content as their field name). 3. Enable Search on each page load (ensures that the web part automatically displays results whenever the page is loaded, even without input from a search dialog). 4. For additional convenience, enable the Filter auto postback property for your Smart search filter web parts (instantly refreshes the search results after users change the filtering options).
Smart search syntax Users can submit advanced search expressions using the Lucene query parser syntax. You can find detailed information at: http://lucene.apache.org/core/old_versioned_docs/versions/3_0_3/queryparsersyntax.html
To allow the advanced syntax, configure the Search options property of the Smart search dialog with results or Smart search results we b part. You can choose one of the following levels of supported syntax:
None - the search does not recognize any Lucene query syntax. The system processes all text entered by users as a part of the search expression. Basic - the search recognizes all query syntax, except for field searching. Full - the search processes all search query syntax, including field searching.
Note: The system does not process advanced query syntax for search requests that use the Any word or synonyms Search mode.
Search syntax errors
If you allow advanced search expressions through the Search options property, a parsing error occurs if a user enters the query syntax incorrectly.
By default, syntax errors cause the search to show the standard "No results" message, and the system enters the error into the application's Event log. If you wish to view syntax errors in place of the results directly on the live site, enable the Show parsing errors property of the given smart search results web part.
Field search
Field searching allows users to define additional conditions in search expressions. All conditions must start with either the + or - symbol. The + symbol indicates that only results which fulfill the field condition should be returned. The - symbol has the opposite meaning, only results that do not contain the specified value in the given field are retrieved.
For example:
+network +NewsReleaseDate:[20080101 TO 20091231]
When searching for this expression using a page index, the smart search returns only news pages containing the word network, released in the year 2008 or 2009.
Field search requirements
Field search only works for fields set as Searchable in the field configuration of the searched object type. If there is no field name specified before a value in the search expression (such as the word network in the example above), the system searches the index fields marked as Content. The system only processes field searches correctly if the search dialog web part has its Search mode set to Any words.
Unless the web part used to display the search results has the Block field-only search property enabled, it is also possible to perform direct field searches without any standard content keywords. This allows users to find records simply by entering an exact field value:
DocumentNodeID:(int)17 - returns the page with a nodeID equal to 17. NewsTitle:"New features" - returns the news page titled New features. SKUDepartmentID:(int)4 - returns all products that belong to the department that has 4 as its ID.
Tip: Using field search queries provides a great deal of flexibility, but is not convenient for regular website visitors. If you wish to allow users to limit the scope of searches through conditions on the live site, we recommended creating Search filters.
Searching numeric fields
When performing field searches, the values specified are processed as strings by default. If you know that you are searching in integer or do uble fields, you need to specify the type of the field:
NewsID:(int)22 SKUPrice:(double)255.0 DocumentNodeID:[(int)1 TO (int)100]
Searching date and time fields Use the following syntax to search in DateTime fields:
For example:
DocumentCreatedWhen:200812230101 DocumentCreatedWhen:[200902020101 TO 200906020101]
If you need to specify date and time values through macros, call the ToSearchDateTime method to convert the values to the suitable format. For example:
{% ToSearchDateTime(CurrentDateTime) %} {% ToSearchDateTime(CurrentDateTime.AddHours(12)) %} {% ToSearchDateTime(CurrentUser.UserCreated, CurrentDateTime) %}
The ToSearchDateTime method's second optional parameter sets a default DateTime value returned if the first parameter is null.
Field search with Stop and Simple analyzers
Indexes created by Stop and Simple analyzers cannot be searched using the standard field search format. This is by design, but you can use a workaround with a range query containing identical boundaries:
newsid:[(int)22 TO (int)22]
Displaying search results using transformations You can use the following default transformations to display search results using the Smart search dialog with results and Smart search results web parts:
CMS.Root.SmartSearchResults CMS.Root.SmartSearchResultsWithImages
The system returns search results in a search dataset. No matter how the fields are named in the found objects, the search dataset always contains the following fields that are automatically mapped to the corresponding object fields:
Search result field Description
score Expresses the relevance of the search result item as a numeric value. Higher values indicate higher relevance.
title Mapped to the field selected as the Title field on the Search fields tab for the given object type.
content Mapped to the field selected as the Content field on the Search fields tab for the given object type.
created Mapped to the field selected as the Date field on the Search fields tab for the given object type.
image Mapped to the field selected as the Image field on the Search fields tab for the given object type.
index The code name of the search index where the given result was found.
imageClass Available for page search results. The imageClass field contains the name of the CSS class that defines the font icon representing the MIME type of the given page. The system generates the class based on the URL extension of the page (automatic for CMS.File pages).
For example, you can display the MIME type font icon in your search results using the following transformation code:
">
In the code of ASCX transformations, you can get the values from the dataset by using the Eval("
You can also use the following methods in your transformations:
SearchResultUrl(bool absolute) - returns the URL of the page containing the details of the search result. The optional parameter indicates if the returned URL is absolute.
Search result URLs for general index results The SearchResultUrl method does not return valid URLs for search results produced by general indexes, since the indexed objects are not pages and there is no default page to display the object details. You need to write and use a custo m transformation method to generate the correct URL of a custom page displaying the appropriate information.
SearchHighlight(string text, string startTag, string endTag) - wraps the text entered in the first parameter into the tags specified by the other two parameters. GetSearchImageUrl(string noImageUrl, int maxSideSize) - returns the URL of the current search result image. The first parameter specifies the URL returned if no image is found, the second one specifies the maximum side size to which the method resizes the image. GetSearchValue(string columnName) - returns the value of the specified field for the current search result. Allows you to access both the general fields of the given objects type (page, custom table etc.) and any other fields included in the search index. GetSearchedContent(string content) - parses the searched content as XML if required, and removes dynamic controls and macro expressions.
Searching according to page permissions You can set the smart search to filter out results for pages that users are not allowed to access:
1. Open the Pages application. 2. Select the page containing the web part you use to get and display search results (Smart search dialog with results or Smart search results). 3. Switch to the Design tab and configure the web part (double-click). 4. Enable Check permissions in the Page filter category. 5. Click OK.
With the Check permissions property enabled, the search results display pages according to the read permissions of individual users.
SQL search The SQL search is an obsolete search engine for pages in the content tree of websites.
We highly recommend using the index-based smart search instead.
The system continues supporting the SQL search for the following reasons:
Backward compatibility with older versions Searching uncommon and legacy file types uploaded as page attachments
This search engine uses standard SQL queries to search for expressions:
The system automatically generates search queries for the data of individual page types. To override the search query for a page type, create a new query named searchtree in Page types -> Edit page type -> Queries. The searchpages query of the Root page type searches fields that are shared by all pages. The searchattachments query of the Root page type searches files uploaded as page attachments. To search attachments, you need to configure the system as described in Configuring SQL search for attachment files.
Adding the SQL search onto your website
To integrate the SQL search into website pages, use the web parts in the Full-text search category (SQL search dialog, SQL search box, etc.) or the CMSSearchDialog and CMSSearchResults server controls (in your ASP.NET code).
Excluding pages from the search
To exclude pages from the SQL search, open the Settings application and select the System -> Search category:
Exclude page types from SQL search - enter page type code names, for example cms.article. You can enter multiple page types separated by semicolons (;). Exclude pages from SQL search - allows you to exclude entire website sections from the SQL search To exclude a single page, enter the alias path, for example: /news/news1 To exclude entire website sections, enter a path expression, for example: /news/% You can enter multiple values separated by semicolons (;).
To directly exclude individual pages from the SQL search:
1. Open the Pages application. 2. Select the page in the content tree. 3. Open the Properties -> Navigation tab. 4. Check Exclude from search. 5. Click Save.
Modifying the search result format
If you wish to change the format of the SQL search results:
1. Open the Page types application. 2. 2. Edit ( ) the Root page type. 3. Select the Transformations tab. 4. Adjust the SearchResults transformation.
Developing custom search providers
If you need to integrate a custom search engine or make additional modifications to the search results returned by the SQL search engine, you can develop your own search provider. You can find more details in Creating custom SQL search providers.
Scheduling tasks The Scheduled tasks application allows you to configure how the system executes automatic tasks. Scheduled tasks can be useful when you need to perform operations at a specific time or regularly over a certain time period. Many Kentico features leverage scheduled tasks.
Configuring scheduled task settings
To configure scheduled task settings:
1. Open the Settings application. 2. Select the System category. 3. Adjust the settings in the Scheduler section. 4. Click Save.
Managing scheduled tasks
To work with individual scheduled tasks, open the Scheduled tasks application.
Two types of tasks are available:
Global - affect the entire system (global features and objects). Only available for users with the Global administrator privilege level. Choose the (global) option in the Site selector. Site-related - tasks that affect content related to the selected Site.
The System tasks tab provides an overview of temporary tasks created dynamically by the system. System tasks internally provide functionality for various Kentico features. You cannot manually create system tasks.
Configuring scheduled task execution This page explains how to configure execution of scheduled tasks. Scheduled tasks can be executed:
By the Kentico web application itself By a dedicated external Windows service
You can have both approaches enabled and execute some tasks directly in Kentico and other tasks via the external Windows service.
Scheduling reliability
Task execution by the Kentico application runs within the ASP.NET process, so tasks cannot be executed if the web application is not running. The application stops running when the process is recycled without being started again (after a long period of website inactivity).
If you want to run the scheduling reliably, we recommend using the Windows scheduling service.
To achieve reliable task execution without using the Windows scheduling service, you need to ensure that your website is always running. For example, you can prepare a utility or service that requests the home of your website on a regular basis. Configuring execution by the Kentico application
By default, all scheduled tasks are executed by the Kentico application.
Setting the task execution time
There are two levels of settings that determine when the system executes tasks:
Task interval - the properties of individual scheduled tasks determine when tasks are ready for execution. Application scheduler interval - determines the time interval after which the application checks if any tasks are ready to be executed.
Task interval
To configure the interval that determines when individual scheduled tasks are ready to be executed:
1. Open the Scheduled tasks application. 2. Edit ( ) the scheduled task. 3. Set the task's scheduling options (Period, Start time, Every, Between, Days). 4. Click Save.
Application scheduler interval
To configure how frequently the application checks if there are any tasks ready to be executed:
1. Open the Settings application. 2. Select the System category. 3. Type a number of seconds into the Application scheduler interval setting. 4. Click Save.
Execution of scheduled tasks by the Kentico application has two modes.
Request-based scheduler mode
This is the default mode. The application performs checks at the end of each standard page request. This means that tasks are only executed when user activity on your website generates requests.
In this case, the Application scheduler interval sets the minimum time between the checks:
For example, a value of 60 means that the application checks after 60 seconds even if multiple page requests occur per minute. Tasks are NOT executed if there are no page requests. 0 disables the execution of tasks by the application.
Automatic scheduler mode
You can configure the scheduler to process tasks regularly according to an automatic internal timer, regardless of website activity. To enable this mode, add the CMSUseAutomaticScheduler key into the /configuration/appSettings section of your web.config file:
In this case, the Application scheduler interval sets the precise interval between the checks:
Values between 1 - 30 seconds define the interval between checks. For example, a value of 30 means that the application checks tasks every 30 seconds. 0 disables the execution of tasks by the application.
Configuring execution by the Windows service
Executing tasks using the external Windows service is recommended for resourceconsuming tasks, because the execution does not affect the performance of the Kentico application.
Enabling the Windows scheduler service
Prerequisites
You need to have the Kentico Scheduler Windows service installed and running.
Note
Only some of the default scheduled tasks support this option. The tasks that do not have the option available in the editing interface must be processed by the application itself. 1. Open the Settings application. 2. Select the System category. 3. Enable the Use external service setting. 4. In the Scheduled tasks application, enable the Use external service option for individual tasks. Tasks with the Use external service option disabled will be executed by the Kentico application itself. If the Use external service setting in the Settings application is disabled, even tasks with the Use external service option enabled are processed by the Kentico application itself.
Resolving context macros when executing tasks by the Windows service
Tasks that are executed by the Windows service cannot resolve macros dependent on application context (for example {% ApplicationPath %}). The context is not available when tasks are executed outside the application. Therefore, you cannot execute such tasks using the Windows service.
Setting the task execution time
There are two levels of settings that determine when the Windows scheduler service executes tasks:
Task interval - the properties of individual scheduled tasks determine when tasks are ready for execution. Service scheduler interval - determines the time interval after which the service checks if any tasks are ready to be executed.
Task interval
To configure the interval that determines when individual scheduled tasks are ready to be executed:
1. Open the Scheduled tasks application. 2. Edit ( ) the scheduled task. 3. Set the task's scheduling options (Period, Start time, Every, Between, Days). 4. Click Save.
Service scheduler interval
To configure how frequently the Windows scheduler service checks if there are any tasks ready to be executed:
1. Open the Settings application. 2. Select the System category. 3. Type a number of seconds into the Service scheduler interval setting. 4. Click Save.
This setting only applies to tasks that are configured to be executed by the Windows service, not by the application itself.
The Service scheduler interval sets the precise interval between the checks:
Values between 1 - 30 seconds define the interval between checks. For example, a value 30 means, that the service checks tasks every 30 seconds. 0 disables the execution of tasks by the external service.
Additional low-level settings
Additional low-level scheduled task settings can be done by adding the keys listed in the Scheduler settings section of the Web.config application keys reference.
Installing the Scheduler Windows service Kentico provides a dedicated Windows service for executing scheduled tasks. You can use the service to execute tasks externally instead of the application itself (typically for resource-consuming tasks). Executing scheduled tasks using the Windows service can optimize the performance of your application.
Installing the Scheduler Windows service using Kentico Service Manager
The easiest way to install the Scheduler Windows service is to use the Kentico Service Manager utility:
1. Launch the Kentico Service Manager utility from the Kentico program files group in the Windows Start menu. You can also launch the KSM utility from Kentico Installation Manager using the Services button. 2. Choose the Kentico instance where you want to install the service (select the CMS folder). 3. Select the Kentico Scheduler service. 4. Click Install. 4.
5. Click Start to start the service after it is installed.
You have installed the Kentico Scheduler service, which is now running and ready to be used.
You can uninstall the service at any time by clicking Uninstall in the Kentico Service Manager utility.
Installing the Scheduler Windows service from the command line
To install the Windows service from the command line, you need to use Installer Tool (InstallUtil.exe), which is a native part of the .NET Framework:
1. Open the Windows command line (type cmd in the Start menu search box) 2. Navigate to the .NET folder containing InstallUtil.exe (e.g. c:\Windows\Microsoft.NET\Framework64\v4.0.30319\). 3. Execute InstallUtil.exe from the Windows command line with the following parameters:
InstallUtil.exe /webpath="C:\inetpub\wwwroot\Kentico\CMS" "c:\inetpub\wwwroot\Kentico\CMS\bin\SchedulerService.exe" /LogToConsole=true /i
The following table describes the used parameters:
/webpath Path to the CMS folder of the Kentico instance for which you want to install the service.
second parameter Path to the SchedulerService.exe file in the Bin folder inside the application (typically c:\inetpub\wwwroot\Kentico\CMS\bin\ SchedulerService.exe).
/LogToConsole Optional parameter that determines whether the installation progress is logged to the console.
/i If this parameter is used, the Installer Tool performs installation of the Windows service.
4. Open the Services management console (type services.msc into the Start menu search box). 5. Select the Kentico Scheduler (
Uninstalling the Scheduler Windows service from the command line
1. Open the Windows command line (type cmd in the Start menu search box). 2. Navigate to the .NET folder containing InstallUtil.exe (e.g. c:\Windows\Microsoft.NET\Framework64\v4.0.30319\). 3. Execute InstallUtil.exe from the Windows command line with the following parameters:
InstallUtil /webpath="C:\inetpub\wwwroot\Kentico\CMS" "c:\inetpub\wwwroot\Kentico\CMS\bin\SchedulerService.exe" /LogToConsole=true /u
After executing this command, the Scheduler Windows service for the Kentico instance specified by the /webpath parameter is uninstalled.
Reference - scheduled task properties The following table explains the properties of scheduled tasks. To configure tasks:
1. Open the Scheduled tasks application. 2. Edit ( ) the task.
Property Description
Task display name Sets a name for the task that appears in the administration interface.
Task name Serves as a unique identifier for the scheduled task, for example in the API. You can leave the (automatic) option to have the system generate an appropriate code name based on the display name.
Task provider Selects the class that implements the scheduled task.
Assembly name - specifies the name of the assembly where the task is implemented. Choose the (custom classes) option for tasks implemented in the App_Code folder. Class - specifies the exact class (including any namespaces) that defines the functionality of the scheduled task.
Period Set the time interval between the execution of the task. The interval Start time settings do not ensure that the system executes the task at the Every exact time, only that the task is considered ready for execution. Between The precise execution time depends on the scheduling settings Days and other factors.
See also: Configuring scheduled task execution
Task data Additional data provided to the task's class. You can access the field from the code of the task, and use the value as a parameter. The Task data allows you to modify the task's functionality without having to edit the code implementation. Task condition Allows you to enter an additional macro condition that must be fulfilled in order for the scheduler to execute the task.
You can write any condition according to your specific requirements. For details about available macro options and syntax, refer to the Macro expressions chapter.
Click Edit to open the macro condition editor, which allows you to build conditions using macro rules.
Task enabled Indicates if the system executes the task.
Delete task after last run Indicates if the system deletes the task after its final run (applicable if the task is set to run only once).
Run task in separate thread Indicates if the scheduler executes the task in a separate thread to improve application performance.
It is not possible to access context data (information about the current page, user, etc.) in the code of tasks that are executed in a separate thread.
Use external service If enabled, the task is processed by the Installing the Scheduler Windows service instead of the web application. If the Use external service setting in Settings -> System is disabled, even tasks with this option enabled are processed by the application itself.
Only some of the default scheduled tasks support this option. The tasks that do not have the option available in the editing interfaces must be processed by the application itself.
You cannot define the task in the App_Code folder if you wish to use the external service. To run a custom task externally, you must add a new assembly to your project and then define the task class there.
Run individually for each site Only available for global tasks. If enabled, the scheduler executes ______the task repeatedly as a sitespecific task, once for each running site in the system. The task automatically runs within the context of the corresponding site.
This can be useful if you wish to manage a task in a single location instead of creating a separate one for every site.
Server name Sets the name of the web farm server where the task is executed. This field is applicable only if your application is running in a Web farm environment.
To add a new task for all web farm servers currently registered in the system, select the Create tasks for all web farm servers chec k box below the field.
Use context of user If the scheduled task needs to access data from the user context in its code (e.g. to check permissions), you can use this property to choose which user is provided. The scheduler always executes the task within the context of the selected user.
In most cases, the user context does not affect the functionality of the task, and you can leave the (default) option — the context of a public user is used.
Executions Shows how many times the task has been executed. You can reset this counter back to 0 by clicking Reset.
Configuring SMTP servers Kentico includes many features that utilize email messages as part of their functionality, such as:
Automatic notifications Email campaigns Various types of confirmation messages Content subscriptions
To allow the application to send out emails, you need to register and configure at least one SMTP server in the administration interface.
Setting up the default SMTP server To register the main SMTP server:
1. Open the Settings application. 2. Navigate to the System -> Emails category. 3. Select an option in the Site selector: Choose a specific site to register a server dedicated to a single website. Choose (global) to register a designated global server — the server processes emails from all sites in the system, and also handles emails that are not related to any specific website.
4. Fill in the following settings: SMTP server - enter the domain name or IP address of the server, including the port number (if it is not 25). Enter localhost to use a server provided by your local machine. SMTP server user - if the server requires authentication, type the user name here. SMTP server password - if the server requires authentication, type the password here. Use SSL - enable to use an SSL secured connection to the SMTP server. The server must be configured for SSL in order for this to work.
5. Click Save.
The system uses the primary server as the default option when sending emails.
Configuring additional SMTP servers
Kentico EMS required
You must have the Kentico EMS license to register multiple SMTP servers.
In addition to the default server, you can add any number of servers in the SMTP servers application. Having multiple SMTP servers allows the system to send out a greater volume of email traffic. Emails use the extra servers whenever the default server is busy.
You can manage existing servers through the following actions:
Edit - opens the server's configuration interface Delete Enable / Disable - enables or disables the server within the context of Kentico To register new servers, click New SMTP server.
When creating new SMTP servers or editing existing ones on the General tab, you can fill in the same options as described for the default server. In addition, you can choose the delivery method for emails:
Network - emails are sent directly to the SMTP server defined by the server name and credentials. This is the default setting for the default SMTP server defined in Settings -> System -> Emails. Pickup directory - use this option if you expect high email traffic on your servers (the method is faster and safer than the Network method). The emails are copied to a folder on the disk (defined by the Pickup directory option), from where they are processed by the SMTP server. Note that you have to grant the IIS_IUSRS group write permissions for the chosen folder. Pickup directory from IIS - similar to the Pickup directory, but may be more difficult to configure. Choose this method if you are already using Microsoft SMTP servers on Windows Server operating systems. You also need to install the SMTP server feature into your IIS and configure it properly. See Configure SMTP Email (IIS 7) for more information. Note that you have to ensure that the NETWORK SERVICE group has write permissions for the defined pickup folder.
Microsoft Azure supports only the Network method.
You may also select the server's Priority. See the Configuring email processing section below for more information about server priority.
If there are multiple sites running under your application, you can assign servers to individual websites on the Sites tab. SMTP servers can either be global or limited to one or more specific websites.
Configuring email processing
You can configure how the system delivers emails to the SMTP servers through the settings in Settings -> System -> Emails.
If Enable email queue is checked, the system temporarily stores all outgoing emails in the database instead of sending them directly to the SMTP servers. This allows advanced email processing and automatic resending of mails that are lost due to errors. Refer to Sending emails t o learn more about the email queue.
Using the email queue is highly recommended when sending out large amounts of emails over a short amount of time.
The system periodically processes the email queue (every minute by default) and asynchronously distributes the stored emails to the SMTP servers:
1. A predefined amount of emails is loaded from the queue as a batch. 2. The system goes through the emails one by one and assigns them to servers according to their priority and availability. The default SMTP server always has the highest priority. Other servers are ordered according to the value of their Priority property (i.e. emails are first assigned to High priority servers, then Normal and finally Low).
3. When a server receives an email, the server is flagged as busy until the sending is complete. 4. The system loads a new batch from the queue and continues assigning individual emails to available servers.
This process is repeated until all emails in the queue are mailed out.
Batch size
The maximum number of emails which is loaded from the database in a single batch is determined by the value of the Batch size setting. The batch size affects all sites in the system, so it is only available if the (global) option is selected in the Site selector on the top left of the settings page.
The value of the batch size affects the number and frequency of database queries. If you set the batch size too large, the system will have to process a lot of database data at one time. Using a smaller batch size increases the frequency of database queries and may reduce the database performance.
Testing SMTP servers
To confirm that your SMTP servers are configured correctly and available, you can send testing emails in the System application on the Ema il tab.
Debugging emails
Debugging can help resolve problems with emails sent by Kentico.
To enable email debugging, add the following keys to the configuration/appSettings section of your project's web.config file:
CMSLogEmails - logs all sent emails to the ~/AppData/logemails.log file. The log contains each email's recipient and subject. CMSDebugEmails - disables sending of emails to the actual recipients. The system only logs emails into the event log. Helpful if you need to test the functionality, but do not want the emails to actually reach the recipients. To view the event log, open the Event log application. The emails are logged as Information type events. The Event code column contains the recipient's address. The system randomly generates Sending failed for
Reference - SMTP server properties When you define a new SMTP server or edit an existing one in the SMTP servers application, you can specify the following properties.
General
Server name Specifies the domain name or IP address of the SMTP server. If the connection to the server should use a different port than 25, include it in the name.
Enter localhost if you wish to use the server provided by your local machine.
Priority When an email (or batch of emails) needs to be sent out, the system checks the SMTP servers in the order of their priority and uses the first one that is available. As a result, servers with a higher priority receive a greater email load.
The server with the highest priority for each website is the default SMTP server configured in Settings -> System -> Emails. If this server is busy or undefined, the email checks for any available server with the High priority, then Normal and finally Low.
Enabled Can be used to manually disable or enable the server (within the context of Kentico). A disabled server is skipped when outgoing emails check for available servers.
Advanced Delivery method The delivery method for emails sent from the system:
Network - the email is sent directly to the SMTP server defined by the server name and credentials. Pickup directory - the emails are copied to a folder (defined by the Pickup directory option) on the disk, from where they are processed by the SMTP server. Pickup directory from IIS - similar to the Pickup directory m ethod, except that the folder and SMPT server must be defined through IIS. You have to first install the SMTP server feature into your IIS and configure it properly. See more information in this article: Configure SMTP Email (IIS 7). Moreover, you have to ensure that the NETWORK SERVICE group has write permissions for the defined pickup folder.
Delivery method - Network
Username If the SMTP server requires authentication, you can enter the user name here.
Password If the SMTP server requires authentication, you can enter the password here.
Use SSL Indicates if the SMTP connection to the server should be secured by SSL. The server must be configured to use SSL in order for this to work.
Delivery method - Pickup directory
Pickup directory Specifies a folder on the disk, where emails will be stored until the SMTP server processes them.
The IIS_IUSRS group must be granted write permissions for this folder.
Managing email templates Kentico sends automatic system emails for various purposes, for example workflow notifications. The content of such emails is determined by templates according to the type of the given email. Many Kentico features send emails based on predefined templates that are included in the default installation.
To edit the templates, open the Email templates application. Editing templates allows you to alter the emails sent by the system to match the required design and/or language.
There are two types of email templates:
Global - only users with the Global administrator privilege level can manage global email templates. Choose the (global) option in the Site selector. Site-specific - allow you to override the global templates for specific websites. You need to select the appropriate Site and create a new template with a Code name that matches the corresponding global template.
The system only contains global templates by default.
When editing email templates, the following properties are available:
Property Description
Display name The name of the template displayed in the administration interface.
Code name Serves as a unique identifier of the email template (for example in the API).
Email type Identifies the type of functionality to which the template is related. This can be used to categorize and filter email templates.
From Email address used as the sender (From) address of the email.
Cc Email addresses of copy recipients.
Bcc Email addresses of blind copy recipients (receive a copy of the email, but cannot see the addresses of other recipients in the mail). Subject Subject of the email.
HTML version Defines the content that is used for the template when sending emails in HTML format.
You can select the preferred format using the Settings -> System -> Emails -> Email format setting.
Plain text version Plain text version of the email template.
Example of the HTML version of a template:
This is an automatic notification sent by Kentico. The following page is waiting for your approval. Please sign in to the Kentico administration interface and approve it.
Page: {%documentname%} {% ifEmpty(DocumentPreviewUrl, "", "(preview)")|(encode)false %}
Last approved by: {%approvedby%}
Last approved when: {%approvedwhen%}
Original step: {%originalstepname%}
Current step: {%currentstepname%}
Comment:
{%comment%}
Most templates contain macro expressions (such as {% currentstepname %}), which the system resolves dynamically when sending the emails. The use of macros is necessary to ensure that individual emails contain information relevant to the situation that caused the email to be sent. You can add macros into fields by clicking Insert macro ( ) or write the required expressions manually.
If you wish to display data loaded via a macro in a specific format, you can apply transformations. See Using transformations in macro expressions for more information.
You can attach files to an email template through the Attachments button in the header of the template editing page. The attachments are included when the system sends out emails based on the given template. Clicking the button opens a dialog where you can manage the attachments.
Working with widget dashboards Widget dashboards are sections of the Kentico administration interface that individual users can customize. Typically, users personalize their dashboards to contain frequently used tools or sources of information. The dashboard then serves as an overview that users can easily access without navigation through the administration interface.
Important: Widget dashboards are a completely separate feature from the system's main application dashboard. Every widget dashboard is either a standalone application, or a page within another application.
The content and structure of widget dashboards is based on page templates. The template designates:
The parts of the dashboard that are always present and cannot be changed by users Customizable areas (zones) and their default content
Users place content onto dashboards using widgets. The widget content is distinct for every user. Most dashboards also have unique content for each site.
By default, the system provides the following widget dashboard applications and pages:
My desk System overview (content shared for all sites) Store overview Store reports -> Dashboard Marketing overview Web analytics -> Dashboard
If required, you can create your own widget dashboard applications or pages anywhere in the administration interface (see Adding widget dashboards to the interface).
Managing widget dashboard content
Important: Widget dashboards are a completely separate feature from the system's main application dashboard. Every widget dashboard is either a standalone application, or a page within another application.
Using widgets on dashboards
If you have access to a widget dashboard application or page, you can personalize the content by manipulating widgets in the available zones:
Click Add new widget to add new widget instances Click Reset widgets to return all zones and their widget content to the default state
Individual widgets are enclosed in containers with a header and a set of action buttons. To manage the widgets on the dashboard, use the appropriate actions.
Configure widget ( ) - allows you to edit the widget's properties. Every widget has its own set of properties. The Widget title prop erty is present for all types of widgets — the property sets the text displayed in the header of the widget on the dashboard page. Minimize widget ( ) - hides the content of the widget so that only the header is visible. Click Maximize widget ( ) to restore the full content of the widget. Remove widget ( ) - deletes the widget from the dashboard.
Use drag-and-drop to change the location of widgets. To pick up a widget, hover over its header, hold down the mouse button and drag the widget to the desired position. This works both for modifying the order of widgets within a zone and moving widgets to a different zone.
Setting the layout and default content of widget dashboards
The overall design and initial content of a dashboard is determined by its page template. You can manage dashboard templates in the Page templates application. The templates of the default dashboards are in the Dashboard pages category.
Note: Dashboard templates must have the Template type property set to Dashboard page on the General tab.
Set up the actual content of the template on the Design tab:
You can define two types of zones on dashboard templates: Web part zones - the content can only be managed here on the Design tab of the page template. The added web parts fun ction as fixed content on the dashboard page itself. The Widget zone type property of these zones must be set to None. Dashboard widget zones - widgets added here on the Design tab serve as the default content of the zone. Individual users can change and configure the widget content of the zone for their own personalized version of the dashboard. The Widget zone type property of these zones must be set to Dashboard.
To alter the placement, size and amount of zones on the template, edit the code of the page layout on the Layout tab.
Add the Widget actions web part into the fixed content of every dashboard template. The web part allows users to:
Add new widgets Reset the zones of the dashboard to their default widget content
You need to configure the properties of the Widget actions web part according to the following:
Widget zone type: Dashboard Widget zone ID: Specify the dashboard zone to which the web part adds new widgets (enter the ID of the desired zone). Once created, users can drag widgets to other zone as required. On the Sites tab, you can assign the template to individual websites. The site bindings do NOT determine where you can create dashboards based on the template. They only ensure that the system exports/imports the template along with the assigned sites.
To learn how to assign a page template to a specific dashboard page, see Adding widget dashboards to the interface.
Allowing widgets on dashboards
To make a widget usable as a dashboard component:
1. Open the Widgets application. 2. Select the widget in the catalog tree. 3. Open the Security tab. 4. Select This widget can be used in dashboard zones in the Allowed for column.
Note: The user type security settings of the widget apply on dashboards. Select whether the widget is usable by all Authenticated users, Global administrators only or members of Authorized roles.
If a widget is also allowed for other types of zones, for example user zones on the live site, you can make properties available only when configuring widget instances on dashboards:
1. Open the Properties tab. 2. Check Display field only on dashboards for individual properties. 3. Click Save to confirm the change for each property.
Adding widget dashboards to the interface If the default widget dashboards in the administration interface do not meet your requirements, you can create your own dashboard applications or pages.
Important: Widget dashboards are a completely separate feature from the system's main application dashboard. Every widget dashboard is either a standalone application, or a page within another application.
The following example demonstrates how to add a custom dashboard application to the Social & Community category. You can apply the same principles when creating widget dashboards in other locations.
Creating the dashboard page template
First, create a page template for the dashboard:
1. Open the Page templates application. 2. Select the Dashboard pages category in the tree. 3. Click New template and enter the following values: Template display name: Community dashboard Template code name: CommDashboard
4. Click Save. 5. Select Dashboard page as the Template type. 6. Click Save.
Adjust the layout of the page template:
1. Switch to the Layout tab. 2. Copy the following sample code into the layout to define web part/widget zones for the template: 2.
| | |
| | |
| | |
3. Click Save. 4. Switch to the Design tab. 5. Expand the menu ( ) of the DashboardTop zone and click Configure. 6. Switch the Widget zone type property from None to Dashboard. 7. Click Save & Close. 8. Repeat the steps 5 – 7 for the DashboardLeft and DashboardRight zones.
Add web parts and widgets to the zones:
1. Add the Widget actions web part into the ZoneTop zone. 2. Configure the following properties of the Widget actions web part: Widget zone type: Dashboard Widget zone ID: Leave empty (Designates the zone where new widgets should be created when users click the Add widget button. By default, the web part uses the first available zone (DashboardTop in this case), but you can specify the ID of any other dashboard zone.)
3. Leave the remaining properties in their default state and click OK. 4. Add the Static text web part to the same zone and set the following properties: Text: This is a custom dashboard page Display as: Header level 2
5. Click OK. 6. Expand the menu ( ) of the DashboardTop zone and click Add new widget. 7. For example, choose the Community -> My messages widget. 8. Confirm the dialogs without making changes and leave the other two dashboard zones empty. This sets the default content of the dashboard that individual users can later configure and expand.
Adding the dashboard UI element
To create a new widget dashboard application, you need to add a UI element to the system: 1. Open the Modules application. 2. Edit ( ) the Custom module. Note that the Module code name is cms.customsystemmodule on the General tab. 3. Switch to the User interface tab. 4. Select the CMS -> Administration -> Social & Community element in the tree. 5. Click New element ( ). 6. Enter the following values: Display name: Community overview Code name: CommDashboardElement Module: Custom Caption: Community overview Element icon type: Class Element icon CSS class: icon-app-content-dashboard Type: URL Target URL: ~/CMSGlobalFiles/CommDashboard.aspx?dashboardName=Comm&templateName=CommDashboard&{has h} Sets the URL of the page with the content of the UI element. You will create the source file used in the URL above later in the example. When creating links to dashboard pages, you need to understand and correctly specify the query string parameters: dashboardName - sets a name for the dashboard to ensure uniqueness in cases where multiple dashboards use the same page template. The content of a dashboard is unique for every user. If two or more dashboards share a page template and the dashboardName parameters in the URLs used to access the page have the same value, changes made to one of the dashboards also affect the other dashboards (for the given user and site). templateName - specifies the code name of the page template that the dashboard is based on. The type of the assigned template must be Dashboard page. This example uses the template created in the previous steps. hash - the system automatically generates a hash code for the element
7. Click Save.
When adding applications to the interface of an actual live website, you can set a macro condition in the Content permissions fiel d to define security requirements for access to the application.
The system creates the new UI element.
Creating the dashboard page source file
Now you need to develop the .aspx file of the dashboard page in your web project:
1. Open your website in Visual Studio. 2. Create a New folder under the root called CMSGlobalFiles (if it doesn't already exist). 3. Rightclick the folder and select Add -> Web form. 4. Name the web form CommDashboard. 4.
This is the file specified in the Target URL of the previously created UI element. The location ensures that the system exports the file with any site that includes global folders in the export package. 5. Modify the page code to match the following:
<%@ Page Language="C#" AutoEventWireup="true" CodeFile="CommDashboard.aspx.cs" Theme="Default" EnableEventValidation="false" Inherits="CMSGlobalFiles_CommDashboard" %>
<%@ Register Src="~/CMSModules/Widgets/Controls/Dashboard.ascx" TagName="Dashboard" TagPrefix="cms" %>
<%=DocType%>
>
The Dashboard user control handles the entire functionality of the dashboard. It processes the query string parameters from the URL used to access the page and displays the corresponding dashboard according to the specified dashboard name, page template and contextrelated data such as the current site and user.
6. Switch to the web form's code behind and add the following references to the beginning of the code:
using CMS.Core; using CMS.UIControls; using CMS.SiteProvider;
7. Set the CMSGlobalFiles_CommDashboard class to inherit from DashboardPage. 8. Modify the class to contain the following code: 8.
[UIElement(ModuleName.CUSTOMSYSTEM, "CommDashboardElement")] public partial class CMSGlobalFiles_CommDashboard : DashboardPage { protected override void OnPreInit(EventArgs e) { base.OnPreInit(e);
// Must be equal to the code name of the module containing the corresponding UI element ucDashboard.ResourceName = "cms.customsystemmodule";
// Must be equal to the code name of the corresponding UI element ucDashboard.ElementName = "CommDashboardElement";
ucDashboard.PortalPageInstance = this as PortalPage; ucDashboard.TagsLiteral = this.ltlTags;
// Ensures that the dashboard has unique content for each site ucDashboard.DashboardSiteName = SiteContext.CurrentSiteName;
ucDashboard.SetupDashboard(); }
protected void Page_Load(object sender, EventArgs e) { // Security access checks for the current user }
}
The handler of the PreInit event sets the properties of the Dashboard user control calls and its SetupDashboard() metho d. Note that the values of the ResourceName and ElementName properties must be set according to the module and code name of the UI element created in previous steps of this example.
9. Save both files. If your installation is a web application, Build the CMSApp project.
Result
Users can now access the Community overview application either through the application list or the application dashboard (if you add the application to the roles of users).
The page displays a fully functional dashboard based on the created page template.
Using output filters Output filters modify the HTML code that the system renders for pages on the live site. The filters make changes to the code before sending it to the browsers of visitors. Output filters do not affect the pages of the Kentico administration interface.
Note: Applying output filters adds steps to the processing of pages, and may slow down the website. If the output code of your pages is already valid by default, and you do not need any of the filtering features, we recommend disabling the output filter for your website. See the Applying output filters section for details.
Output filter types
The following types of output filtering are available:
Filter type Description
Form filter The form filter fixes issue with non-working postbacks on pages that use URL rewriting. It ensures that forms, dialogs and buttons work correctly on pages managed by Kentico.
URL resolving filter Resolves relative URLs so that they contain the root URL of the website. For example, the filter changes ~/mypage1/mypage2.aspx to:
/mypage1/mypage2.aspx (if the application is running in the root)
or
/VirtualDirectory/mypage1/mypage2.aspx (when using a virtual directory).
The filter only modifies URLs inside src and href attributes. XHTML filter Fixes XHTML incompatibilities. Specifically, the filtering functionality can ensure the following things:
Valid tag attributes - the attributes of HTML tags are generated in valid XHTML format. JavaScript tags - the type and language attributes are included in all