Vous êtes sur la page 1sur 253

Kentico 8.

1. Configuring Kentico . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1 Managing sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.1 Installing new sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.1.1 Creating new sites using the wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.1.2 Creating new sites from templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.1.3 Creating web templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.2 Setting domain names for sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.3 Managing site licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.4 Setting up multiple websites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.4.1 Running multiple sites on a single domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.4.2 Configuring nested websites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.5 Switching sites to off-line mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6 Configuring settings for sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.1 Settings - Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.1.1 Settings - Content management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.1.2 Settings - Media . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.1.3 Settings - Blogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.1.4 Settings - Translation services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.2 Settings - URLs and SEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.3 Settings - Security & Membership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.3.1 Settings - Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.3.2 Settings - Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.3.3 Settings - Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.4 Settings - System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.4.1 Settings - Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.4.2 Settings - E-mails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.4.3 Settings - Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.4.4 Settings - Health monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.4.5 Settings - Output filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.4.6 Settings - Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.4.7 Settings - Debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.5 Settings - On-line marketing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.5.1 Settings - Contact management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.5.2 Settings - Newsletters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.5.3 Settings - Web analytics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.6 Settings - E-commerce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.6.1 Settings - Global objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.6.2 Settings - Authorize.NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.6.3 Settings - PayPal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.7 Settings - Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.7.1 Settings - Forums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.7.2 Settings - Message boards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.7.3 Settings - Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.7.4 Settings - Avatars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.7.5 Settings - Chat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.8 Settings - Social media . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.8.1 Settings - Facebook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.8.2 Settings - Google+ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.8.3 Settings - LinkedIn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.9 Settings - Social marketing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.9.1 Settings - URL shorteners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.10 Settings - Intranet & Collaboration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.10.1 Settings - Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.10.2 Settings - Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.11 Settings - Versioning & Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.11.1 Settings - Staging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.11.2 Settings - Object versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.11.3 Settings - Web farm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.12 Settings - Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.12.1 Settings - Integration bus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.12.2 Settings - Microsoft SharePoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.12.3 Settings - REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.12.4 Settings - WebDAV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.12.5 Settings - Data.com . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.12.6 Settings - Salesforce.com . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.12.7 Settings - 51Degrees.mobi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.6.12.8 Settings - Strands Recommender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Managing files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.1 Storing files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2 Importing files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.3 Uploading files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.4 Resizing images on upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.5 Administering files globally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.6 Editing file metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 Configuring page URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.1 URL format and configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.2 Setting page aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5
6
7
7
8
10
11
12
12
16
17
18
19
21
22
24
24
25
27
30
33
34
35
37
39
42
43
44
45
46
46
52
52
57
58
60
63
63
63
64
65
66
66
66
67
70
70
71
71
71
72
72
72
72
73
73
73
74
75
75
75
76
77
77
77
78
78
79
80
82
84
85
86
88
88
91
93

1.3.3 Wildcard URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


1.3.4 Custom and extensionless URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.4.1 Troubleshooting custom and extensionless URL configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.5 Linking pages and files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.6 Custom handling of URL path values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4 Search engine optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.1 Configuring websites for SEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2 Google Sitemaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.3 Managing robots.txt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5 Optimizing website performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.1 Loading data efficiently . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.2 Configuring caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.2.1 Caching page output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.2.1.1 Using output cache substitutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.2.2 Caching files and resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.2.3 Caching the data of page components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.2.4 Setting cache dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.2.5 Debugging cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.2.6 Reference - Cache settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3 Using code minification and compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4 Setting up a web farm environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.1 Web farm synchronization mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.2 Defining web farm servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.4.3 Debugging web farms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6 Setting up search on your website . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.1 Enabling search indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.2 Creating search indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.2.1 Defining page indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.2.2 Defining forum indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.2.3 Defining custom table indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.2.4 Defining on-line form indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.2.5 Defining user indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.2.6 Defining general indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.3 Monitoring search indexing tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.4 Adding search functionality to pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.4.1 Setting up predictive search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.5 Configuring search assistance features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.6 Searching attachment files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.6.1 Configuring SQL search for attachment files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.7 Using search filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.8 Smart search syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.9 Displaying search results using transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.10 Searching according to page permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.6.11 SQL search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7 Scheduling tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.1 Configuring scheduled task execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.2 Installing the Scheduler Windows service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.7.3 Reference - scheduled task properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8 Configuring SMTP servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.8.1 Reference - SMTP server properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9 Managing e-mail templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.10 Working with widget dashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.10.1 Managing widget dashboard content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.10.2 Adding widget dashboards to the interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.11 Using output filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.12 Configuring time zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.12.1 Managing time zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13 Working with object versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.1 Using object versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.2 Objects recycle bin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14 Creating alternative forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.1 Code names of automatically used alternative forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.2 Displaying filters using alternative forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.15 Health monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.15.1 Registering performance counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.15.2 Installing the Health monitoring Windows service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.15.3 Enabling health monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.15.4 Monitoring using the Performance monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.15.5 Reference - default performance counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.16 Adding cookie law consent to web pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.16.1 Cookie levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.16.2 Reference - Kentico cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.17 Banning IP addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.18 Configuring countries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.19 Working with system reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.19.1 Creating reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.19.2 Creating report categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

94
95
98
99
100
102
103
106
110
112
114
116
118
121
123
124
125
127
129
133
135
136
136
139
140
141
142
145
150
151
152
153
155
156
157
159
163
166
168
171
174
175
176
176
177
177
179
181
182
185
186
187
188
190
195
198
200
201
203
204
205
206
206
208
209
211
212
213
215
216
217
218
221
222
223
223
237

1.19.3 Defining report parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


1.19.4 Storing data from reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.19.5 Displaying reports on websites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.19.6 Subscribing to reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.19.7 Example - creating a simple report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.19.8 Reporting security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.20 Configuring Windows Communication Foundation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.21 Configuring the administration interface URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.22 Configuring the code editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

237
239
239
239
243
247
249
251
251

Configuring Kentico
Configure the
environment for
content editing

Configure the
system
Sites

Workflows
Workflows define the
life cycles of pages.
Learn how to create
them and apply them to
pages.

Whether you run one or


multiple sites, it is
useful to know how to
manage sites in the
system. Learn how to in
stall new sites, add site
licenses, set domain
names, and more.

Page versioning
Configure versioning of
pages with or without a
workflow. Set up lockin
g of pages for
collaborative editing.

Media libraries
Configure custom
storage for media
libraries, custom file
types or maximum file
upload size.

WYSIWYG editor
Configure and
personalize the
WYSIWYG editor for
content editors.

On-site editing
Allow content editors to
adjust page content on
websites directly while
viewing the website in a
live mode.

Enable content editors


to receive notification
messages when pages
are created, updated or
deleted.

WebDAV
Enable the content
editors to
collaboratively edit files
stored on remote
servers using the client
applications (e.g., using
Microsoft Word)
installed on their local
computers.

Performance
optimization
Learn which aspects
affect the performance
of your websites and
what can you do to
improve the
performance. Setting up
web farms can also
provide load balancing
for your website.

Files
Explore the ways of
storing files in Kentico.
Choose whether to stor
e files in the database
or the file system, uploa
d multiple files to your
websites, set up image
resizing on upload.

Search engine
optimization (SEO)
Help your website be
visible in search
engines like Google.

Output filters
Page URLs
Learn how to set the
URLs for web pages in
Kentico. Adjust your
URLs so that they do
not have extensions.

The output filters


enable the system to
automatically adjust the
HTML code of pages
before sending the
code to browsers.

Health monitoring
Website search
The system provides
built-in, index-based
search functionality. En
able search indexing, cr
eate search indexes an
d add Smart search
web parts to your site.

SMTP servers
Content notifications

Optimize your
website

Connect the system to


SMTP servers to allow
Kentico to send out
e-mails.

E-mail templates
Create and manage
templates for e-mails,
which are automatically
sent by the system.

Scheduled tasks
Learn how to configure
the system to
periodically perform
tasks.

Set up performance
monitoring for your
application. This can
help you find
bottlenecks in the
system.

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.
2.
3.
4.

Select the Users sub-tab.


Click Add users.
Select the users that you want to add to the site.
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 <web project>\<site name>\files folder).
Delete meta files physical files - if checked, the deletion process removes the site's meta files (stored in the <web
project>\<site name>\metafiles folder).
Delete media files physical files - if checked, the deletion process removes physical files stored in the site's media
libraries (<web project>\<site name>\media folder).
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 website template.
Create a new site using a wizard - creates a new blank site.
Use website 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 website template in the first step.
Custom templates
You can create your own web templates from existing sites.

Step 2 - Choose website template


You can choose from a number of website templates:
Corporate site is a typical web presentation of a company.
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 website 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 checked, all imported site related objects will be assigned to the
imported site.
Run the site after import - if checked, the system attempts to start the new site immediately after the import is finished.
Delete incomplete site when import fails - if checked, 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 checked, 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,
payment options, integration connectors, scheduled tasks and smart search indexes 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 checked, 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 checked, the import process includes site-related files originally exported from the following folders:
~/App_Code/<site code name>/
~/App_Data/<site code name>/
~/<site code name>/
~/Controllers/<site code name>/
~/Views/<site code name>/

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.
4.
5.
6.
7.
8.

Create a new folder for your web template.


Add a sub-folder named Data.
Extract the content of your site's export package into the Data folder.
Log into the Kentico administration interface and open the Web templates application.
Click New web template.
Enter the following details:
Display name - the name of the web template displayed in the new site wizard.

8.

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\<y
our folder>
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
website 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.
3.
4.
5.

Edit ( ) your site.


Select the Domain aliases tab.
Click New domain alias.
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.
3.
4.
5.

Edit ( ) your site.


Select the Domain aliases tab.
Edit your aliases.
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 administrators 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

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.

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

mysite.com
www.mysite.com
mysite2.com
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 <appSettings> section of the web.config file in the installation directory shared by both websites:

<add key="CMSWebFarmEnabled" value="true"/>


<add key="CMSWebFarmSynchronizeFiles" value="false" />
<add key="/mykenticoweb/web1:CMSWebFarmServerName" value="server1" />
<add key="/mykenticoweb/web2:CMSWebFarmServerName" value="server2" />

This enables web farms in general and disables 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.
3.
4.
5.

Log in to the Kentico administration interface on one of the sites.


Open the Web farms application.
Create a web farm server for each application.
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:

<add key="/mykenticoweb/web1:CMSSearchIndexPath"
value="App_Data\CMSModules\SmartSearch\Web1\" />
<add key="/mykenticoweb/web2:CMSSearchIndexPath"
value="App_Data\CMSModules\SmartSearch\Web2\" />

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.

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.

<system.webServer>
<validation validateIntegratedModeConfiguration="false" />
<modules>
// remove or comment out all keys in this section
</modules>
<handlers>
// remove or comment out all keys in this section
</handlers>
</system.webServer>

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 <microsoft.web.services3> section.
You need to remove the whole <microsoft.web.services3> section from the web.config of the nested web project (Web2).
Do not remove the section from the Web1 (outer) project, since both websites will use this configuration.
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.

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.
2.
3.
4.
5.

Select a category in the Settings application.


Choose (global) in the Site selector above the settings tree.
Click Reset these settings to default.
Click OK in the confirmation dialog.
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: <site code name>.<settings key code name>
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.<settings key code name>
For example:

{% Settings.CMSStoreFilesInFileSystem %}

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
Metadata

Alias path of the website's default page.

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


<span> 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://<domain>/<virtual directory>/cmsedit

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<some@something.com> format.

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/<file guid>/<file name>.<file extension>.<files
friendly URL extension>), otherwise direct path to the file will be
used (e.g.: ~/MySite/Media/MyLibrary/MyImage.jpg).

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: ~/<site code
name>/media

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. <custom media libraries folder>/<site code name>. It is
useful for better orientation in files when multiple sites are running
in the system.

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:
<file name>_<file extension><thumbnail suffix>.<thumbnail
extension>

HTML5 support
Render HTML5 media tags

If enabled, the system renders HTML5 <audio> and <video> tags


for media content.

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 e-mails from

E-mail address that will be used as the Sender ('From') address of


notification e-mails.

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 e-mail.

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 e-mail confirmation should be sent to users after


they approve a subscription. If double opt-in is disabled, these
confirmation e-mails 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: utf8

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/<node alias>/myimage.aspx
If empty, the file URLs end with no extension: getfile/<node
alias>/myimage

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 <website domain>/robots.txt URL
is requested.

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: <doma
in>/default.aspx
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: <domain>/en-US/Home.aspx

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 e-mail

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 will only have to be unique for each site,
not globally, meaning that it will be 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 unique identifier
(GUID) of the given site will internally be added 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 e-mail (


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)

Content

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

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 <connectio
nStrings> section of the application's web.config file. The (default)
option represents the CMSConnectionString added by the
application's initial database installer.
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 don't 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

Indicates if events are logged to the file system. Doesn't overwrite


Event 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

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 checked, file requests are redirected to the corresponding


physical file (if the requested file is stored in the file system).

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, the system only saves the output cache in the application
memory. If you enter a value, the system checks both types of
output 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.

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["<stylesheetn
ame>"]%}
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 - E-mails
General
E-mail encoding

Sets the character encoding used for e-mails 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 e-mails.

E-mail format

Format used for e-mail messages. You can choose between HTML
and Plain text. If Both is selected and an e-mail template has both
formats defined, HTML will be used for the e-mail text and plain
text will be included as an attachment.

E-mail processing
Enable e-mails

If checked, e-mail sending will be enabled. You can temporarily


disable sending of e-mails by clearing this check-box, e.g. when
performing administration tasks.

Enable e-mail queue

If checked, an e-mail queue will be used when sending e-mails.


This allows advanced email processing and automatic resending of
mails that are lost due to errors. If disabled, e-mails 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 (newsletters
or other types of mass emails).

Batch size

Sets the maximum number of e-mails that can be transferred from


the e-mail queue to an SMTP server in one batch. If the specified
value is smaller than the total amount of e-mails to be sent from the
queue, a new batch is prepared and assigned to the next available
server. This process is repeated until all e-mails 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 e-mails (days)

Sent e-mails will be stored by the e-mail queue for the number of
days specified here. Such emails may be viewed in the E-mail
queue application on the Sent e-mails tab.
If set to 0, e-mails 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 ~/<site
code name>/files.

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. <custom form files folder>/<site code name>. It
is useful for better orientation in files when multiple sites are
running in the system.

Custom form files folder

Folder where files uploaded via Forms 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 files are stored in ~/<site code
name>/BizFormFiles.

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. <custom BizForm files folder>/<site code name>. It is
useful for better orientation in files when multiple sites are running
in the system.

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

The behavior of the system when uploading images depends on


which values you fill in these fields:
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 so that aspect ratio is preserved.
Both width and height - images are resized so that the larger
dimension matches the respective entered value. Aspect ratio
is 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.
You can find more info in the Resizing images on upload chapter.

Watermark
Watermark image

Image name or path that will be used for watermarking images.


User either a full path (~/..) or just a file name from the ~/App_The
mes/Default/Images/Watermarks folder.

Watermark position

The position where the image 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 checked, the watermark is used for page attachments.

Use watermark for media files

If checked, the watermark is used for media files.

Use watermark for object attachments

If checked, the watermark is used for object attachments.

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 <script> tags.

Excluded XHTML lower case filter URLs

Specifies the URL paths of the pages that should be excluded from
the Lower case XHTML filter, which ensures that all HTML tags
and attributes are generated in lower case.

Excluded XHTML self close filter URLs

Specifies the URL paths of the pages that should be excluded from
the Self closing tag XHTML filter, which ensures that all HTML
elements without closing tags are properly closed, e.g. <br> will be
replaced by <br />.

Excluded HTML 5 filter URLs

Specifies the URL paths of the pages that should be excluded from
the HTML5 output filter.
This filter replaces tag attributes that are obsolete in HTML5. Such
attributes are removed and the system instead assigns CSS
classes named in format <attribute name>_<attribute value>.
These classes need to be defined in the CSS stylesheet used by
the website's pages.
The affected attributes are: cellpadding, cellspacing, width, height,
border, align, valign
For example:
<table cellpadding="2" cellspacing="4">
would be replaced by:
<table class="cellpadding_2 cellspacing_4">

Indent output HTML

Indicates if the HTML output of pages should be processed into a


properly indented, easier to read format. This setting is applied to
all pages on which the XHTML output filter is enabled.

Convert TABLE tags to DIV tags

Determines which <table> elements (and their child <tr> and <td> t
ags) should be converted to <div> elements by the output filter.
The system automatically assigns CSS classes to the replacement
Div tags according to the name of the original tag. The classes
need to be defined in the CSS stylesheet used by the website's
pages.
This behavior can either be disabled completely, enabled for all
tables except for those marked by the _nodivs CSS class, or only
enabled for the tables designated through the _divs class.

Settings - Search
On this page you can configure settings related to the search engine on your websites.
Search
Exclude page types from SQL search

Specifies the page types that the system does NOT search when
using SQL search. You can specify multiple page types separated
by semicolons (;).

Exclude pages from SQL search

Specifies site sections that the system does NOT search when
using SQL search.
Use path expressions to identify site sections or individual pages.
You can enter multiple paths separated by semicolons (;).

Enable smart search indexing

Indicates if smart search indexing is enabled. This setting is only


available if (global) is selected in the Site drop-down list, not for
individual sites.

Allowed attachment file types

Specifies which file types are included when searching page


attachments. The smart search indexes the content of attachments
along with the related pages. Only applies to Page indexes that
have the Include attachment content option enabled for their
allowed content.
By default, the system can extract content for the following file
types: xml, txt, csv, html, htm, pdf, docx, xlsx, pptx
Enter the allowed file types as file extensions without dots,
separated by semicolons. If you leave the setting empty, all
available file types are allowed.

Settings - Debug
On this page, you can configure settings of the system's debugging tools. The following categories of settings are available:
General
All
Cache access
SQL queries
IO
Page ViewState
Output

Security
Macros
Analytics
Requests
Web farm
Event handlers

General
Setting

Description

Disable debugging

Globally disables all debugs, regardless of individual debug


settings.

Debug Import/Export

If disabled, the system does not log debug information for the
pages of the Import/Export interface. For performance reasons, it is
recommended to leave this option disabled unless you need to
debug the Import/Export process.

Debug resources

If disabled, the debug ignores all resource requests (GetResource


and GetCSS).

Debug scheduler

If disabled, the debug ignores all operations executed by the sched


uler.

All
Setting
Debug everything everywhere

Description
Enables:
All debug types
Debugging of user interface pages for all debugs
Live site debugging (for all debugs)

Enable all debugs

Enables all debugs and the corresponding tabs in the Debug appli
cation.

Display all debugs on live site

If checked (true), all enabled debugs display their information on


the live site below the regular content of pages.

Include UI pages in all debugs

If checked (true), all enabled debugs include actions performed on


the pages of the user interface.

Default log length

Sets the default maximum length of the debug log in the Debug ap
plication. The default log length is used by debug types that do not
have their own log length set.

Display stack information in every debug

If enabled, the system tracks the code stack for all debug types
and displays the information in the Context column of the debug
interface in the Debug application.

Log everything to file

Enables logging of all possible operations into .log files in the ~/Ap
p_Data/ folder (including the Event log and E-mail sending log).

Cache access
Setting

Description

Enable cache access debug

Enables cache access debugging and the Cache access tab in the
Debug application.

Display cache access debug on live site

If enabled, cache access debug information is also displayed at the


bottom of each live site page. This option requires cache access
debugging to be enabled.

Debug cache access of UI pages

If enabled, access to data cached for pages of the administration


interface will also be included in the cache access debug. This
option requires cache access debugging to be enabled.

Cache access debug log length

Sets the maximum length of the cache access debug log on the De
bug -> Cache access tab, i.e. the number of requests for which
debug information is preserved and displayed on the tab. If empty,
value of the Default log length setting (or the CMSDebugEveryth
ingLogLength key) is used.

Display stack information

If enabled, the system tracks the code stack when debugging


cache access 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 logcache.log file.

Log cache access to file

If enabled, cache access debug log is saved into the logcache.log f


ile in the ~\App_Data folder. This option does not require cache
access debugging to be enabled.

SQL queries
Setting

Description

Enable SQL query debug

Enables SQL query debugging and the SQL queries tab in the De
bug application.

Display SQL query debug on live site

If enabled, SQL query debug information is also displayed at the


bottom of each live site page. This option requires SQL query
debugging to be enabled.

Debug SQL queries of UI pages

If enabled, SQL queries called by pages of the administration


interface will also be included in the SQL query debug. This option
requires SQL query debugging to be enabled.

SQL query debug log length

Sets the maximum length of the SQL query debug log on the Debu
g -> SQL queries tab, i.e. the number of requests for which debug
information is preserved and displayed on the tab. If empty, value
of the Default log length setting (or the CMSDebugEverythingLo
gLength key) is used.

Debug SQL connections

If enabled, SQL connection operations (new, open, close) are


logged in the SQL query debug log.

Display stack information

If enabled, the system tracks the code stack when debugging SQL
queries 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 logsql.log file.

Log SQL queries to file

If enabled, SQL query debug log is saved into the logsql.log file in
the ~\App_Data folder. This option does not require SQL query
debugging to be enabled.

IO
Setting

Description

Enable IO operation debug

Enables IO operation debugging and the IO tab in the Debug appli


cation.

Display IO operation debug on live site

If enabled, IO operation debug information is also displayed at the


bottom of each live site page. This option requires IO operation
debugging to be enabled.

Debug IO operations of UI pages

If enabled, IO operations called by pages of the administration


interface will also be included in the IO operation debug. This
option requires IO operation debugging to be enabled.

IO operation debug log length

Sets the maximum length of the IO operation debug log on the Deb
ug -> IO tab, i.e. the number of requests for which debug
information is preserved and displayed on the tab. If empty, value
of the Default log length setting (or the CMSDebugEverythingLo
gLength key) is used.

Display stack information

If enabled, the system tracks the code stack when debugging IO


operations 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 logfiles.log file.

Log IO operations to file

Page ViewState

If enabled, IO operation debug log is saved into the logfiles.log file


in the ~\App_Data folder. This option does not require IO operation
debugging to be enabled.

Setting

Description

Enable ViewState debug

Enables ViewState debugging and the Page ViewState tab in the


Debug application.

Display ViewState debug on live site

If enabled, ViewState debug information is also displayed at the


bottom of each live site page. This option requires ViewState
debugging to be enabled.

Debug ViewState of UI pages

If enabled, ViewState of administration interface pages will also be


included in the ViewState debug. This option requires ViewState
debugging to be enabled.

ViewState debug log length

Sets the maximum length of the ViewState debug log on the Debu
g -> ViewState tab, i.e. the number of requests for which debug
information is preserved and displayed on the tab. If empty, value
of the Default log length setting (or the CMSDebugEverythingLo
gLength key) is used.

Output
Setting

Description

Enable output debug

Enables page output debugging and the Output tab in the Debug
application.

Debug output of UI pages

If enabled, output of administration interface pages will also be


included in the output debug. This option requires output
debugging to be enabled.

Output debug log length

Sets the maximum length of the output debug log on the Debug ->
Output tab, i.e. the number of requests for which debug
information is preserved and displayed on the tab. If empty, value
of the Default log length setting (or the CMSDebugEverythingLo
gLength key) is used.

Log output to file

If enabled, output debug log is saved into the logOutput.log file in


the ~\App_Data folder. This option does not require output
debugging to be enabled.

Security
Setting

Description

Enable security debug

Enables security operation debugging and the Security tab in the


Debug application.

Display security debug on live site

If enabled, security operation debug information is also displayed


at the bottom of each live site page. This option requires security
debugging to be enabled.

Debug security operations of UI pages

If enabled, security checks performed by pages of the


administration interface will also be included in the security debug.
This option requires security debugging to be enabled.

Security debug log length

Sets the maximum length of the security debug log on the Debug
-> Security tab, i.e. the number of requests for which debug
information is preserved and displayed on the tab. If empty, value
of the Default log length setting (or the CMSDebugEverythingLo
gLength key) is used.

Display stack information

If enabled, the system tracks the code stack when debugging


security 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 logSecurity.log file.

Log security operations to file

If enabled, security debug log is saved into the logSecurity.log file


in the ~\App_Data folder. This option does not require security
debugging to be enabled.

Macros
Setting

Description

Enable macro debug

Enables macro debugging and the Macros tab in the Debug applic
ation.

Enable detailed macro debug

If enabled, the macro debug displays the results of all subelements


used within macro expressions. This allows you to check the exact
data content of a macro's components during each step of the
resolving process.
Detailed macro debugging is highly recommended if you encounter
problems with complex expressions. If disabled, the debug only
shows the final result of each macro.
You can enable the detailed debug only for specific expressions by
adding the |(debug) parameter to the given macro.

Display macro debug on live site

If enabled, macro debug information is also displayed at the bottom


of each live site page. Macro debugging must also be enabled.

Debug macros resolved on UI pages

If enabled, macros resolved on the pages of the administration


interface are also included in the macro debug. Macro debugging
must also be enabled.

Macro debug log length

Sets the maximum length of the macro debug log, i.e. the number
of requests for which the macro debug stores information. If empty,
the value of the Default log length setting (or the CMSDebugEver
ythingLogLength key) is used.

Display stack information

If enabled, the system tracks the code stack when debugging


macros 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 logmacros.log file.

Log macros to file

If enabled, the system saves the macro debug log into the logmacr
os.log file in the ~\App_Data folder. Macro debugging must also be
enabled.

Analytics
Setting

Description

Enable web analytics debug

Enables web analytics debugging and the Analytics tab in the Deb
ug application.

Display web analytics debug on live site

If enabled, web analytics debug information is also displayed at the


bottom of each live site page. This option requires web analytics
debugging to be enabled.

Web analytics debug log length

Sets the maximum length of the web analytics debug log on the De
bug -> Analytics tab, i.e. the number of requests for which debug
information is preserved and displayed on the tab. If empty, value
of the Default log length setting (or the CMSDebugEverythingLo
gLength key) is used.

Display stack information

If enabled, the system tracks the code stack when debugging web
analytics 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 loganalytics.log file.

Log web analytics to file

If enabled, web analytics debug log is saved into the loganalytics.lo


g file in the ~\App_Data folder. This option does not require web
analytics debugging to be enabled.

Requests
Setting

Description

Enable request debug

Enables request debugging and the Requests tab in the Debug ap


plication.

Display request debug on live site

If enabled, request debug information is also displayed at the


bottom of each live site page. This option requires request
debugging to be enabled.

Debug UI page requests

If enabled, administration interface page requests will also be


included in the macro debug. This option requires request
debugging to be enabled.

Request debug log length

Sets the maximum length of the request debug log on the Debug
-> Requests tab, i.e. the number of requests for which debug
information is preserved and displayed on the tab. If empty, value
of the Default log length setting (or the CMSDebugEverythingLo
gLength key) is used.

Display stack information

If enabled, the system tracks the code stack when debugging


requests 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 logRequests.log file.

Log requests to file

If enabled, request debug log is saved into the logRequests.log an


d logRequestsUrls.log files in the ~\App_Data folder. The first file
contains the full log, while the second one only lists requested
URLs. This option does not require request debugging to be
enabled.

Web farm
Setting

Description

Enable web farm debug

Enables request debugging and the Web farm tab in the Debug ap
plication.

Debug web farm operations of UI pages

If enabled, operations performed via the administration interface


will also be included in the web farm debug. This option requires
web farm debugging to be enabled.

Web farm debug log length

Sets the maximum length of the web farm debug log on the Debug
-> Requests tab, i.e. the number of requests for which debug
information is preserved and displayed on the tab. If empty, value
of the Default log length setting (or the CMSDebugEverythingLo
gLength key) is used.

Display stack information

If enabled, the system tracks the code stack when debugging web
farm operations and displays the information in the Context colum
n.
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, web farm debug log is saved into the logwebfarm.log fil
e in the ~\App_Data folder. This option does not require web farm
debugging to be enabled.

Event handlers
Setting

Description

Enable handlers debug

Enables event handlers debugging and the Event handlers tab in


the Debug application.

Display handlers debug on live site

If enabled, event handlers debug information is also displayed at


the bottom of each live site page. This option requires event
handlers debugging to be enabled.

Debug handlers in UI pages

If enabled, operations performed via the administration interface


will also be included in the event handlers debug. This option
requires event handlers debugging to be enabled.

Handlers debug log length

Sets the maximum length of the event handlers debug log on the D
ebug -> Event handlers tab, i.e. the number of requests for which
debug information is preserved and displayed on the tab. If empty,
value of the Default log length setting (or the CMSDebugEveryth
ingLogLength key) is used.

Display stack information

If enabled, the system tracks the code stack when debugging event
handlers 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 handlers to file

If enabled, event handlers debug log is saved into the logwHandler


s.log file in the ~\App_Data folder. This option does not require
event handlers debugging to be enabled.

Settings - On-line marketing


On-line Marketing
Enable on-line marketing

Indicates if on-line marketing should be enabled. This includes the


following functionality:
Tracking of users on the live site as contacts. If the setting is
disabled, users can still work with existing contacts in the
administration interface.
Logging of on-line marketing activities.
Newsletter marketing features, i.e. e-mail tracking, A/B testing
and bounced mail monitoring.

Optimization
Enable A/B testing

Indicates if A/B testing is allowed for pages.


A/B testing allows you to define different variants of pages. When a
visitor views the tested page on the live site for the first time, the
system randomly displays one of the variants. From that point, the
visitor's activity on the website is logged and categorized under the
given variant.
In order to work correctly, A/B testing additionally requires the Ena
ble web analytics and Track conversions settings to be enabled
in Settings -> On-line marketing -> Web analytics.

Enable multivariate testing

Indicates if multivariate testing (MVT) is enabled. This allows you to


define MVT tests for pages and create different variants of their
content. Once the test is running, the system assigns one of the
possible content combinations to visitors who access the page on
the live site. From that point, the visitor's activity on the website is
logged and categorized under the given MVT combination.
In order to work correctly, multivariate testing additionally requires
the Enable web analytics and Track conversions settings to be
enabled in Settings -> On-line marketing -> Web analytics.

Content personalization
Enable content personalization

Indicates if content personalization is enabled. This allows page


designers (and content editors) to create different variants of web
parts, entire web part zones or editor widgets. The system displays
the variants to users on the live site according to dynamically
resolved conditions.

Settings - Contact management


On this tab you can configure settings related to contact management.
General
Log IP addresses

Indicates if logging of IP addresses is allowed.

Remember contacts permanently

Indicates how long contacts are remembered. If checked, a contact


is kept until cookies are deleted or another contact is determined.
Otherwise, contacts are kept until the current session expires.

Automatically recognize visitors by user agent

Indicates if browser user agent information are used to determine


what contact is assigned to the current anonymous visitor.

Automatically recognize visitors by IP address

Indicates if IP addresses are used to determine what contact is


assigned to the current anonymous visitor.

Notes stamp format

Defines the format of the stamps that can be added to account or


contact notes.

Settings - Activities

General
Log activities

If enabled, activities are logged for the website (according to the


other settings in this category).

Track file downloads (cms.file) for these extensions

The system can track file downloads as Page visit activities for files
stored as CMS.File pages in the content tree of a website. This
setting specifies which types of files the tracking includes.
Enter the allowed file types as a list of extensions separated by
semicolons, for example: pdf;docx;png
If left empty, the system tracks all file types.

Page
Page visits

If enabled, the page visit activity is logged.

Landing page

If enabled, the landing page activity is logged. A landing page is


where the visitor comes first when viewing the website.

Membership
User registration

If enabled, the user registration activity is logged.

User login

If enabled, the user login activity is logged.

Joining a group

If enabled, the joining a group activity is logged.

Leaving a group

If enabled, the leaving a group activity is logged.

E-commerce
Customer registration

If enabled, the customer registration activity is logged.

Adding a product to shopping cart

If enabled, the activity of adding a product to the shopping cart is


logged.

Removing a product from shopping cart

If enabled, activity of removing a product from the shopping cart is


logged.

Adding a product to wishlist

If enabled, the activity of adding a product to wishlist is logged.

Purchase

If enabled, an activity is logged when a contact makes a purchase


on the website (one record for the entire purchase).

Purchased product

Indicates if an activity is logged individually for every purchase of a


product.

Newsletter
Subscription

If enabled, the newsletter subscription activity is logged.

Unsubscrption

If enabled, the newsletter unsubscription activity is logged.

E-mail opening

If enabled, the newsletter e-mail opening activity is logged.

Clickthrough tracking

If enabled, the activity of user's clicking a particular hyperlink in an


e-mail is logged.

Search
Search

If enabled, the internal search activity is logged (the site visitor


uses a standard search webpart).

External search

If enabled, the external search activity is logged (the site visitor


uses an external search engine that leads them to the website).

Subscriptions
Blog post subscription

If enabled, the blog post subscription activity is logged.

Blog post comments

If enabled, the activity of visitor's adding a new comment to a blog


post is logged.

Forum post subscription

If enabled, the forum post subscription activity is logged.

Forum posts

If enabled, the activity of visitor's adding new forum posts is logged.

Message board subscription

If enabled, the message board subscription activity is logged.

Message board posts

If enabled, the activity of visitor's adding new message board posts


is logged.

User contributions
Creation of a new page

If enabled, the activity of creating a new page is logged.

Update of existing page

If enabled, the activity of updating an existing page is logged.

Deletion of existing page

If enabled, the activity of deleting an existing page is logged.

Chat
Requesting support

If enabled, an activity is logged when a contact requests chat


support.

Requesting support using offline form

If enabled, an activity is logged when a contact submits a support


request via e-mail (this option is offered when no one from the chat
support staff is online).

Accepting initiated chat request

If enabled, an activity is logged when a contact accepts a chat


request initiated by website personnel.

Accepting automatically initiated chat request

If enabled, an activity is logged when users accept automatically


initiated chat requests.

Other
On-line form submission

If enabled, the activity of submitting an on-line form will be logged.

Content rating

If enabled, the content rating activity is logged.

Poll voting

If enabled, the activity of poll voting is logged.

Abuse report

If enabled, the abuse report activity is logged.

Custom table form submit

If enabled, the activity after submitting custom table form is logged.

Event booking

If enabled, the activity of event booking, i.e. attendee's subscribing


to an event, is logged.

Custom activities

If enabled, custom activities are logged.

Settings - Global data & merging


Global data
Allow global contacts

Enables the use of global contacts on the website.

Automatically create global contact for user

If enabled, the system creates new global contacts when it detects


that there are multiple contacts associated with a user registered
on multiple websites in the system.
The site-specific contacts are merged into the global contact.
If one of the detected contacts is already global, the system
directly merges the other contacts into it instead of creating a
new contact.

Automatically create global contact for visitors with identical e-mail


addresses

If there are users with the same e-mail address across multiple
websites, the system creates a global contact for all site contacts
associated with the given user.

When choosing from global contacts, select

Indicates which contact the system uses as the primary contact for
site visitors who have multiple global contacts assigned. The
following options are available:
Last modified - the contact that was most recently modified.
First created - the oldest contact.
Create a new contact - the system creates a new contact and
merges the other global contacts into it.

Allow global accounts

Enables the use of global accounts on the website.

Allow global contact groups

Enables the use of global contact groups on the website.

Allow global configuration

Enables the use of global contact statuses, account statuses and


contact roles on the website.

Automatic merging of contacts


Merge contacts for identical Ecommerce customers

If enabled, the system automatically merges contacts that are


associated with the same e-commerce customer.

Merge contacts for identical Newsletter subscribers

If enabled, the system automatically merges contacts that are


associated with the same newsletter subscriber.

Merge contacts with identical e-mail addresses

If enabled, the system automatically merges contacts that have the


same e-mail address.

When a visitor has more contacts, use

Determines which contact the system selects as the parent when


automatically merging:
Last logged contact - the contacts with the most recently
logged activity.
Most active contact - the contact with the highest number of
logged activities.
Create a new contact - the system creates a new contact as
the parent a merges all matching contacts into it.

Note: The system always automatically merges contacts that are associated with the same user account.

Settings - Geolocation
In this category, you can configure the mapping of the Geolocation fields to Kentico contact fields. Use the drop-down lists to select the target
fields into which the system maps the information.
The Area code, Metro code, DMA code, Latitude and Longitude fields don't have equivalent fields in Kentico. To create new fields to map
into:
1.
2.
3.
4.

Navigate to the Modules application.


Edit the Contact management module.
On the Classes tab, edit the Contact management - Contact class.
Define the fields on the Fields tab.

The following settings are available. Mind the type restrictions when assigning target fields or creating custom fields for holding geolocation
data.
General
Enable IP geolocating contacts

Indicates if contacts' locations can be tracked down based on their


IP addresses.

Suffix

Type in an optional suffix, which the system adds to the values of


contact fields obtained using Geolocating. The suffix is only added
to text-based fields.

Geodata mapping
Country

Accepts integer-based and text-based columns. When mapping to


an integer-based column, Country ID is used. Country display
name is mapped into a textbased column.

State

Accepts integer-based and text-based columns. When mapping to


an integer-based column, State ID is used. State display name is
mapped into a textbased column.

City

Accepts text-based columns.

Postal code

Accepts integer-based and text-based columns.

Area code

Accepts integer-based and text-based columns.

Metro code

Accepts integer-based and text-based columns.

DMA code

Accepts integer-based and text-based columns.

Latitude

Accepts decimal-based and text-based columns.

Longitude

Accepts decimal-based and text-based columns.

Organization/ISP (GeoIPOrg required)

Accepts text-based columns. The specified column will only be


updated if the GeoIP Organization Database is installed.

Settings - Inactive contacts

General
Delete inactive contacts

Determines whether the contacts associated with the given site


should be affected when the Delete inactive contacts scheduled
task is executed. This task is used to periodically clear out contacts
(and the activities logged for these contacts) according to certain
conditions. If disabled, the site's contacts will only be removed if
they are deleted manually.
The remaining settings in this category are used to set the
conditions that specify which contacts should be deleted. At least
one condition must be entered in order for any contacts to be
deleted.
If multiple conditions are set, only those contacts that fulfill all
conditions are removed.

Delete condition
Last activity older than (days)

Can be used to delete contacts that do not have any recent


activities logged. Contacts whose latest activity is older than the
specified number of days are removed.
For example, entering 14 means that the task removes all contacts
which do not have any activities logged within the last two weeks.

Contact created before (days)

Can be used to clear out old contacts. All contacts that are older
than the specified number of days are removed.
For example, setting the value to 365 means that the task removes
all contacts created more than a year ago.

Contact last logon before (days)

This condition is only applied to contacts that are not anonymous


(i.e. only those that are associated with a specific user account). It
can be used to delete contacts who have not logged into the
website recently.
For example, entering 31 means that the task removes all contacts
who have not logged in within the last month.

Contact last modified before (days)

Can be used to remove contacts that were not edited recently (e.g.
had their contact address changed). Contacts whose latest
modification is older than the specified number of days are deleted.
For example, entering 31 means that the task removes all contacts
which were not modified within the last month.

Contact merged before (days)

Can be used to delete contacts that were merged into another


contact a certain number of days ago.
A merged contact is one that was combined into another contact,
not the contact which is the actual result of a merge operation.
For example, entering 7 means that the task removes all contacts
which were merged more than one week ago.

Merged into site contact only

Determines whether the task should delete all contacts that were
merged into another contact associated with the given site.
A merged contact is one that was combined into another contact,
not the contact which is the actual result of a merge operation.

Merged into global contact only

Determines whether the task should delete all contacts that were
merged into a global contact.
A merged contact is one that was combined into another contact,
not the contact which is the actual result of a merge operation.

Contact is anonymous

Can be used to choose whether the task should remove all


contacts that are anonymous, or the opposite (those that are
related to a specific user account).
Note: Contacts that are only related to a customer or subscriber
are still considered as anonymous.
The Doesn't matter option is the equivalent of an empty value in
this condition. (i.e. if selected, the task does not delete any
contacts unless at least one other condition is specified).

Custom SQL WHERE condition

Allows you to enter an SQL WHERE condition that determines


which contacts are deleted by the scheduled task.
For example:
(ContactEmail is NULL OR ContactEmail = '')
With this custom condition, the Delete inactive contacts task
removes contacts that have an empty e-mail address (and fulfill all
other delete conditions).

Settings - Newsletters
General
Newsletter unsubscription page URL

Sets the URL of the page where users can unsubscribe from a new
sletter. The Newsletter unsubscription web part must be placed on
the specified page to ensure the required functionality.
The value of this setting is inherited by individual newsletters if their
Unsubscription page URL property is not set. If empty, the ~/CM
SPages/Unsubscribe.aspx default page is used.

Newsletter double opt-in approval page URL

Sets the URL of the page where users can confirm their
subscription to a newsletter with double opt-in enabled. The Subsc
ription approval web part must be placed on the specified page to
ensure the required functionality.
The value of this setting is inherited by individual newsletters if their
Approval page URL property is not set. If empty, the ~/CMSModu
les/Newsletters/CMSPages/SubscriptionApproval.aspx default
page is used.

Double optin interval

Sets the length (in hours) of the time interval during which users
will be allowed to confirm their subscription to a newsletter that
uses double optin. If a user does not activate their subscription
within the specified number of hours, the link in their confirmation
email will expire and become invalid.
The same time limit is also applied to unsubscription requests
submitted through the Unsubscription request web part.

Generate newsletter e-mails if e-mails are disabled

If enabled, newsletter e-mails will be generated and saved into the


E-mail queue even if the sending of e-mails is disabled in Settings
-> System -> E-mails.

Use external service for dynamic newsletters

If enabled, the scheduled tasks that are created to ensure the


mailout of new dynamic newsletters will be set to be processed by
the external scheduling service by default.
Note: this does not change the settings of existing dynamic
newsletter tasks. If you wish to configure these to use the external
scheduler Windows service, you will have to enable their Use
external service property manually in the Scheduled tasks applic
ation (remember to select the appropriate site, these tasks are not
global).

Bounced e-mails
Monitor bounced e-mails

Indicates if bounced e-mails should be tracked for newsletter


subscribers. Bounced e-mails are received whenever there is a
problem with the delivery of a newsletter issue to a subscriber.

Bounced e-mail address

Sets the address to which bounced e-mails are sent when the
delivery of a newsletter issue to a subscriber fails. If set, this
address is used in the From field of newsletter issue e-mails.

Bounced e-mail limit

Sets the amount of bounced e-mails that can be counted for a


subscriber before the system blocks them from receiving further
newsletter issues. This limit is set for all newsletters under the
selected site.
If 0 is entered, subscribers will never be blocked automatically, but
their bounced e-mail count will still be tracked and displayed in the
Newsletters application.

Block subscribers globally

If checked, bounces will be added to all subscribers that have the


same e-mail address. This is applied across all sites in the system.
Note: this setting does not ensure consistency between the
bounce counts of all subscribers with a shared address, only that
new bounces will be added to all of them.
This field is only available when defining global settings, i.e. when
the (global) option is selected from the Site drop-down list.

POP3 settings
Server name

Sets the address of the mail server where the bounced e-mails are
stored. POP3 is used to check the server and monitor bounced
e-mails.

Server port

Specifies the number of the port used to connect to the mail server.

User name

Sets the user name used for authentication against the mail server.

Password

Sets the password used for authentication against the mail server.

Use SSL

Indicates whether the connection to the mail server should be


secured using SSL.

Authentication method

Allows the selection of the authentication method used for the


connection to the mail server. Options include basic user name and
password authentication and several challengeresponse
mechanisms.
The Auto option uses APOP if the server supports it and plain text
user name and password authentication otherwise.

Settings - Web analytics


The settings here allow you to enable or disable tracking of various types of events and specify other related configuration options.
Note: The system checks the values of the settings at the moment that tracked events occur. Changes do not affect previously
logged data, only future events.

General
Enable web analytics

Enables or disables the entire web analytics application. If this


setting is disabled, the system does not track any of the statistics
listed below.

Log via JavaScript snippet

If enabled, the system uses JavaScript to log web analytics and


page-related on-line marketing activities. Otherwise the logging
occurs directly on each request.
JavaScript logging ignores all browsers and devices that do not
support JavaScript or have it disabled. This filters out non-human
tools such as RSS readers and web crawlers from future statistics.
In most cases, it is recommended to use JavaScript logging.
Switching to JavaScript logging does not reduce the performance
of the website.

Campaigns & Conversions


Track campaigns

Indicates if campaign tracking is enabled.

Campaign tracking URL parameter

Sets the name of the URL query string parameter which is used to
indicate that the site was accessed as a result of a campaign. The
value of the parameter stores the code name of the given
campaign.

Track conversions

Indicates if tracking of conversions is enabled. In addition to


general conversion, this setting also applies to the logging of
conversions for A/B or Multivariate tests and Campaigns.

Views & Downloads

Track file downloads

If enabled, the system tracks which files were downloaded by


website visitors.
Important: Web analytics only track files stored as pages in the
website's content tree.

Track invalid pages

Indicates if invalid page requests should be tracked. Invalid


requests are those that contain the website's domain name, but
specify a path to a page that does not exist.

Track page views

Indicates if the web analytics track how many times the website's
pages were viewed by visitors. Only pages that are served by
Kentico are included in the statistics.

Track aggregated views

If enabled, the web analytics track access to pages via links


contained in RSS or Atom feeds (created using the Syndication fun
ctionality).

Track landing pages

Indicates if the web analytics track which pages are the first ones
viewed by visitors when they start their browsing session on the
website.

Track exit pages

If enabled, the web analytics log the final pages that were visited
by users when their browsing session ended.

Track average time on page

If enabled, the web analytics track the average time that users
spend on pages.

Visitors
Track browser types

Indicates if the web analytics track the browser types and versions
used by the website's visitors.

Track visits

Indicates if site visits are tracked. A single visit includes any


number of page views or other actions performed by a specific user
during one session.
First time users are logged as new visits. After a specified time
period of inactivity, known users are logged as returning visits.
Visitors are recognized using a browser cookie.

Visitor idle time (minutes)

Determines how long (in minutes) a visitor must be inactive before


their presence on the website is logged as a returning visit.
The default value is 1380 (23 hours). You can adjust this setting
depending on how often visitors usually return to your site. For
example, to track how frequently your site's visitors return over the
course of a single day, you could set the value to 60 minutes or
less.

Remember visitors by IP (minutes)

If the entered value is higher than 0, the system stores the IP


addresses of the website's visitors in the memory for the specified
number of minutes.
You may use this setting in cases where there are problems
identifying visitors using the standard approach, e.g. if many of
your visitors have cookies disabled in their browser.

Track countries

If enabled, web analytics track the countries from which visitors


access the website.
The countries are recognized according to the IP addresses of
visitors, which may not be 100% reliable in all cases, but the
overall statistics for a high number of visits should provide correct
results.

Track registered users

Enables tracking of user registrations.

Track search crawlers

Indicates whether the web analytics monitor the activity of search


engine web crawlers (robots). This type of tracking is performed
even if the Exclude search engines setting is enabled.
Note: This only includes crawlers whose user agent is specified for
one of the search engines registered in the system. See Monitoring
traffic from search engines for more information.

Track mobile devices

Excluded

If enabled, the web analytics track whether visitors access the


website using mobile devices.

Exclude search engines

If enabled, hits generated by search engine robots (crawlers) are


not included in tracking statistics. This does not affect the Search
crawlers statistic.

Excluded file extensions

Sets which file types should not be tracked as part of the File
downloads statistics. The file types are specified using a list of
extensions separated by semicolons (;), for example: .jpg;.gif
Note: it is necessary to include the period in the extension name.

Excluded URLs

Can be used to exclude websites or their sections from all types of


web analytics tracking. To exclude a page and all underlying
pages, enter its URL (or page alias). You can specify multiple
URLs (or site sections) separated by a semicolon (;).

Excluded IP addresses

Hits generated by the client IP addresses listed here are not


included in web analytics tracking.
You can enter multiple addresses separated by semicolons (;). The
asterisk ( * ) wildcard can be used as a wildcard for any number in
an IP address, substituting for all values from 0 to 255.
This can be used to exclude the IP addresses of the website's
administrators or other special users, so that they do not influence
tracking results.

Traffic sources
Track search engines

Indicates if the web analytics track traffic from search engines.

Track search keywords

Indicates if the web analytics log the keywords that were entered
into search engines in order to find the website.

Track on-site keywords

Indicates if the keywords that were used in the website's local


search functionality should be logged.

Track referring local pages

If enabled, the web analytics track which links visitors use to


navigate within the website (i.e. menus or other types of links
present on the site's pages).

Track referring pages by direct link

If enabled, the web analytics log when the website's pages are
accessed directly through a URL entered into the browser.

Track referring sites

Indicates if the web analytics log the total amount of page views
gained through links from external websites and the statistics for
individual website domains.

Track referrals

Indicates if the web analytics log the full URLs of external pages
from which visitors were linked to the website and the number of
resulting page views.

Settings - E-commerce
Here you can configure the Kentico E-commerce Solution settings.
Products UI
Display tree of product sections

Indicates whether the system displays the tree of product sections


in the products administration UI. If the sections tree is hidden, you
can create only stand-alone SKUs from the products administration
UI. Otherwise, you can create a complete product, i.e. an SKU with
its page representation in the sections tree.

Products starting path

Indicates a path within the content tree where the subtree of


product sections starts, e.g.: /Products. The system displays this
subtree in the products administration UI. The setting has no effect
if the sections tree is hidden.

Display products in sections tree

Indicates if the system displays products in the product sections


tree. The setting has no effect if the sections tree is hidden.

Allow stand-alone SKUs

Indicates whether the users can create stand-alone SKUs (i.e.


SKUs without their page representations in the sections tree). If so,
the system displays the stand-alone SKUs node above the product
sections tree in the products administration UI. The setting has no
effect if the sections tree is hidden.

Products properties

Related products relationship name

Specifies the name of the relationship used when defining related


products. If you leave the default option, i.e. (all), the users can
select from all relationships existing on the current site while
adding related products. This gives them the possibility to use
more than one type of relationship among products.

Products are 'new' for

Specifies the number of days for which the recently added products
are marked as New products in your on-line store. The system
counts the days based on the products' In store from property.

Public status for 'new products'

Specifies a product public status indicating that this product is new


in your on-line store. The system can mark any product with this
status automatically based on the Products are new for setting,
and the In store from product property, regardless of the
product-specific public status configuration. The product-specific
public status is then used when displaying the product status
indicator on the live site.

Default product image URL

Here you can enter the default product image URL (virtual path).
The system uses this image if no image is specified for a given
product.

Keep the advertised price of the products according to their


cheapest product variant

For each product, indicates if the system updates the product price,
visible in the product listing, automatically with the price of the
cheapest product variant.

Taxes
Default country

Allows you to specify the default country, or select your country or


country where you sell the most. The system applies all taxes
based on their values as set for the default country, unless the
customer specifies their country (or state) during the checkout
process.

Apply taxes based on

Indicates whether the system applies taxes based on the shipping


address or billing address. Taxes related to orders with no shipping
address specified are calculated based on the billing address,
regardless of this setting.

Unregistered customers
Register customer after first checkout

Indicates if the system automatically creates an account for


unregistered customers after successfully completing the checkout
process. The system uses data that the customer provided during
the checkout process. The customer then receives a notification
e-mail with their login information, i.e. an e-mail address and a
randomly generated password.

Registration after checkout e-mail template

The system sends a notification e-mail to unregistered customers


after the first checkout if the Register customer after first
checkout setting is enabled. This setting allows you to select or
modify a template for the notification e-mail.

Live site pricing


Display price including discounts

Indicates if the system displays product prices on the live site


including discounts. This takes effect only for prices that are
displayed through the GetSKUFormattedPrice() or GetSKUPriceSa
ving() methods.

Display price including taxes

Indicates if the system displays product prices on the live site


including taxes. This takes effect only for prices that are displayed
through the GetSKUFormattedPrice() or GetSKUPriceSaving() met
hods.

Invoice
Invoice number pattern

Indicates the pattern used for generating invoice numbers. If left


empty, the default pattern {%Order.OrderID%} is used; invoice
numbers are then equal to order IDs.

Shipping
Weight formatting string

Indicates the format used for displaying product weight. Enter the {
0} expression to insert the weight into the formatting string.

Pages
My account URL

Indicates the URL of the My account page (virtual path).

Wishlist URL

Indicates the URL of the Wishlist page (virtual path).

Shopping cart URL

Indicates the URL of the Shopping cart page (virtual path).

Redirect to shopping cart

If on, the system redirects the customer to the shopping cart


content page when they click Add to shopping cart. Otherwise,
the customer stays on the same page, and the product is added to
the shopping cart in the background.

E-mails
Send e-commerce e-mails from

Here you can specify an e-mail address from which e-commerce


notification e-mails are sent.

Send e-commerce e-mails to

Here you can specify an e-mail address (e.g. the merchant's e-mail
address) to which e-commerce notification e-mails are sent.

Send order notification

Indicates if the system sends e-mail notifications after completing


and saving orders. The E-commerce order notification to customer
e-mail template is used when sending notifications to customers.
The E-commerce order notification to administrator e-mail template
is used when sending notifications to administrators.

Send payment notification

Indicates if e-mail notifications are sent after completing order


payment. The system sends these notifications automatically if the
customers paid through payment gateways, or if orders moved to a
status with the Mark order as paid property on (available in Store
configuration -> Order status -> edit order status).
Besides, store administrators can manually complete order
payment by turning on Order is paid for selected orders (available
in Orders -> edit order -> Billing tab).
Note: The E-commerce - Order payment notification to customer email template is used when sending notifications to customers, and
the E-commerce - Order payment notification to administrator e-ma
il template is used when sending notifications to administrators.

Send e-products reminder (days)

Allows you to specify how many days prior to e-products expiration


the system sends to the customers a notification e-mail.

Use customer's culture for e-mails

Indicates if the system sends the customers e-mails in the


shopping cart culture.

Conversion tracking
Registration conversion name

Here you can enter the name of a conversion logged when a


customer successfully registers on the site while going through the
checkout process.

Registration conversion value

Allows you to specify a number that the system records, together


with the Registration conversion, as the Registration conversion
value when this conversion is logged. The values are cumulative,
i.e. when a conversion hit is logged, the specified value is added to
the total sum previously recorded for the conversion.
You can insert a macro expression to dynamically retrieve a value
from the current website context.

Order conversion name

Here you can enter the name of a conversion logged when a


customer completes an order.

Order conversion value

Allows you to specify a number that the system records, together


with the Order conversion, as the Order conversion value when this
conversion is logged. The values are cumulative, i.e. when a
conversion hit is logged, the specified value is added to the total
sum previously recorded for the conversion.
You can insert a macro expression to dynamically retrieve a value
from the current website context.
For example: {%
EcommerceContext.CurrentShoppingCart.TotalPrice %}
The macro is resolved into total price of all items contained in the
order, including tax and shipping. With this configuration, each Ord
er conversion automatically stores the given orders price as its
value.

Add to shopping cart conversion name

Here you can enter the name of a conversion logged when a


customer adds a product to the shopping cart.

Add to shopping cart conversion value

Allows you to specify a number that the system records, together


with the Add to shopping cart conversion, as the Add to shopping
cart conversion value when this conversion is logged. The values
are cumulative, i.e. when a conversion hit is logged, the specified
value is added to the total sum previously recorded for this
conversion.
You can insert a macro expression to dynamically retrieve a value
from the current website context.
For example: {% ShoppingCartItem.UnitTotalPrice %}
With this macro as the conversion value, the Add to shopping cart
conversion logs the price (including tax) of a product added to the
shopping cart.

Settings - Global objects


Here you can configure settings related to the use of global objects in the Kentico E-commerce Solution.
The system allows you to use:
site-specific objects available on your separate sites only
global objects shared across all these sites
Concerning the multistore approach, there are three groups of objects available for your sites:
Objects with both site and global option

Include E-commerce Solution objects that you can use either as


site-specific objects, or as site-specific objects together with global
objects. Corresponds to the Allow global objects for section.

Objects with only site or global option

Include E-commerce Solution objects that you can use only


separately, i.e. either as site-specific objects, or as global objects.
Corresponds to the Use global settings for section.

Special case objects

Include site-bound E-commerce Solution objects, for which there


are no global object settings available; for example customers, ord
ers, reports, discounts.

Check boxes in the Allow global objects for section indicate for the selected site if the respective global objects along with the
respective site-specific objects are used (ON), or if only the respective site-specific objects are used (OFF).
Check boxes in the Use global settings for section indicate for the selected site if the respective global settings are used (ON), or
if the respective site-specific settings are used (OFF).

Settings - Authorize.NET
Here you can configure settings related to the Authorize.NET payment gateway.
General
API login

Allows you to specify an API login ID for the payment gateway


account.

Transaction key

Here you can enter a transaction key obtained from the merchant
interface.

Use test mode

The behavior of the payment gateway depends on test mode confi


guration both in the Kentico E-commerce Solution administration
interface (Settings -> E-commerce -> Payment gateways ->
Authorize.NET), and in the Authorize.NET Merchant Interface.
Test mode configuration in the Kentico administration interface
and in the Authorize.NET Merchant Interface resulting in the
transaction being processed as a test transaction:
ON/ON, OFF/ON, ON/OFF
Test mode configuration in the Kentico administration interface
and in the Authorize.NET Merchant Interface resulting in the
transaction being processed as a live transaction:
OFF/OFF

Settings - PayPal
Here you can configure settings related to the PayPal payment gateway.
General
Business

Allows you to specify an e-mail address for the merchant's PayPal


account. Enter the primary PayPal e-mail of the merchant's
account.

Cancel return URL

Here you can specify a URL to which the system redirects the
customer's browser if the payment is cancelled; for example a URL
on your site displaying your custom Payment cancelled page. By
default, i.e. if no such URL is defined, the system redirects the
browser to the corresponding PayPal page.

Notify URL

Allows you to enter a URL to which PayPal sends information


about the transaction. If specified, overrides the settings in the
PayPal Merchant Interface.

Return URL

Allows you to enter a URL to which the system redirects the


customer's browser after completing the payment; for example a
URL on your site displaying your custom Thank you for your
payment page. By default, i.e. if no such URL is defined, the
system redirects the browser to the corresponding PayPal page.

Settings - Community
Groups
Group template path

Alias path of the page that will be used, together with the pages
stored under it, as a template for newly created groups, e.g. /Group
s/Template.
The value of this setting is used by the Group registration web
part if its Template source alias path property is empty.

Groups security access denied path

Alias path of a page to which users will be redirected when they try
to access pages of a group they don't have permissions for. This
page should contain the Group security message web part, e.g. /Gr
oups/{GroupName}/Access.

Group management path

Alias path of the group management page, containing the Group


profile web part, e.g. /Groups/{GroupName}/Management.

Group profile path

Alias path of the group profile page; e.g. /Groups/{GroupName},


where GroupName is a wildcard replaced by the name of a given
group.

Group invitation
Invitation acceptation path

Alias path of the page containing the Group invitation web part; this
is a special web part handling requests for joining a group when a
user clicks the joining link in group invitation e-mail, e.g. /Special-p
ages/Invitation-acceptation.

Group invitation expires after (days)

When some user receives a group invitation e-mail, the link for
joining the group included in the e-mail will be active for the
number of days entered here. After the specified duration, the link
will no longer be functional. If 0 is entered, the link will be functional
permanently.

Members
Member management path

Alias path of the member management page, e.g. /Members/Mana


gement.

Member profile path

Alias path of member the profile page, e.g. /Members/{UserName},


where UserName is a wildcard replaced by the name of a given
user.

Enable friends

Indicates if the Friends functionality should be available in other


modules on the live site.

Friend management path

Node alias path of a page with the Friendship management web


part. This is a special web part for handling friendship approval or
rejection requests.

Activity points
Enable user activity points

If checked, activity points will be logged for users.

Activity points for blog post

Sets the number of activity points that users receive for adding a
blog post.

Activity points for blog comment post

Number of activity points that users receive for adding a blog post
comment.

Activity points for forum post

Number of activity points that users receive for adding a forum


post.

Activity points for message board post

Number of activity points that users receive for adding a message


board post.

Content management
Use parent community group for new pages

Indicates if new pages should inherit the value of the Owned by


group property from their parent page.

Settings - Forums
On this page you can adjust the settings related to forums.
General
Send forum e-mails from

Sets the e-mail address that will be used as the sender for forum
notifications and confirmation e-mails.

Forum base URL

This setting should contain the relative URL of the page where the
website's forums are located, for example:
~/Community/Forum.aspx
Forum groups and individual forums can either inherit this value
from the settings or use their own. Having a correct base URL is
important for generating valid links in forum-related e-mails.

Forum attachments allowed extensions

Allows you to specify a list of file extensions that will be allowed for
forum post attachments. The extensions should be entered without
dots and separated by semicolons. If blank, all extensions are
allowed.

Max forum post nodes

Determines the maximum number of forum post nodes displayed in


the forum post tree when editing a forum in the Forums application
.
If there are more nodes than allowed by this value, the click here
for more ... link will be displayed at the bottom of the tree, letting
you display a list of all nodes in the main area.

Subscriptions
Forum unsubscription URL

Sets the URL of the page that unsubscribes users from receiving
notifications about new forum posts. The Forum unsubscription
web part must be placed on the page in order for the
unsubscriptions to work.
The value of this setting can be inherited by forum groups and
through them by particular child forums. If left empty, the ~/CMSPa
ges/Unsubscribe.aspx default page is used.

Enable double opt-in for forums

Indicates if double opt-in should be enabled for forum objects.


When enabled, users are required to confirm their subscription by
clicking a link that is sent to them in an e-mail.
You can override this setting in the properties of a particular forum
group or a forum.

Double opt-in approval page path

Path to the page that contains the Forum 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 a user has to confirm their


subscription request.

Send double opt-in confirmation

Indicates if an e-mail confirmation should be sent to user after they


approve a subscription. If double opt-in is disabled, these
confirmation e-mails are always sent.

Settings - Message boards


On this page you can adjust settings related to message boards.
General
Send message board e-mails from

E-mail address that will appear in the From field of notification


messages about new message board messages.

Board base URL

Global board base URL that can be inherited by message boards.


It can be used by board notification e-mails and message board
viewers.

Subscriptions
Board unsubscription URL

URL of the site on that the Message board unsubscription web part
is placed. This web part handles requests for unsubscription from
notifications about new message board messages.
See Managing message boards

Enable double opt-in for message boards

Indicates if double opt-in should be enabled for message boards.


When enabled, users are required to confirm their subscription by
clicking a link that is sent to them in an e-mail.
You can override this setting in the properties of a particular forum
group or a forum.

Double opt-in approval page path

Path to the page that contains the Message board 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 a user has to confirm their


subscription request.

Send double opt-in confirmation

Indicates if an e-mail confirmation should be sent to users after


they approve a subscription. If double opt-in is disabled, these
confirmation e-mails are always sent.

Settings - Messaging
Users can be notified about new messages received using the notification e-mails. The settings on this page are related to these notification
e-mails:
General
Messaging sender e-mail

E-mail address that will be used as the sender address (From field)
of the notification e-mails.

Messaging e-mail subject

Entered text will be used as content of the Subject field of


notification e-mails.

Settings - Avatars
On this page, you can adjust settings related to avatars.
General
Enable pre-defined avatars

If checked, it will be possible to select one of the shared,


predefined avatars when choosing a user or group's avatar image.
If disabled, only custom uploaded avatars will be allowed.
This setting does not affect Gravatars.

Avatar type

Determines what kind of user avatars will be usable on the website.


The following options may be selected:
Avatar - users can either upload their own image or choose a
predefined one. The images are stored locally in the website's
database or file system.
Gravatar - the system will automatically load and display the g
lobally recognized avatars associated with the e-mail
addresses of users. Users must be registered at http://gravata
r.com/ to have a custom avatar, otherwise a default image will
be assigned to them. Note that switching to this option will
change the avatars of users who have uploaded a custom
image locally on the website.
User can choose - users will be able to choose if they want to
use a local avatar or a Gravatar when configuring their profile.
Gravatar support will be enabled for public users.

Gravatar rating

Gravatars are rated according to the maturity level of their content.


Through this setting, you can specify the maximum rating that will
be allowed on the site. The following options are available:
G - suitable for display on all websites with any audience type.
PG - may contain rude gestures, provocatively dressed
individuals, the lesser swear words, or mild violence.
R - may contain such things as harsh profanity, intense
violence, nudity, or hard drug use.
X - may contain hardcore sexual imagery or extremely
disturbing violence.
If a user's Gravatar does not meet the site's rating requirements,
the default image is displayed instead. Note that the rating of a
Gravatar is entered by its owner, so it may not always be accurate.

Gravatar default image

Determines what type of image should be displayed as the avatar


of users who do not have a valid Gravatar registered for their email
address.
If the (none) option is selected, the local avatar image specified as
the default option for users in the Avatars application is used. The
remaining options provide various types of default Gravatar
images. Most of the options automatically generate a different
default image based on the email address of the given user.

User avatars
Avatar max side size

Sets the maximum allowed size of user avatar images. If one or


both dimensions of the uploaded image are larger, it will be resized
so that the larger dimension matches the entered value.
If 0 is entered, the Avatar height and Avatar width settings will be
used instead.

Avatar height

If the Avatar max side size setting is set to 0, avatar images will
be resized to this height.

Avatar width

If the Avatar max side size setting is set to 0, avatar images will
be resized to this width.

Group avatars
Group avatar max side size

Sets the maximum allowed size of group avatar images. If one or


both dimensions of the uploaded image are larger, it will be resized
so that the larger dimension matches the entered value.
If 0 is entered, the Group avatar height and Group avatar width
settings will be used instead.

Group avatar height

If the Group avatar max side size setting is set to 0, images will
be resized to this height.

Group avatar width

If the Group avatar max side size setting is set to 0, images will
be resized to this width.

Settings - Chat
On this page, you can adjust settings related to chat.
General

Allow anonymous users

Indicates if users can enter chat without being logged in on the


website.

Guest prefix

Text that will be appended with a number and used as the user
name for anonymous users.

Force unique nicknames for anonymous users

If checked, nicknames of anonymous users on chat will have to be


unique. Nicknames of registered users always have to be unique.

Maximum length of message

Maximum number of characters in a message.

Convert URLs to HTML anchors in messages

If checked, URLs in messages will be converted to clickable HTML


anchors.

Enable BBCode in messages

Indicates if BBCode tags will be allowed and resolved in chat


messages. This setting affects the Room messages web part
(resolving) and the Send message web part (inserting BBCode
tags). If BBCode is enabled globally, you can still disable it for a
specific web part in its settings.

Convert emoticons to images

Indicates if emoticons will be converted to images in messages.

Enable sound in live chat

Indicates if the system uses sound notifications for new messages


opened in one-on-one conversations.

Support chat
Enable support chat

Indicates if support chat is enabled in the administration interface.

Enable sound in support chat

Indicates if the system uses sound notifications for new support


requests and new messages in support chat.

Send support messages to this e-mail address

Messages sent in support chat when no support person is on-line


will be sent to this e-mail address.

Timeout settings
Room ping interval (seconds)

Defines how often room related web parts will update their content
(messages, users in the room, etc.). The ping interval is the time in
seconds between two requests to the server. If you are
experiencing performance issues with chat, consider setting this
number to a higher value.

Global ping interval (seconds)

Defines how often global chat web parts will update their content
(on-line users, available rooms and notifications). The ping interval
is the time in seconds between requests for new data to the server.
If you are experiencing performance issues with chat, consider
setting this number to a higher value.

Kick lasting time (seconds)

Defines how long a kicked users will not be able to join the room
they were kicked from.

Log out user when inactive for more than (seconds)

Defines how long chat users can be inactive, i.e., not send any
request to the server, before the system logs them out. This can
happen if the users' Internet connections are down or they closed
the chat window.

Log out support engineer when inactive for more than (seconds)

Defines how long a support people can be inactive, i.e., not send
any request to the server, before the system logs them out. This
can happen if the users' Internet connections are down or they
closed the chat window.

Release room taken by support when not pinging for more than
(seconds)

Time of inactivity needed to release a room taken by a support


person. After this time passes, the room will appear as available to
other supporters.

Delete chat history older than (days)

Messages, rooms and chat users will be deleted after the number
of days specified in this setting. Records will be deleted according
to these rules:
All messages written earlier than the time specified will be
deleted.
All rooms will be deleted, which don't have any messages in
them, no one has access to them and were created earlier
than the time specified.
All users will be deleted, who are anonymous, have not written
any message and haven't been on-line for the specified time.

Default paths

Default redirection path - enter chat action

When this setting has a value, users will be redirected to the given
path after they enter chat. Specified web part setting will override
this global setting.

Default redirection path - leave chat action

When this setting has a value, users will be redirected to the given
path after they leave chat. Specified web part setting will override
this global setting.

Default redirection path - join room action

When this setting has a value, users will be redirected to the given
path after they join a chat room. Specified web part setting will
override this global setting.

Default redirection path - leave room action

When this setting has a value, users will be redirected to the given
path after they leave a chat room. Specified web part setting will
override this global setting.

Chat room popup window URL

URL of the window that is opened as a chat room pop-up (for


support chat or one-on-one chat).

Flood protection
Enable flood protection

Enables flood protection according to other settings in this section.

Join room interval (seconds)

Number of seconds which have to pass between two subsequent


room joinings made by one chat user.

Create room interval (seconds)

Number of seconds which have to pass between two subsequent


room creations by one chat user.

Post message interval (seconds)

Number of seconds which have to pass between two messages


posted by one chat user.

Change nickname interval (seconds)

Number of seconds which have to pass between two nickname


changes made by one chat user.

Settings - Web parts


On this page you can adjust settings related to chat web parts.
Default web parts settings
Items per page

Number of items displayed on one page when paging is enabled.


Affects on-line users, users in rooms, user search results, and
rooms. This setting can be overridden by a web part's setting.

Pages in group

Number of pages displayed in one group when paging is enabled.


Value 0 means that pages will not be grouped. Affects on-line
users, users in rooms, user search results, and rooms. This setting
can be overridden by a web part's setting.

Show filter limit

Filter will be shown when there is at least the specified number of


items displayed by a web part. This setting can be overwritten by a
specific web part's setting.

Invite users - users per page

Defines how many users will be displayed on one page when


inviting a user to a room.

Invite users - search mode

If enabled, the Search on-line users web part will be used when
inviting a user to a room. Otherwise, the On-line users web part will
be used. This setting can be overridden by a web part setting.

Search on-line users - maximum users in response

Defines how many users can be returned as a response to a


search query when the Search on-line users web part's search
mode is activated. If this setting is set to 0, the response will not be
limited.

First load of messages


Display 'Kick' system message

If checked, system messages of this type will be displayed when a


user enters a room.

Display 'Enter room' system message

If checked system messages of this type will be displayed when a


user enters a room.

Display 'Leave room' system message

If checked system messages of this type will be displayed when a


user enters a room.

Display 'Change nickname' system message

If checked system messages of this type will be displayed when a


user enters a room.

Display 'Support greeting' system message

Indicates if automatic greeting support message will be displayed


to users when they enter support chat.

Display 'Invited' system message

If enabled system will display messages when users invite other


users to chat room in that room.

Display 'Announcement' system message

Announcement is a message written from Kentico administration


interface (Chat -> Chat room -> Messages -> New announcement).
If checked, Announcements will be displayed when a user enters a
room.

Number of messages displayed after entering room

Indicates how many messages will be displayed when a user


enters a chat room. Negative number means there is no limitation
and all messages from the room will be displayed.

Default transformations
Room user transformation name

Transformation for displaying users present in a room.

Room message transformation name

Transformation that will be applied to messages in a normal (not


one-on-one chat) room.

Chat room name transformation

Transformation for displaying chat room name in the room title.

Room transformation

Transformation to be used for displaying rooms in their list.

Notification transformation

Transformation used for displaying notification messages.

On-line user transformation

Transformation for displaying on-line users.

Error transformation

Transformation that will be used for displaying errors.

Close all button transformation

Transformation that will be used to display the Close all button.

Chat support request transformation name

Transformation name for the element that allows to initiate on-line


support.

Initiated chat transformation name

Transformation for displaying chat bubble, which informs site


visitors that a support person wants to initiate chat with them.

Related pages
Writing transformations for chat

Settings - Social media


This category contains settings dedicated to the configuration of social media integration.

Settings - Facebook
This section contains settings related to Facebook features integrated into Kentico, which include Facebook authentication and posting to
Facebook.
We recommend that you configure these settings for individual sites separately. Configuring these settings on a global level could cause
problems if you have multiple sites and each of the sites has a different associated Facebook page and Facebook App.
Facebook app
App ID

A numeric ID of your Facebook App. You can find your App ID on


the Facebook App editing page.

App secret

The key used to authenticate Kentico against the Facebook App.


You can find your App secret on the Facebook App editing page.

Login with Facebook


Enable login with Facebook

Enable if you want your website users to log in with their Facebook
account. See Facebook authentication for more information.

Assign Facebook members to roles

When a new user logs in using Facebook, the system assigns the
user to the roles entered here.

Update users using their Facebook profile

Allows you to load information from the user's Facebook profile and
store it with the user's record in Kentico. This feature only works
when users log in using their Facebook accounts.
Never disables this feature. User information that has been
already downloaded stays in the system.
When they log in for the first time downloads the user
information only once, when they log in for the first time.
Every time they log in updates the user information every
time they log in.

Mapping of Facebook user profile

Determines how Kentico user fields match with Facebook profile


fields.

Settings - Google+
On this tab, you can adjust settings related to Google+ services. These settings are currently needed only for one web part: Google+
activity feed.
General
Client ID

Key obtained during the authorization of API access on Google.

Client secret

Key obtained during the authorization of API access on Google.

Access token

Click the Get button to obtain a site-wide access token required to


execute Google+ API calls that require authorization. The Client ID
and Client secret fields must be filled in.

To obtain these keys, create an account at https://accounts.google.com, create a new API project at https://cloud.google.com/console and
authorize it on the APIs & auth -> Credentials tab.

Settings - LinkedIn
On this tab, you can adjust settings related to LinkedIn authentication. This feature enables live site users to register and log on to your
website using their LinkedIn logon credentials.
General
API key

Key obtained during the registration of your application at LinkedIn.

Application secret

Key obtained during registration of your application at LinkedIn.

Access token

Click the Get button to obtain a site-wide access token required to


execute LinkedIn API calls that require authorization. The API key
and Application secret fields must be filled in. After the token
expires, it is renewed automatically.

Authentication
Enable LinkedIn authentication

Indicates if LinkedIn authentication is enabled.

Assign new users to roles

New users registered via LinkedIn authentication will be assigned


to these roles.

Required user data page

URL of the page where the LinkedIn required data web part
resides. If entered and a new LinkedIn user logs in to the site for
the first time, 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.

To obtain these keys, create an account at https://www.linkedin.com/ and create a new application at https://www.linkedin.com/secure/develo
per.
Required fields: The Access token field is used mainly for certain web parts (it is not required for LinkedIn authentication).

Settings - Social marketing


In this section you can adjust settings that relate to the integration of Kentico with social media.
In the Default URL shortener category, you can set up the default URL shortener that the system will use to shorten links posted to social
media.
The default shortener appears as the default selection when posting to a social network in the Facebook, Twitter, or LinkedIn applications.

Settings - URL shorteners


--------------On this tab, you can adjust settings URL
related
shortening
to
services that can be set for Facebook, LinkedIn and Twitter. Such services
shorten URLs that are undesirably long in posts. It is especially useful in case of Twitter, because its posts cannot be longer than 140
characters and generated URLs can take up a lot of this space.
bitly
Login

Your Bitly account username. Note that if you signed into bitly
using Facebook or Twitter, your actual login may be different from
the displayed name.

API key

Key assigned to your bitly account.

It is necessary to provide these settings in order to use the bit.ly service.


After registering an account (or signing in) at https://bitly.com/, you can view your user name and API key at http://bitly.com/a/your_api_key.
goo.gl
API key

Key assigned to your google application after enabling an API


access.

Providing the API key for goo.gl service is not necessary, but it is highly recommended. To obtain it:
1.
2.
3.
4.

Register an account (or sign in) at https://accounts.google.com.


Visit the API console at https://cloud.google.com/console.
Activate the URL Shortener API on the APIs & auth -> APIs tab.
Click the Credentials tab.
You can generate and view the API key on this page

TinyURL.com: TinyURL service does not require any settings.

Settings - Intranet & Collaboration


In this section, you can configure settings related to the Intranet portal. The following setting is available:
Departments
Department template path

Alias path of a page that will be used, together with the pages
stored under it, as a template for newly created departments.

Settings - Events
In this section, you can configure settings related to events.
General
Sender's e-mail

Senders e-mail address.

Sender's name

Name of the sender.

E-mail subject

Here you can add the subject of the event announcement


message.

Settings - Projects
In this section, you can configure settings related to the Projects application:
General
Task detail page

URL of a page that displays detailed information about the tasks as


signed to users. This page should contain the Tasks assigned to
me web part. The value of this setting is used for generating links
to personal tasks in project management email notifications and as
the URL that is linked to by the Task info panel web part if its Task
detail page URL property is empty.
Sample value: ~/Employees/Management/My-Projects-and-tasks.a
spx

Send project management emails from

Sets the email address from which automatic project management


notification emails are sent when tasks are created or modified.

Settings - Versioning & Synchronization


This category contains settings related to content staging and object versioning.

Settings - Staging
On this page you can adjust settings related to the Content staging functionality.
Client (source only)
Log content changes

Specifies whether content change tasks are generated. Check for


source server.

Log data changes

If enabled, staging tasks are logged when data in custom tables


are modified.

Log object changes

Specifies whether the object change tasks are generated, check for
source server.

Log staging changes

If enabled, synchronization tasks are created for changes made by


synchronization from another server to this server

Log export tasks

Specifies whether the export tasks are logged when the object is
deleted (incremental update support).

Staging service (target only)


Enable staging service

Specifies whether the staging service is enabled. Check for target


server.

Staging service authentication

Staging service authentication type, use value USERNAME or


X509.
See Using X.509 authentication.

Staging service user name

Staging service user name for username authentication.

Staging service password

Staging service password for username authentication.

X509 Certificates
Client key ID

Staging service client certificate key ID.

Server key ID

Staging service server certificate key ID.

Settings - Object versioning


General
Enable object versioning

Globally enables or disables object versioning. This option is


enabled by default. If disabled, no versions are created when
objects are modified.

Delete objects to recycle bin

Determines which objects should be moved to recycle bin when


deleted:
No - no objects are moved to recycle bin when deleted, i.e.
they are deleted permanently.
Versioned objects only - only objects that support versioning
and whose versioning is enabled by the settings below are
moved to the recycle bin when deleted.
All objects - all objects that support staging synchronization a
re moved to the recycle bin when deleted.

Team development
Use check-in/check-out for objects

Indicates if object locking (check-in/check-out) should be used for


virtual objects. See Preparing your environment for team
development.

Keep new objects checked out

Indicates if new objects are automatically checked out upon


creation.

Version history

Version history length (minor versions)

Indicates how many minor versions of a single object will be stored


in its version history. If the number of versions exceeds this value,
the oldest version is deleted. If set to 0, minor versions history
length is not limited.

Version history length (major versions)

Indicates how many major versions of a single object will be stored


in its version history. If the number of major versions exceeds this
value, the oldest versions are deleted. If set to 0, major versions
history length is not limited.

Save to last version if younger than (minutes)

If an object is edited and saved within this number of minutes since


it was last saved, changes made to it are saved to the last version.
If it is saved after more minutes since it was last saved, a new
version is created. If set to 0, a new version is created whenever
you save an edited object.

Promote to major version if older than (hours)

If an object is edited and saved after this number of hours since it


was last saved, a new major version is created. If it is saved
earlier, a new minor version is created or the changes are saved to
the latest version (depending on the setting above). If set to 0,
major versions are never created automatically.

Use object versioning for


Alternative forms

Indicates if versioning of page type, on-line forms and custom table


alternative forms is allowed.

Automation process

Indicates if versioning of the automation process objects is allowed.

CSS stylesheets

Indicates if versioning of CSS stylesheets is allowed.

Custom table definitions

Indicates if versioning of custom table definitions is allowed.

Page type definitions

Indicates if versioning of page type definitions is allowed.

E-mail templates

Indicates if versioning of e-mail templates is allowed.

Form definitions

Indicates if versioning of on-line form definitions (the Forms


module) is allowed.

Media files

Indicates if versioning of media files (the Media module) is allowed.


This options is disabled by default because versioning of large
media files may consume an extensive amount of database space.

Media files versioned extensions

Extensions of versioned media files. Only media files with


extensions enumerated here will be versioned.

Newsletter issues

Indicates if versioning of newsletter issues is allowed.

Newsletter templates

Indicates if versioning of newsletter templates is allowed.

Page layouts

Indicates if versioning of page layouts is allowed.

Page templates

Indicates if versioning of page templates is allowed.

Queries

Indicates if versioning of page type and custom table queries is


allowed. Only custom queries are versioned system queries are
not versioned because they are re-generated by the system
automatically when their parent object is modified.

Report graphs

Indicates if versioning of report graphs is allowed.

Report tables

Indicates if versioning of report tables is allowed.

Report values

Indicates if versioning of report values is allowed.

Report definitions

Indicates if versioning of report definitions is allowed.

Transformations

Indicates if versioning of page type and custom table


transformations is allowed.

UI element

Indicates if versioning of UI element objects is allowed.

Web part containers

Indicates if versioning of web part containers is allowed.

Web part layouts

Indicates if versioning of web part layouts is allowed.

Workflows

Indicates if versioning of workflow objects is allowed.

Settings - Web farm


General
Enable web farm

Indicates whether web farm support is enabled.

Update within request

Enable this setting if you want synchronization to be triggered with


every page request. If you disable this setting, synchronization
must be ensured through scheduled tasks or custom code.

Use web farm database updater

Indicates whether database web farm updater is used.

Web farm updater custom class

Specifies custom web farm updater class (given class must inherit
from IWebFarmUpdater interface).

Generate servers dynamically

Specifies whether web farm servers are generated dynamically on


application start. If true, you don't have to create them in the user
interface.

Delete generated servers on application end

Ensure that generated web farm servers will be deleted on


application end event.

Web farm application physical path

Path to the application's physical path on disk for synchronizing


physical files.

Maximum file size to be synchronized (kB)

Sets the maximum file size in kilobytes which should be


synchronized.

Allow synchronization for

In this category, you can enable or disable web farm synchronization of a particular object.

Settings - Integration
This category contains settings related to integration with external applications and services.

Settings - Integration bus


The settings in this category allow you to adjust the functionality of the integration bus, which can connect Kentico with external third party
systems. The integration synchronizes objects and pages (in both directions).
General
Enable system integration bus

Allows logging and processing of incoming and outgoing


integration tasks.
Integration tasks represent individual synchronization operations
for objects or pages (create, update, delete etc.). The
synchronization process consists of two steps:
Logging - creation of integration tasks for actions that require
synchronization.
Processing - execution of the integration tasks.
You can enable or disable logging/processing of incoming/outgoing
tasks separately through the other settings in the category.

Enable logging of incoming tasks

Indicates if the integration bus logs integration tasks received from


external systems. To log tasks, the Enable system integration
bus setting must also be enabled.

Enable processing of incoming tasks

Check to allow processing of integration tasks incoming from


external systems. To process tasks, the Enable system
integration bus setting must also be enabled.

Enable logging of outgoing tasks

Indicates if the integration bus logs changes made to pages and


objects in Kentico as outgoing integration tasks. To log tasks, the E
nable system integration bus setting must also be enabled.

Enable processing of outgoing tasks

Check to allow processing of outgoing integration tasks. To


process tasks, the Enable system integration bus setting must
also be enabled.

Settings - Microsoft SharePoint

In this section you can configure the default logon credentials used to access the SharePoint server. If you configure a Username and Pass
word here, it will be used by default if you leave the Username and Password fields blank in the properties of SharePoint web parts.
If you enable the Use Windows Authentication option, the current user's windows domain credentials will be used to access the SharePoint
server.
You must specify the address of the SharePoint server itself in the properties of SharePoint web parts.
Important: The settings configured here are automatically used for authentication by the GetSharePointFile.aspx page and since the URL to
access the page can be entered manually, it is highly recommended to enter the credentials of a user that is authorized to access only the
files you want to display on your website.

Settings - REST
On this tab, you can adjust settings related to Kentico REST service. The following settings can be adjusted:
General
Service enabled

Enables or disables the Kentico REST service. See Configuring the


REST service.

Service enabled for

Choose if the REST service allows access to objects, pages, or


both.

Authentication type

Determines which type of authentication the REST service uses.


Supported types are Basic and Forms authentication. See Authent
icating REST requests.
Note: You can authenticate REST requests using the hash query
string parameter in both modes.

Always check page security

If disabled, security is not checked when accessing published


versions of pages. If enabled, security is always checked.

Page access is read only

If enabled, the REST service only allows GET requests for pages
(pages cannot be modified).

Object access is read only

If enabled, the REST service only allows GET requests for objects
(objects cannot be modified).

Allowed page types

Specifies a list of page types that the REST service is allowed to


access. Enter the names of page types separated by semicolons.
If empty, all page types are allowed.

Allowed object types

Specifies a list of objects types that the REST service is allowed to


access. Enter the names of object types separated by semicolons.
If empty, all object types are allowed.

Generate authentication hash for URL

Click the button to generate an authentication hash for specific


REST URLs.
Enter the full absolute URL of the REST request, including the
protocol, website domain name, virtual directory, REST path, and
query string parameters. For example:
http://mywebsite.com/rest/content/currentsite/en-us/all/news?forma
t=json
The system adds the authentication hash parameter to the URL.
You can copy the URL and use it to perform the REST request
without any other type of authentication.
Restrictions:
Only works for GET requests (read only data retrieval)
You cannot use hash parameter authentication for /all object
retrieval requests (~/rest/<objecttype>/all).

Default encoding

Sets the character encoding that the REST service uses for
requests that do not contain a supported Accept-Charset header.

Allow sensitive fields for administrators

If enabled, REST requests authenticated using the credentials of


users with the Global administrator privilege level are allowed to
work with data fields that contain sensitive information (for example
fields related to passwords).
Requests authenticated under non-administrator users can NEVER
access sensitive fields, regardless of this setting's value.

Settings - WebDAV
On this tab, you can enable WebDAV integration and configure which file types should be editable using WebDAV.
WebDAV is only functional if Kentico is configured to use Windows authentication, otherwise this settings have no effect.

General
Enable WebDAV support

Enables or disables WebDAV editing in both the Edit mode and the
Browse mode.

Supported file extensions

List of file extensions that should be editable using WebDAV Edit


mode. The Edit in client application (
next to pages with this extension.

) icon is only displayed

Enter extensions with or without the leading dots, separated by


semicolons; e.g. .docx;.xlsx;.pptx;jpg;jpeg.
An appropriate client application with WebDAV support must be
installed on the client machine for each listed extension in order for
WebDAV editing of these files to be possible.

Settings - Data.com
The settings in this category allow you to configure data field mappings between:
Kentico and Data.com contacts
Kentico accounts and Data.com company profiles
To modify the default field mappings, click Edit at the bottom of the Contact or Company sections.

Related pages
Data.com integration
Mapping Data.com fields
Contact management

Settings - Salesforce.com
On this tab, you can configure the Salesforce integration module which replicates Kentico contacts to Salesforce leads based on their scores.
General
Organization access

Allows you to authorize access of Kentico to your Salesforce


organization on behalf of a specific user.

Replication of contacts into Salesforce leads


Enabled

Enables or disables replication of Kentico contacts into Salesforce


leads.

Keep Salesforce leads updated

If enabled, the replication process includes contacts that have


already been replicated before. This ensures that the system
updates the corresponding Salesforce leads based on the current
contact data.
If disabled, contacts are only replicated once.

Mapping of contacts to Salesforce leads

Allows you to map contact fields to the fields of Salesforce leads.


The replication process transfers contact data to leads according to
the mappings.
Organization access must be granted in order for this option to be
configurable.

Batch size

Applications can only make a limited number of API calls to


Salesforce within a 24 hour window. To minimize the number of
calls, the replication process handles contacts in batches. Each
batch only requires one API call.
This setting specifies the maximum number of contacts that the
system replicates in a single batch.

Score

Allows you to select the score that determines which contacts are
replicated. The system only replicates contacts that reach a certain
value in the given score (specified via the Minimum number of
points for replication setting).
If you do not choose a score (None), the system replicates all
contacts.
Note: The replication process is always performed separately for
each website, so you can only select a score for individual sites,
not globally.

Minimum number of points for replication

Specifies the amount of points that contacts must reach in the


score selected through the Score setting. Once a contact reaches
this value, the system marks it for replication as a Salesforce lead.

Lead description

Defines a custom description for replicated contacts. To map the


description to a specific field of Salesforce leads, select the Gener
ated lead description source in the field mappings.
You can insert the values of contact fields into the description using
macro expressions.
The default description adds the Last name of the contact that is
being replicated and the name of the current site:

{% Contact.ContactLastName %} from
{% CurrentSite.SiteName %}

For example, to use the Business phone value instead of the last
name, enter the following expression:

{% Contact.ContactBusinessPhone %}
from {% CurrentSite.SiteName %}

Default company name

All Salesforce leads require a company name value.


This setting allows you to specify a default company name, which
the replication process uses for contacts who are not associated
with any company.
The system attempts to retrieve the company name value from
sources in Kentico in the following order:
1. The value of the contact's Company name field
2. The name of the account in which the contact is listed as a pri
mary contact
3. The account that lists the contact as a secondary contact
4. The first account that contains the contact as a regular contact
5. The value of the Default company name setting (if none of
the above steps are successful)

Settings - 51Degrees.mobi
On this tab, you can enhance the functionality of Device profiles by adding a Premium 51Degrees.mobi Data license key or uploading a
Premium data .xml file. The Premium data version contains additional devices, e.g., game consoles, eBook readers, tablets and smart
phones. It also contains additional properties in comparison with the Lite data version, which is included in Kentico by default.
General
License settings

Insert your Premium Data license key into the text box and click Ac
tivate.
You can also upload a Premium data file using the Choose file an
d Upload button instead.

Settings - Strands Recommender


On this tab, you can configure the Strands Recommender integration functionality which allows you to place recommended content to site
visitors based on their behavior.
General
API ID

Enter the unique identifier of your Strands Recommender account.


The system requires the ID to communicate with the
recommendation service. You can find your API ID in the My
account section of the Strands Recommender website.

Validation token

Enter the validation token of your Strands Recommender account.


The Strands recommendation service requests the token when the
application performs certain customer actions. You can find your
Validation Token in the My account section of the Strands
Recommender website.

Catalog feed
Catalog layout

Transformation used to generate each item in the Strands catalog


feed. Only items in the feed will be considered when
recommending items.

Path

The path from which items are generated into the Strands catalog
feed.

Product types

The page types from which items are generated into the Strands
catalog feed. Leave empty to include all page types.

WHERE condition

The value of the WHERE condition in the SELECT statement that


specifies the items in the Strands catalog feed.

Automatic catalog upload


Enable automatic catalog upload

Enables automatic upload of the Strands catalog feed to Strands.


When selected, the Save button automatically uploads the Strands
catalog feed to Strands.

Automatic upload frequency

The frequency at which the Strands catalog feed is requested by


Strands.
You can set the frequency more precisely directly on the Strands
portal (e.g., you can set an exact hour for weekly updates).

Catalog access restriction


Username

The username used for restricting access to the Strands catalog


feed.

Password

The password used for restricting access to the Strands catalog


feed.

Managing files
Kentico allows you to upload files (such as GIF, JPG, SWF, PDF, XLS, DOC, etc.) to the Kentico database or file system and manage them
as any other content.

File management approaches in Kentico


If you need to upload files to the Kentico database or file system, you need to distinguish between four types of files:

CMS.File pages
These files are uploaded by content editors as new CMS.File pages into the content tree. You will typically use this type for files that are used
as part of unstructured pages, such as page links or images inserted into editable regions of pages. It is advisable to have files stored within
folders (CMS.Folder page type). You can also use the File import module when uploading multiple files. The Document library module allows
convenient management of CMS.File pages on the live site.

Page attachments
These files are stored as a part of a structured page and their life cycle is also bound to the page (including workflow and versioning). You
can have an unlimited number of files attached to a page. You can find a detailed description of the whole concept and examples of typical
usage in Attaching files to pages.

Media libraries
The Media libraries application allows you to store large amounts of files, while large file sizes are supported. The application and its typical
usage is described in Media libraries.

Unmanaged files
These files are part of the website theme. They should be stored in the <web project>\app_themes\<theme>\images folder on the disk. They
usually include images and Flash animations used throughout the site. These files are not managed by the system.

Storing files
Page attachments and CMS.File pages can be physically stored in the file system, in the database, or in both. You can define this in the Setti
ngs application in the System -> Files category using the Store files in file system and Store files in database options.

The following three combinations can be achieved using the settings:


File system - the files are stored in the configured folder on your disk. This option provides the best performance. However, the Mo
dify permissions on the disk must be granted to the ASP.NET account on your machine, which is not always possible. The process
of granting the Modify permission is described in Disk permissions problems.
Database - the files are stored in the database. This option provides worse performance, but doesn't require the Modify permission
for the file system and allows you to easily backup the uploaded files as part of your database.
Both - Database and file system - this option combines the advantages of both options. It provides the same performance as the
file system-only option since the files are stored in the file system. At the same time, you can use the full-text search because the
database is also available.

Page attachments and metafiles location


Page attachments are stored in the file system under ~/<site code name>/files, metafiles are stored under ~/<site code name>/metafiles.
Both these folders can be located in different locations, which can be configured using the Settings -> System -> Files -> Files folder settin
gs option. Learn more in Settings - Files.

Form files location


Files uploaded by website users into forms are always stored in the file system. The default location is ~/<site code name>/BizFormFiles.
You can customize the location in Settings -> System -> Files -> Custom form files folder.
Files may be submitted as part of form records, typically when a form contains an uploader type field (specifically the Upload file field
type/form control). You can adjust the following settings related to files submitted through forms and their storage in the file system:
Storage
Custom form files folder

Folder where files uploaded via forms 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 files are stored in the ~/<site code
name>/BizFormFiles/ folder.

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. <custom BizForm files folder>/<site code name>. It is
useful for better orientation in files when multiple sites are running
in the system.

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 will be allowed for all file types.

Media library files location

Files stored in media libraries are always stored in the file system. The default location is ~/<site code name>/media, while the location of the
folder can be customized in Settings -> Content -> Media -> Media libraries folder, as described in Configuring media libraries.

Importing files
The File import application allows you to import large amounts of files into the system. The files imported using this application are stored in
the content tree as CMS.File (or CMS.Folder) pages. This eliminates the need to create pages and upload files in the content tree manually
one-by-one.
You can import files from the two following sources:
From your computer - use this option to import files from anywhere on your disk. Note that this option allows you to perform import
on a file-to-file basis only. This means that you have to structure the files into folders manually.
From a server disk - use this option to import files located on the server disk. Note that this options allows you to import files
including their whole folder structure.

The use of this application should be allowed only to site administrators, as the File import application doesn't check certain
security settings from Settings -> System -> Files, such as allowed file extensions. The File import security subsection
demonstrates how you can set permissions for this application.

The File import application isn't the only way how you can upload files to the system. See Working with files for further details.

Importing files from your computer


When importing files from your computer, the system doesn't retain the original folder structure. If you want to import whole folders, import
the files from a server disk. Files imported this way are stored as CMS.File pages.
1. Open the File import application.
2. Switch to the Import from your computer tab.
3. Specify the following properties:
Target alias path - path within the content tree where the files will be imported.
Culture - culture to which the uploaded files (pages) will be assigned.
Include file extension in name - if enabled, the file extension is included in the File name of the newly imported files.
4. Click Select files to select files that you want to import into the system.

5. Click on Upload.
The system imports the files.
If you now open the Pages application and locate the alias path that you specified in the previous step, you can see that the files have been
uploaded.

Importing files from a server disk


You can ensure the entire folder structure is retained by importing files from a server disk. When files are uploaded this way, they are stored
as CMS.File (or CMS.Folder) pages.
1. Copy your files into the specified import folder.
The default file import folder is ~/CMSImportFiles.
You can customize the file import path in Settings -> System -> Files -> Files folder.
2.
3.
4.
5.

Open the File import application.


Switch to the Import from server disk tab.
Select files to import.
Specify the following properties:
Target alias path - path within the content tree where the files will be imported.
Culture - culture to which the uploaded files (pages) will be assigned.
Delete imported files from disk - if enabled, files in the import folder will be deleted after a successful import.
Include file extension in name - if enabled, the file extension is included in the File name of the newly imported
files.

6. Click Start import.


The system imports the files.
If you now open the Pages application and locate the alias path that you specified in the previous step, you can see that the files have been
uploaded.

File import security


You can configure access rights for the File import application using the Permissions application after selecting Permissions for: Module
File import. The File import application has only one permission:
Import files - members of the specified roles can import files using the File import application.

Uploading files
You can upload files in Kentico either one by one or as multiple files. This can be useful if you need to upload a greater number of files at
once, or if you need to perform the task quickly. Uploading multiple files at once is available for:
Media files - files in media libraries (e.g. Media libraries -> Edit (

) media library -> Files).

Meta files - files related to specified objects (e.g. e-mail template attachments in E-mail templates -> Edit (
General).
Page attachments - files attached to pages (e.g. Pages -> select page -> Properties -> Attachments).

) e-mail template ->

Requirements for uploading multiple files


The following conditions must be fulfilled to allow uploading of multiple files:
The application has the write-to-disk permission for the temporary file repository (CMS/App_Data/CMSTemp/MultiFileUploader fol
der).
The client browser supports HTML 5 (for example, the system only allows uploading of single files for older versions of Internet
Explorer)

How it works
1. Select one or more files from a given location.

2. The files are downloaded as temporary files to a repository (CMS\App_Data\CMSTemp\MultiFileUploader). To upload the files
successfully, users need to avoid causing a post back on the page containing the upload form field.
3. When the upload is finished, the temporary files become the requested files:

If a post back occurs while uploading multiple files or another error occurs, the temporary files remain in the temporary repository.
The system provides the Delete old temporary upload files scheduled task (configurable in the Scheduled tasks application),
which deletes these temporary files, by default older than 24h. You can change this setting by changing the value of the CMSDelet
eTemporaryUploadFilesOlderThan key (you need to manually add the key into the web.config file of the current web project
folder).

Resizing images on upload


You can set global image resizing parameters in Settings -> System -> Files -> Image resizing by entering the following values:
Automatic image resize on upload (width, height, max side size) - depending on which values you fill in, the functionality is the
following when uploading images:
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 so that aspect ratio is preserved.
Both width and height - images are resized so that the larger dimension matches the respective entered value. Aspect
ratio is 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 the width and height settings are not applied.

These settings are applied by default when uploading images as:


media library files
page attachments
CMS.File pages
Editable text web part - uploading images using the text editor dialogs.
Editable image web part - uploading images using the Select image dialog.
Field editor fields - uploading images using the following field types (form controls), e.g. in forms, Page type field editor, etc.
File attribute type -> Upload file and Direct uploader form controls.
Text attribute type -> HTML Area (Formatted Fext), BBcode editor, Image selection, Media selection and File
selection form controls.
The default settings defined here can be overridden by local settings in the particular parts of the user interface (e.g. web part properties,
field editor, text editor dialogs, etc.).

Administering files globally


A user interface for global-level administration of files stored by the system is located in the System application on the Files tab. This part of
the user interface is divided into tabs described in the following text.

Test tab
On the Test tab, you can perform a test that verifies the system's access to the file system. The test consists of the following steps:
1. Creation of a testing folder and file
2. Modification of the testing file
3. Deletion of the testing folder and file
Click Test files to perform the test.

Attachments tab
On the Attachments tab, you can find a list of page attachments stored by the system. Based on selection in the Site drop-down list, you
can either select a site and view all page attachments on the site, or choose (all) to view all page attachments on all websites in the system.
If there are more than 25 page attachments (or a different number set by means of the CMSDefaultListingFilterLimit web.config key), a filter
is displayed above the grid. Using the filter, you can filter displayed attachments by their name, extension, size or depending on if they are
stored in the database.
Depending on the Store files in file system and Store files in database settings in Settings -> System -> Files, the system allows you to
perform for the page attachments management actions.
Use the two drop-down lists below the grid. In the first drop-down list, you can select:
Selected files - performs the action for files selected using the check-boxes in the grid.
All files - performs the action for all listed files.
Then you can select the required action from the second drop-down list and click OK.
Copy to database - copies the attachment to the database. This action is only displayed if the attachment is stored only in the file
system while settings are configured for files to be stored both in the file system and in the database.
Delete from database - deletes the attachment from the database. This action is only displayed if the attachment is stored both in
the file system and in the database while settings are configured for files to be stored only in the file system or to be stored both in
the file system and in the database.
Copy to file system - copies the attachment to the file system. This action is only displayed if the attachment is stored only in the

database while settings are configured for files to be stored only in the file system or both in the file system and in the database.
Delete from file system - deletes the attachment from the file system. This action is only displayed if the attachment is stored both
in the file system and in the database while settings are configured for files to be stored only in the database.

Clearing the attachment search content


The Smart search feature of Kentico allows users to search the text of attachment files along with the content of pages. The application
stores the text 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.
Click Clear attachment search cache in the header of the Attachments tab to remove the search content from the database for all
attachments.
This allows you to rebuild your page indexes correctly in the following scenarios:
After you apply a hotfix or upgrade that changes how the search indexes attachment files
If you modify the functionality of a custom search text extractor

Metafiles tab
On the Metafiles tab, you can find a list of metafiles stored by the system. Based on selection in the Site drop-down list, you can select:
(all) - displays all metafiles stored by the system.
(global) - displays metafiles of global, i.e. not site-related objects.
<website> - displays metafiles of site-related objects belonging to the selected site.
Using the Object type drop-down list, you can further limit which metafiles will be displayed. By selecting (all), you get all metafiles that
match the selection in the drop-down list above. The other options in the drop-down are particular object types, while choosing one displays
only metafiles of these objects that match the selection in the drop-down list above.
If there are more than 25 metafiles (or a different number set by means of the CMSDefaultListingFilterLimit web.config key), a filter is
displayed above the grid. Using the filter, you can filter displayed metafiles by their name, extension, size or depending on if they are stored
in the database.
In the Actions column in the grid, action icons are displayed depending on the Store files in file system and Store files in database settin
gs in Settings -> System -> Files. The displayed actions are the following.
Depending on the Store files in file system and Store files in database settings in Settings -> System -> Files, the system allows you to
perform for the metafiles management actions:
Use the two drop-down lists below the grid. In the first drop-down list, you can select:
Selected files - performs the action for files selected using the check-boxes in the grid.
All files - performs the action for all listed files.
Then you can select the required action from the second drop-down list and click OK.
Copy to database - copies the metafile to the database. This action is only displayed if the metafile is stored only in the file system
while settings are configured for files to be stored both in the file system and in the database.
Delete from database - deletes the metafile from the database. This action is only displayed if the metafile is stored both in the file

system and in the database while settings are configured for files to be stored only in the file system or to be stored both in the file
system and in the database.
Copy to file system - copies the metafile to the file system. This action is only displayed if the metafile is stored only in the database
while settings are configured for files to be stored only in the file system or both in the file system and in the database.
Delete from file system - deletes the metafile from the file system. This action is only displayed if the metafile is stored both in the
file system and in the database while settings are configured for files to be stored only in the database.

Editing file metadata


You can use the Metadata editor to edit metadata (i.e. descriptions) of non-image files stored in media libraries , as page attachments or as
object metafiles. The Edit metadata dialog is accessible by clicking the Edit (
administration interface.

) icon next to the file listed in the respective part of the

You can enter the following metadata:


File name - the name of the file (without the trailing dot and extension). The current file name is always pre-filled when the dialog is
opened.
Title - the title of the file (may be different from the actual file name).
Description - text describing the content of the file.

Configuring page URLs


Kentico uses a rewriting engine to processes URLs. The engine allows the system to use friendly URLs in format:
http://www.example.com/products/kentico-cms.aspx
instead of something like:
http://www.example.com/products.aspx?id=527
The friendly URLs provide several benefits:
They are easy to remember and easy to write into the browser address bar.
They are friendly towards search engines (for more information, see the Search engine optimization chapter).
They represent a path that shows users where they are located on the website.

Users can easily bookmark or send the URLs of pages


Every page has its own unique URL. If the website's content is available in multiple languages, individual language versions of pages are
recognized based on a combination of their alias path and a URL with a culturespecific format, or through completely custom URL paths (if
specified).
Figure: Basic page processing steps

After pages are processed by the rewriting engine, the system optionally applies output filters that perform additional changes in
the rendered HTML code.

URL processing
The steps below explain how the system handles a request for the following URL: http://www.example.com/products/kentico-cms.aspx
1. Look up the website based on the domain name
The system checks the domain name in the URL and finds a matching site, either via the main site domain name or domain aliases. If
none of the currently running websites match the domain name, the ~/cmsmessages/invalidwebsite.aspx page is displayed. If the
requested domain name contains a port number that is not found, the domain is checked without the port number.

2. Process the URL path


The request in this example specifies a standard URL path, so the request is handled by the Kentico URL rewriting engine. The most
prioritized way to identify standard pages is the Page URL path, so the engine first attempts to find a page with a URL path set to /produ
cts/kentico-cms.
If there is no page with a matching URL path, the rewriting engine tries to look up a page with an Alias path equal to /products/kentico-c
ms (the alias path is generated according to the page's position in the content tree).

3. Check for Page aliases

If a page cannot be found under the given URL or alias path, the system tries to find a page with a Page alias set to /products/kentico-c
ms.
See also: Setting page aliases

4. Handle errors
If the steps described above fail to find a matching page for the requested URL, the system does not process the request. The web
server returns a 404 HTTP status code and displays the Page not found error page configured for the website.

5. Display the page


When the requested page is identified, the system displays the content according to the type of the page's template:
If the page is managed by the Portal engine, the ~/cmspages/portaltemplate.aspx system page is called, which renders the
final output according to the web parts placed on the given template and the content of the specific page.
For ASPX page templates, the appropriate template (web form) is loaded using an internal URL, for example: /products.aspx?ali
aspath=/products/kentico-cms
In the case of MVC templates, the system passes on the request to the MVC controller and action specified for the given
template, which then renders the page using an appropriate MVC view.

Figure: Processing for all types of URL requests

Processing of MVC and Routing URL patterns


If the URL of an incoming request matches the MVC or Routing pattern defined for a page, the pattern always has priority over
other types of URL processing (even if it is set through a page alias).
The rewriting engine evaluates MVC and Routing patterns in the same step of the process, so precedence between the two is not
defined. You should always avoid collisions between MVC and Routing patterns.

Excluding URLs from the rewriting engine


If your website uses custom physical pages (.aspx, .html or any other file types) stored inside the web project directory, you can avoid
unnecessary processing by excluding their URLs from the Kentico rewriting engine. When a visitor requests an excluded URL, the system
skips all URL rewriting actions and attempts to access the specified page directly. This leads to better performance and also allows you to
prepare your own custom URL rewriting logic.
To disable rewriting for specific pages, open the Settings application, select the URLs and SEO category, and type the matching URL paths
into the Excluded URLs setting:
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 /Custom, for example: ~/Custom.aspx, ~/Custom2.aspx, ~/Custom/Page.
htm

/Custom;/Static - excludes all pages whose URL path starts with /Custom or /Static.
Warning: Be careful not to exclude the URLs used by the regular pages in the website's content tree. With URL rewriting disabled
for a URL, the system always tries to load a matching physical page, which leads to a page not found error in most cases.

URL format and configuration


Defining URL extensions
Page URLs can use various types of extensions. By default, all URLs end with .aspx, for example: http://www.example.com/products/kentico
-cms.aspx
You can also use custom extensions, such as .htm, .html or any other sequence of characters, or URLs without extensions, such as http:
//www.example.com/products/kentico-cms. In this case, you need to configure the system as described in Custom and extensionless URLs.

Forbidden URL characters


Certain characters have special meanings in URLs, so they cannot be used in values that determine the path to pages (i.e. page aliases and
URL paths). By default, the following characters are forbidden:

\/:*?"<>|&%.'#[]+=" and the space character

To specify additional forbidden characters:


1.
2.
3.
4.

Open the Settings application.


Select the URLs and SEO category.
Type the characters into the Forbidden URL characters setting (without any separator).
Click Save.

Alternatively, you can enter a regular expression into the Allowed URL characters setting to precisely specify which characters are allowed
in URLs.
Note
The default characters listed above are always forbidden unless you override the CMSForbiddenURLValues key in the /configurat
ion/appSettings section of your application's web.config file. For example:

<add key="CMSForbiddenURLValues" value="$\/:?&quot;&lt;&gt;|&amp;%.&apos;#[]


=" />

You can either use the key to allow some of the default forbidden characters, or add new ones. It is strongly recommended to
keep the default characters forbidden entering the characters into URL paths may prevent certain types of URLs from
working correctly.
The system automatically replaces or removes forbidden characters. You can specify the character that is used to replace forbidden
characters through the Forbidden characters replacement setting in Settings -> URLs and SEO. By default, forbidden characters located
at the beginning or end of the path are removed completely and consecutive forbidden characters are only replaced by a single character. If
you wish to have each forbidden character replaced individually, add the following key to your web.config:

<add key="CMSLimitUrlReplacements" value="false" />

This preference may also be set specifically for the Page URL Path property of pages (and no other URLs) via the key below:

<add key="CMSUseLimitReplacementsForUrlPath" value="false" />

Advanced character replacement customization


You can change the character replacement behavior to deal with specific scenarios, such as handling non-ASCII character sets or
assigning unique replacement strings for specific characters.
This can be achieved by customizing how the system converts URLs into a safe format. See Custom handling of URL path values f
or more information.

Using URL Prefixes


If you need to add a prefix to all URLs on a specific site (e.g. for search engine optimization), you can specify it in Settings -> URLs and
SEO -> Default Url path prefix. The URLs use the following format: <domain>/<path prefix>/<page URL path>
For example: http://www.example.com/myprefix/products/kentico-cms.aspx

Using language prefixes for URLs


To add a different URL prefix for every page culture version, type the prefix into the Settings -> URLs and SEO -> Use language prefix for
URLs setting. If you have both language prefixes and standard URL path prefixes enabled, the standard URL prefix always precedes the
language prefix in the URL. Refer to Configuring URLs for multilingual websites for more details.

Reference - URL settings


The above configuration tasks can be performed via the Settings application in the URLs and SEO category. The following table shows an
overview of the available settings:
URL format
Forbidden URL characters

List of additional characters that cannot be used in URLs (page


aliases and URL paths).
The following characters are forbidden by default:
\/:*?"<>|&%.'#[]+= and the space character.

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.

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/<node alias>/myimage.aspx
If empty, the file URLs end with no extension: getfile/<node
alias>/myimage

Excluded URLs

Specifies a list of URLs that are excluded from the URL rewriting
engine. See Excluding URLs from the rewriting engine for more
information.

Page URLs
Default URL path prefix

Defines a default URL path prefix used for all URLs of content
pages. Internally, this prefix is rewritten to the urlpathprefix query
string parameter.

Use name path for URL path

If checked, the system automatically copies page name paths to


the URL path.

Use permanent URLs

If enabled, URLs of pages and page attachments are generated in


permanent format. If disabled, friendly URLs are used. Learn more
in Linking pages and files.

Remember original URLs when moving pages

Indicates if the system creates new page aliases when a user sets
a new page URL path or extension for a page.

Automatically update page alias

If enabled, the alias of pages is automatically updated to match any


changes in the name of the given page in the default culture. When
enabled, the page alias property cannot be edited manually.

Other settings (related to SEO) may also affect the format of URLs. To learn about these, refer to the Search engine optimization chapter.

Setting page aliases


Pages can have an unlimited number of different URLs. To configure URLs, select a page in the content tree of the Pages application and
open the Properties -> URLs tab:
Page alias - the unique name of the page in the given section of the website. Aliases form the alias path of each page, which
contains all parent pages up to the root of the site's content tree. The alias path of a page is then used to generate its default URL.
For example, if you set a page's alias to Media, then the URL is: <site domain>/<parent page alias path>/Media.aspx
Page URL path - the fields in this section specify an alternate URL for the page, regardless of its position in the website hierarchy.
For example, if you select the Standard URL or wildcard Path type and enter /Medialibrary, the URL of the page is: <domain>/Medial
ibrary.aspx

Adding page aliases


You can add more URLs to pages through page aliases. Aliases do not change how the system generates the main URL of a page, they only
make the given page available under other URLs.
To create page aliases:
1.
2.
3.
4.
5.

Open the Pages application.


Select the page in the content tree.
Open the Properties -> URLs tab.
Click Add new alias in the Page aliases section.
You can fill in the following properties for each alias:
Property
Path type
________________

Description
You can choose several different URL types for the alias path:
Standard URL or wildcard - the alias URL is handled by
the standard Kentico rewriting engine. Wildcard URLs can
be used here, as described in Wildcard URLs.
Route - the alias URL is processed as an ASP.NET Route
pattern.
MVC - requests to the alias URL are handled as requests
for an MVC page. See Developing sites using the MVC
framework for more information.
The selection determines how the system processes the value
of the Path or pattern property.

Path or pattern

Enter a URL path for the page alias according to the selected
Path type.
For example, if you enter /Mediagallery as the value, you can
then access the page under the following URL: <domain>/Medi
agallery.aspx

Default controller
(MVC only)

The name of the MVC controller containing the action


performed when the alias URL is accessed, without the Control
ler part at the end. For example, if the class is called NewsMV
CController, enter NewsMVC.
The system first searches for the specified class in the CMS.C
ontrollers.<current site code name> namespace. If it is not
found there, the CMS.Controllers.Global namespace is
searched.

Default action
(MVC only)

Specifies the MVC action that the controller performs when the
page is accessed through the alias URL.

Alias redirection

Determines how the system handles (redirects) the URL when


the page is accessed through the alias:
Use site settings (default) - with this option, the
redirection behavior follows the Redirect page aliases to
main URL setting specified for the website in Settings ->
URLs and SEO.
Redirect to main URL - if selected, the system always
redirects the alias URL to the page's main URL, i.e. the
alias path or custom URL path (if specified).
Do not redirect - if selected, the system does not redirect
the alias URL. This option is recommended if the URL of
the alias contains a wildcard.
See also: Search engine optimization

Culture

Determines which language version of the page the system


displays when the page is access through the alias URL.

URL extensions

Specifies additional supported extensions for the alias URL. To


use custom extensions, you need to configure the system
according to the instructions in Custom and extensionless
URLs.
This field is optional.

Track campaign

The system assigns visitors who access the page through the
alias to the selected web analytics Campaign.
For example, you can create a special alias for a page and
then use the alias URL in links contained in marketing
materials, such as banners, e-mails etc. This allows the
system to monitor how many page views the website receives
as a result of the campaign and track the activity of the visitors
who arrive as a result.
This field is optional.

6. Click Save.
If you now switch back to the page's Properties -> URLs tab, the new alias appears in the Page aliases section. You can add any number
of aliases.

Viewing all aliases on a website


You can access a list of all aliases defined on the website (for all pages).
1. Open the Pages application.
2. Select a page with an alias in the content tree.
3. Open the Properties -> URLs tab.
4. Edit ( ) any alias.
5. Click View all aliases in the page header.
The information provided can help you avoid URL collisions when creating new aliases, and allows you to manage aliases from a single
location.

Automatic creation of new page aliases


You can configure the system to automatically create new page aliases when a user sets a new URL path, alias or extension for a page:
1.
2.
3.
4.

Open the Settings application.


Select the URLs and SEO category.
Enable the Remember original URLs when moving pagessetting.
Click Save.

Wildcard URLs
Wildcard URLs provide a way to load content dynamically depending on the page URL.
You can find an example on the sample Community starter site. The Members -> Profile page uses wildcard URLs to display user profiles
a single page displays profiles of various site users.
How is it achieved? Log in to the administration interface and open the Pages application. Select the Members -> Profile page in the content
tree and switch to the Properties -> URLs tab. You can see /Members/{UserName} in the Page URL path field. The {UserName} part of
the URL is the actual wildcard.

If you type <domain>/Members/David.aspx into your browser, the Members -> Profile page opens. The system converts the wildcard part
of the URL (David) into a query string parameter, so that the internal URL actually looks like <domain>/Members/Profile.aspx?username=
David. The name of the parameter is taken from the name of the wildcard, and the value is the matching part of the entered URL. The User
public profile web part which is placed on the page recognizes the username parameter in the rewritten URL and displays David's profile.

Default wildcard values


You can set default values for wildcards in URLs. Use the following format in the URL path: {<wildcard name>;<Default value>}. Default
values are useful when you want to have a wildcard in a page's URL path, but expect that the wildcard part may not always be present in the
URL. The default value ensures that the system always generates the URL with a certain value in the wildcard.
For example, open the sample Community site in the Pages application and select the Members page. Switch to the Properties -> URLs ta
b, enter /Members/{UserName;David} into the Page URL path field and click Save. If you now access the Members page on the live site, the
page displays David's profile by default.
Additionally, the current value of a wildcard is always used as the default value in all other URLs on the given page that contain the same
wildcard. For example, imagine a scenario with two pages that use a wildcard in their URL path: the first set to /Profile/{UserName} and the
other to /Profile/{UserName}/Details. When the first page is accessed through the URL <domain>/Profile/Andy.aspx, navigation links to the
second page are automatically generated as <domain>/Profile/Andy/Details.aspx. The current value is used even for wildcards that have a
different default value set in the URL path.

Using wildcard URLs on multi-language sites


The Page URL path is unique for each language version of a page. As a result, you may encounter problems when referring to a page using
a wildcard URL on multi-lingual sites.
For example, on the sample Community Starter site, the Members/Profile page has the Page URL path set to /Members/{UserName}. If
you create a version of this page in another language, the Page URL path is automatically changed to /Members/{UserName}-1. This
happens because the URL path needs to be unique for every page.
Now let's presume that you have the following link leading to the page: <domain>/Members/David.aspx. In the original version, it works
fine. But if you try to click the link in the second language version, no profile is found, because the URL in this language version is <domain>/
Members/David-1.aspx. The modification added to the end of the URL path changes the wildcard value representing the user name, which
makes it impossible to find a matching user profile.
If you want to keep such links functional in all language versions, you need to define the /Members/{UserName} path via the Page aliases s
ection, as described in Setting page aliases. When creating the alias, select (all) in the Culture drop-down list. Before you can do this, you
must erase the Page URL path value for both language versions of the page.
Keep in mind that it is not possible to specify default wildcard values through page aliases. An alias only makes the page
accessible through a given URL, it does not enforce this URL for the page.

Dots in wildcard URLs


You may encounter problems when string containing a dot character (".") get into the wildcard parts of URLs. A typical example of this can be
found on the Members -> Profile page of the sample Community Starter Site.
The page's Page URL path is /Members/{UserName}. For the username jack.smith, the profile page URL is http://<domain>/Members/ja
ck.smith. Since the last part of the URL after the last dot (smith in this case) represents the extension, the URL returns a 404 error.
To prevent this, registration on the sample Community Starter Site doesn't allow user names with dots. If you need to allow dots in user
names and use wildcard URLs with user names at the same time, move the wildcard in the Page URL to the middle of the URL, for example:
/Members/{UserName}/Profile

Custom and extensionless URLs


You can configure the system to use custom URL extensions and extensionless URLs.
Custom URL extensions allow you to change the default .aspx extension to .html, .asp, .php, or any other value.
For example, instead of the default http://www.example.com/news.aspx, you can have URLs ending with .html:
http://www.example.com/news.html
you can also configure extensionless URLs:
http://www.example.com/news
To use custom URL extensions, take the following steps:
1. Adjust your web.config or IIS to handle custom extensions
2. Configure custom URL extensions in the Kentico settings

Configuring IIS to allow custom URL extensions

Note: This procedure only works for IIS 7 sites that use an Application Pool with Managed Pipeline Mode set to Integrated.
1. Edit your application's web.config file.
2. Find the <modules> element inside the system.webServer section directly under the web.config root (i.e. not under a specific <loca
tion> element).
3. Set the runAllManagedModulesForAllRequests attribute to true for the opening <modules> tag:

<system.webServer>
...
<modules runAllManagedModulesForAllRequests="true">
<remove name="WebDAVModule"/>
<remove name="XHtmlModule"/>
<remove name="CMSApplicationModule"/>
<remove name="UrlRoutingModule-4.0"/>
...
</modules>
...
</system.webServer>

With this modification in your web.config, configure the extensions in the Kentico administration interface. You can also perform additional
configuration as described below.

Optional configuration (recommended)


It is recommended to configure a custom Page-not-found (404) error page when using custom URL extensions, otherwise a blank page may
be displayed in some browsers if a user attempts to access a nonexisting resource.
1. In the Kentico administration interface, open the Settings application.
2. Select the Content category.
3. Enter the URL of the appropriate page (or aspx web form) into the Page not found URL setting, for example: ~/CMSMessages/Pag
eNotFound.aspx.
Please read Creating custom error handling pages to learn more.
Alternatively, you can add a <httpErrors> element into the system.webServer section of your web.config file according to the following:

<httpErrors existingResponse="Auto" errorMode="Custom">


<clear/>
<error statusCode="404" responseMode="ExecuteURL"
path="/<Virtual_Directory>/CMSMessages/PageNotFound.aspx" />
</httpErrors>

Replace the <Virtual_Directory> string in the value of the path attribute of the <error> element with the name of the virtual directory where
you run Kentico.
You can also add the following key to the AppSettings section of the web.config file, which ensures that URLs remain the same even after
postback.

<add key="CMSUseExtensionOnPostback" value="false" />

If you are using trailing slashes (enabled through the Use URLs with trailing slash setting in Settings -> URLs and SEO), you can use the
following extra key to have only extensionless URLs ending with the trailing slash. URLs ending with an extension are rendered without the
slash when the key is used.

<add key="CMSUseTrailingSlashOnlyForExtensionLess" value="true" />

Using the cmspages/handler404.aspx page (obsolete)


For the purposes of backward compatibility, you can also set error pages by configuring your IIS manually. This approach is required for sites
that use an application pool in Classic Managed Pipeline Mode.
1. Open Start -> Control Panel -> Administrative Tools -> Internet Information Services (IIS) Manager.
2.

2. Select your website from the tree and open the Error pages section.
3. Right-click the 404 error and select Edit Feature Settings.
If you receive a Lock violation message when configuring the following step, proceed to Troubleshooting custom and
extensionless URL configuration.

4. Enter the following values:


Path: enter the URL of the cmspages/handler404.aspx page according to your application's URL.
Example: if you run your web project in virtual directory /kentico, you need to enter
/kentico/cmspages/handler404.aspx
Path type: Execute URL
5.
6.
7.
8.
9.

Click OK.
Right-click the 404 error again and select Edit.
Select Execute a URL on this site and enter the same URL that you entered in step 4. Click OK.
Go back to step 3 and repeat the same procedure for the 405 error.
Click OK in all dialogs to save the changes. It's not necessary to restart the application.

Setting up extensions in IIS manually (obsolete)


The following approach is also possible, but not recommended and considered obsolete. For example, to use the .html extension, go
through the following steps:
1.
2.
3.
4.
5.

Run Internet Information Services (IIS) Manager.


Select your website.
Open Handler mappings.
Click to Add managed handler... .
Enter the following values:
Request path: *.html
Type: System.Web.DefaultHttpHandler
Name: HTML

6. Click OK.

Setting custom URLs


Once you have performed the required low-level configuration, set the URL extensions in the Kentico administration interface:
1.
2.
3.
4.

Open the Settings application.


Select the URLs and SEO category.
Type the required extension into the Friendly URL extensions setting, for example: .html
Click Save.

Now when you go to the live website, the system renders all URLs in menus and listings with the specified extension. You may need to
manually update static links that were created with the default .aspx extension.

Setting extensionless URLs


To configure the system to use URLs without an extension, save an empty value into the Friendly URL extensions setting.

Using multiple extensions


You can enter multiple extensions into the Friendly URL extensions setting. Use the following rules:
The first extension is used as the default
Enter other extensions, separated by semicolons. Pages can be accessed through URLs ending with all entered extensions.
To allow extensionless URLs in combination with other extensions, enter a semicolon without an extension
Examples:
;.aspx - extensionsless URLs by default, also allows aspx
.html;.htm;;.asp - html extension by default, also allows htm, extensionless and asp
If you enable the Redirect pages to main extension setting in Settings -> URLs and SEO, the system redirects URLs with non-default
extensions to the corresponding URL with the default extension. This can be useful for SEO purposes. For example, if you want to change
your site's URL extension, and use the new extension when the pages are accessed from a search engine that has your website indexed
with the old extension.

Page-level extension settings


In addition to the global settings, you can set URL extensions for individual pages. The default extension that appears in the browser address
bar when opening pages is always taken from the global settings.
1. Open the Pages application.
2.

2.
3.
4.
5.
6.

Select the page in the content tree.


Switch to the Properties -> URLs tab.
Select the Use custom URL extensions check box.
Type the required extensions using the same rules as described above.
Click Save.
Even if the Use custom URL extensions option is disabled, files (cms.file pages) can be accessed under their physical
extensions.

Troubleshooting custom and extensionless URL configuration


When configuring your IIS 7 (or later) to allow custom extensions or extensionless URLs, you may receive the Lock violation error message
(especially if you are running Kentico in a virtual directory).
This may be caused by a locked defaultPath attribute in the httpErrors section. You can check and unlock it in Internet Information
Services (IIS) Manager. Select your site (IIS site) and open Configuration Editor (it is included in the Management section in the standard
installation of IIS 7.5, if you are using IIS 7, you can download and install it as a part of the IIS7 Administration Pack).

In the Configuration Editor, choose system.webServer/httpErrors in the Section drop-down.


If there is a lock icon next to the defaultPath attribute, right-click the attribute name and select the defaultPath Attribute -> Unlock
Attribute action. If the option is missing in the menu, you probably need to unlock it on a higher level in the IIS tree, i.e. on the parent site or
on the root of the server.

Click Apply to save the changes. From now, the Lock violation errors shouldnt appear.

Linking pages and files


Creating permanent links to pages
If you need to create a permanent link to a page, use a URL in the following format:

<domain>/getdoc/<page GUID>/<page name><extension>

<page GUID> is the globally unique identifier of the page. You can find a page's GUID value in Pages -> Properties -> General ->
Node GUID.
The <page name> value may contain any text it is not used by the system, but allows you to specify the exact URL (e.g. for the
purposes of search engine optimization). By default, the system uses the page's name.
Permanent links keep working even if you move the target page to another location.
For example:
http://www.example.com/getdoc/016fad52-0d69-46d5-80dc-daec9173c0c7/Products.aspx
is the permanent equivalent of:
http://www.example.com/company/products.aspx

Linking specific language versions of pages


If you need to link to a specific language version of a page, you use a URL in the following format:

<domain>/getdoc/<page GUID>/<page name>/<culture code><extension>

For example:
http://www.example.com/getdoc/8FG7-84E394-FABD-5678/our-services/fr-fr.aspx
Displays the given page in French (if the page is translated). It is an equivalent of:
http://www.example.com/company/our-services.aspx?lang=fr-fr

Linking attachments
If you need to create a permanent link to a file uploaded as a page attachment, you use a URL in the following format:

<domain>/getattachment/<file GUID>/<filename><extension>

The <file GUID> is not the same as the page GUID. It is the GUID of the file in the CMS_Attachment database table. To find the
GUID of an attachment, click the attachment in Pages -> Properties -> Attachments and view the URL.
The <file name> value can contain any text.
For example:
http://www.example.com/getattachment/763c8921-be94-4610-99b4-25e8d3be5b08/logo.aspx

GetFile.aspx parameters
The system uses the GetFile.aspx page to retrieve uploaded files from the database. The page is called whenever you use /getdoc,
/getattachment or a direct URL based on the alias path of a CMS.File page.
GetFile URLs accept the following query string parameters:
Parameter name

Description

Sample value

guid

Attachment GUID value.

nodeguid

Node GUID value.

versionhistoryid

Version history ID of the attachment. It can


only be used together with the guid param
eter.

width

Resizes the image to a specified width (in


pixels).

100

height

Resizes the image to a specified height (in


pixels).

400

maxsidesize

Resizes the image to the specified size of


the longest side (in pixels).

500

disposition

Indicates the output disposition of the file.

inline

You can use one of the following


disposition values:

or
attachment

inline - opens the file in the browser


window if possible
attachment - opens the browser's
"Save or Open" dialog

Resizing of images
If your website has the Resize images according to device profile setting enabled in Settings -> Content -> Content
management, the system may override the width, height and maxsidesize parameters used in GetFile URLs of image files.
When a user views the website on a device that matches a device profile, images automatically reduce their maximum side size to
the larger of the dimensions set for the given profile.
To configure the dimensions of device profiles:
1. Open the Device profiles application.
2. Edit ( ) a profile.
3. Set the Preview width and Preview height properties.
4. Click Save.
If you wish to disable device profile resizing for an image, add the resizemode=1 parameter to the GetFile URL.

Custom handling of URL path values


To ensure that URLs can be processed correctly, the system checks text values for unsafe characters before they are added to the URL
path, and makes any necessary changes. This affects fields such as page aliases, page URL paths, forum names, post subjects etc.
By default, the process includes removal of diacritics and replacement of all forbidden characters according to the settings defined for the
given site (as described in URL format and configuration). Characters with diacritics are replaced by the appropriate base character, for
example is converted to u.
If you need to change the default behavior in any way, you can register and implement a handler for one or both of the following system
events:

OnBeforeGetSafeUrlPath - occurs whenever a potentially unsafe text value is added to a part of a URL, e.g. when the page alias
field is saved (or filled automatically based on the page's name). This event can be used to customize the final format of URL paths.
For example, you can convert characters from an international character set to an equivalent in Latin characters (ASCII) or specify a
unique replacement string for particular forbidden characters.
OnBeforeRemoveDiacritics - occurs whenever the system removes diacritics from text. This is one of the default steps performed
when creating safe URLs, but the event is also triggered during many text parsing operations that are not directly related to URLs
(for example when indexing text for the Smart search).
The events are members of the URLHelper and TextHelper classes respectively, which can be found under the CMS.Helpers namespace.
The handlers for these events have the source text included as a string parameter passed by reference, so any changes that you
make in the code are reflected in the result.
Both handlers have a boolean return value that indicates whether the default functionality should also be performed after the handler
is executed. For this reason, it is highly recommended to set the return value to true for all but the most extensive customizations.
Warning
Only return a false value if you are sure that your custom handler can take full responsibility for all URL safety or diacritics removal
requirements.
Disabling the default system functionality may prevent parts of your website from working correctly, particularly in the case of
handlers for the OnBeforeGetSafeUrlPath event.

Example
The following example demonstrates how to define handlers for the forbidden character events:
1. Open your Kentico web project in Visual Studio.
2. Expand the App_Code folder (or CMSApp_AppCode -> Old_App_Code if your project was installed as a web application) and
create a new class.
3. Edit the class and add the following references:

using CMS.Base;
using CMS.Helpers;

4. Delete the default class declaration and its content. Instead, add the following code:

[URLFormatHandlerLoader]
public partial class CMSModuleLoader
{
/// <summary>
/// Custom attribute class.
/// </summary>
private class URLFormatHandlerLoaderAttribute : CMSLoaderAttribute
{
/// <summary>
/// Called automatically when the application starts.
/// </summary>
public override void Init()
{
// Assigns a handler to the OnBeforeGetSafeURLPath event
URLHelper.OnBeforeGetSafeUrlPath += Custom_OnBeforeGetSafeUrlPath;
// Assigns a handler to the OnBeforeRemoveDiacritics event
TextHelper.OnBeforeRemoveDiacritics += Custom_OnBeforeRemoveDiacritics;
}
}
}

This extends the CMSModuleLoader partial class and defines a new attribute. The override the Init method of the CMSLoaderAttri
bute attribute class allows you to assign custom handlers for events.

5. Add the definition of the Custom_OnBeforeGetSafeUrlPath handler into the private class:

static bool Custom_OnBeforeGetSafeUrlPath(ref string url, string siteName,


EventArgs e)
{
// Replaces all & characters with the word "and"
url = url.Replace("&", "and");
// Returns true to indicate that the default URL replacements should also be
performed (i.e. removing diacritics and forbidden characters)
return true;
}

This code replaces all ampersand (&) characters with the word and. For example, a page named Products & Services has
its default page alias generated as Products-and-Services, which is then used in the page's URL. This example is only
meant as a simple demonstration. In realworld scenarios, the handler can be much more complex, for example when
mapping the character set of an international language to appropriate ASCII characters or words.
The siteName parameter of the handler contains the code name of the site under which the event occurred. This can be
useful if you need to access the forbidden character settings of the given site in your custom code.

6. Add the Custom_OnBeforeRemoveDiacritics handler:

static bool Custom_OnBeforeRemoveDiacritics(ref string text, EventArgs e)


{
// Replaces German special characters
text = text.Replace( "", "ae" );
text = text.Replace( "", "oe" );
text = text.Replace( "", "ue" );
text = text.Replace( "", "Ae" );
text = text.Replace( "", "Oe" );
text = text.Replace( "", "Ue" );
text = text.Replace( "", "ss" );
// Returns true to indicate that the default diacritics removal should also
be performed
return true;
}

This ensures that the system uses custom replacements for German special characters rather than simply stripping the
diacritics and leaving the base character.

7. Save the file. Build your project if it was installed as a web application.
The system applies the changes when creating new URLs and when removing diacritics from text.
Note: The customization does not automatically change the aliases and URL paths of existing pages until the current value is
changed or saved.

Search engine optimization


Search engine optimization (SEO) is a process that attempts to improve the page rank of a website. The rank determines the site's organic
position in the results of web search engines (such as Google). Being higher in search results benefits the site by naturally attracting more
visitors.
While Kentico cannot guarantee by itself that your website will have good search engine optimization, it provides many features that simplify
related configuration tasks and make it easier to follow general best practices. Additionally, the system ensures a solid SEO foundation by

generating pages with valid, standards compliant output code, and page URLs in a search engine friendly format.
Tracking search engine traffic
You can use web analytics to review the results of your website's SEO. Tracking is supported for:
Traffic gained from search engines
The activity of web crawlers on your site's pages
See: Monitoring traffic from search engines

Configuring websites for SEO


This page describes the Kentico settings that can affect your website's SEO.

Editing the metadata of pages


An important SEO consideration is the metadata of individual pages. To edit the metadata of a page:
1. Open the Pages application.
2. Select the corresponding page in the content tree.
3. Open the Properties -> Metadata tab.
You can set the following SEO-related properties:
Property
Page title

Description
The page title is displayed to users in the header of their browser
(or tab) when the page is viewed. Many search engines use this
title for the page in their search result lists.
The system adds the content of the field into the <title> element in
the HEAD section of the page's output.

Page description

A brief description of the page and its purpose. The description can
be used for SEO purposes and when performing searches on the
website.
The system adds the content of the property as a description meta
element in the HEAD section of the page's output. Some search
engines index this tag.

Global metadata settings


You can configure a prefix for the page title and description for all pages. Use the corresponding settings in Settings -> Content.
The settings allow you to set the prefixes and also the overall format of the page title.
The default page title format is: {%prefix%} - {%pagetitle_orelse_name%}
The title format consists of the prefix value, followed by the page title value. If the page title value is not set, the page name is
used.
Macro expressions in metadata
Use macro expressions in format (% ColumnName %} to dynamically insert values of page fields into metadata values.

SEO settings
You can configure most of the SEO functionality of your website through the Settings application in the URLs and SEO category. The
settings here are divided into three main sections.

Search engine optimization (SEO)


Before search engines can provide results that link users to your website, they need to index the site using web crawlers (robots). The
settings in this section allow you to use standard techniques for giving instructions to crawlers. You can also enable several options that help
crawlers easily and accurately index the pages on your website.
Setting
Google sitemap URL

Description
These two settings set up the URL of the website's Google (XML)
sitemap and the path of the source page. The sitemap allows you

Google sitemap path

to instruct web crawlers how to index the site's pages.


See also: Google Sitemaps

Robots.txt path

Specifies the path of the page that generates the website's robots.
txt file.
See also: Managing robots.txt

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 not to


follow links posted by users on Forums, Message boards or in Blog
comments. This is achieved by including the rel="nofollow" attribute
in the output code of all such link tags.
This can prevent damage to your website's search ranking caused
by usergenerated links that lead to unrelated content. The setting
can also help stop spammers from passing page rank to other
sites.

Default replacement page

See the Assigning replacement pages for deleted pages section


below.

Assigning replacement pages for deleted pages


Removing pages can have a negative effect on your website's traffic. Visitors may find it confusing if pages suddenly become unavailable (for
example if they have a deleted page bookmarked). Another thing to consider is that deleted pages might be indexed by search engines,
which then provide invalid links in their search results until they reindex the site's content.
You can mitigate these problems by setting up other pages as replacements when deleting pages:
1. Open the Pages application.
2. Select the page that you wish to remove.
3. Click Delete ( ).
4. Select the Display alternate page when visitors access the deleted page check box.
5. Specify the path of the Replacement page.
The field loads a default value from the Default replacement page setting of the current website, but you can enter a
different path for each specific case.
6. Enable or disable the following configuration options:
Copy all paths - if checked, the website uses the replacement page for all possible URL paths of the deleted page
(including any page aliases). If false, the replacement only covers the main URL of the deleted page, i.e. the corresponding
page's custom URL path (if one is specified) or alias path.
Include child nodes - if checked, the website uses the replacement page for all child pages removed along with the deleted
page.
7. Click Yes.

Once you confirm the deletion, the system automatically adds page aliases to the replacement page. These aliases ensure that the website
serves up the replacement page whenever a visitor requests the URLs of the deleted page. When combined with permanent 301 redirection,
the replacement aliases also properly inform search engine crawlers about the change in your website's structure.

SEO - URLs
The settings in this section allow you to configure URL rewriting that focuses on avoiding issues with duplicate content, i.e. having the same
content available under multiple URLs. Such problems can have a negative effect on search ranking, so it is recommended to set up a
unified URL format.
Setting
Use URLs with trailing slash

Description
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. 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 pages aliases
through their Alias redirection property.
For more information about page URLs, see Setting page aliases.

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 URL 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: 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 page specified by the website's Content -> Default
alias path setting.
Use default page URL - always uses the default URL: <doma
in>/default.aspx
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
The options in this section are important when performing search engine optimization of multilingual websites. The following settings allow
you to set up unique URLs for different language versions of pages in a search engine friendly format.
Setting
Force domain culture

Description
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 (
Sites application:

) your site in the

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: <domain>/en-US/Home.aspx

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.

See also:
Configuring URLs for multilingual websites
Multilingual websites

Google Sitemaps
Kentico allows you to automatically generate sitemaps for your websites according to the Google Sitemap Protocol. Sitemaps help search
engines correctly index the content of websites and can have a significant effect on the resulting search ranking.
A sitemap is an XML file that lists the URLs of a website's pages along with additional metadata. Search engine crawlers (robots) use the
sitemap data to determine which pages to index and how often to re-index pages. Sitemaps only serve as a recommendation and do not
guarantee that all crawlers will index your website strictly according to the specified data.
For detailed information about the Sitemap protocol, see http://www.sitemaps.org/.

Setting the sitemap URL


To adjust the URL of your website's sitemap:

1.
2.
3.
4.

Open the Settings application.


Select the URLs and SEO category.
Enter the required URL into the Google sitemap URL setting.
Click Save.

For example, the default value googlesitemap.xml means that web crawlers can access the sitemap through the following URL:
<website domain>/googlesitemap.xml
Using the .xml extension
If you want to have your sitemap available under a URL with the .xml extension, you need to configure your application to handle
all types of request extensions:
1. Edit your application's web.config file.
2. Find the system.webServer section directly under the web.config root (i.e. not under a specific <location> element).
3. Add the following attribute to the <modules> element:

<modules runAllManagedModulesForAllRequests="true">

Defining the sitemap content


The system generates sitemaps for websites based on the pages stored in the content tree.
By default the sitemap:
Only contains pages of the CMS.MenuItem type
Automatically excludes all pages whose parent page is not in the sitemap, such as pages stored under folders or custom page types
You can modify the content of your website's sitemap by creating a dedicated sitemap page:
1. Open the Pages application.
2. Create a new Page (menu item) page in your website's content tree.
You can use the predefined SEO -> Google Sitemap page template to quickly create sitemap pages. This template
contains the required web part by default.
3. Place the Google Sitemap (XML Sitemap) web part onto the page.
Adding this web part stops the page from displaying standard content. Instead, the page returns an XML response with the
sitemap data.
The web part only generates output when the page is accessed on the live site.
4. Configure the content of the sitemap through the web part's properties.
You can limit which pages are included in the sitemap by entering an appropriate Path expression.
5. Open the Settings application and select the URLs and SEO category.
6. Enter the path of your sitemap page into the Google sitemap path setting.
7. Click Save.
The sitemap generated by the web part replaces the default sitemap. Search crawlers can access the sitemap either under the main URL
specified in the Google sitemap URL setting, or directly through the URL of the page containing the Google Sitemap web part.
Customizing the default sitemap directly
If you do not wish to use portal engine pages and web parts, you can instead edit the markup of the ~/CMSPages/googlesitemap.a
spx system page. This page generates the default sitemap for websites that have an empty Google sitemap path setting.
The GoogleSitemap control on the page provides the same configuration options as the Google Sitemap web part.

Troubleshooting:

If you encounter problems with pages missing in your sitemap, try checking for the following:
Manually excluded pages - specific pages may be excluded through their sitemap properties (Show in sitemap or Exclude from
search).
Incorrect content filtering - review the content filtering properties of your Google Sitemap web part.
If the Page types property is empty, the sitemap only loads CMS.MenuItem pages. Add the page types that you wish to
have in the sitemap. You can use the asterisk (*) wildcard to specify all page types.
Broken page hierarchy - sections of the website may be excluded due to parent pages missing in the sitemap. To load all pages
regardless of the parentchild hierarchy in the content tree, disable the Hide children for hidden parent property of the Google
Sitemap web part.

Configuring sitemap settings for specific pages


By filling in the sitemap properties of pages, you can exclude specific pages from sitemaps or give search crawlers additional details
describing how to index pages:
1.
2.
3.
4.

Open the Pages application.


Select the page in the content tree.
Open the page's Properties -> Navigation tab.
Set up the following properties:
Basic properties
Show in sitemap

Sitemaps only list pages that have this property enabled.

Search & SEO


Exclude from search

Marks the page to be ignored by all forms of search, including


search engines.
Enabling this checkbox excludes the page from sitemaps by
default. However, individual Google Sitemap web parts can
override this setting and generate sitemaps including pages
that are excluded from search.

Sitemap change frequency

Determines the value of the page's <changefreq> tag in the


sitemap. This metadata provides a suggestion to search
engines about how often they should re-index the page.
Choose a value that reflects how frequently the page's content
changes.

Sitemap priority

Allows you to inform web crawlers which pages you consider


to be the most important.
The system converts the selected priority to a decimal number
between 0 and 1 and adds the number as the value of the
page's <priority> tag in the sitemap. Web crawlers only
measure the priority in relation to other pages on the website.

If you enter the URL of the sitemap into your browser, you can review the generated XML output. The system automatically creates the
required XML structure.

The <url> elements represent individual pages.


The sitemap loads the values of the <loc> and <lastmod> tags from the data of the corresponding pages.
The <changefreq> and <priority> optional tags are added for pages that have values in their Sitemap change frequency and Site
map priority properties.

Creating sitemap indexes


A single XML sitemap can only list up to 50 000 pages (URLs). If you need to include more pages, prepare multiple sitemaps and create a
sitemap index for your website:
1. Add any number of sitemap pages, each one containing its own Google Sitemap web part.
2. Separate your website's pages between the sitemaps by configuring the content filtering properties of the web parts.
Each sitemap can contain a maximum of 50 000 items.
Avoid duplicate content do not list the same page URLs in multiple sitemaps.
3. Create the index as another page with a Google Sitemap web part.
Switch the Sitemap mode property of the web part to Sitemap index.
Configure the content filtering properties so that the sitemap index web part loads only the pages representing your
sitemaps.
4.

3.

4. Enter the path of your sitemap index page into the website's Google sitemap path setting.
This ensures that crawlers process the sitemap index first.
The sitemap index points search engine crawlers to the other sitemaps, which then provide the lists of page URLs in the usual way.

Customizing the XML format of sitemaps


If you need to override the default XML format of a sitemap or index, you can specify a custom transformation for the Google Sitemap web
part or GoogleSitemap control. This allows you to react to any changes in the Sitemap protocol.
For example, the default CMS.Root.GoogleSiteMap transformation uses the following code to define the sitemap structure:

<url>
<%# GetSitemapItem("loc") %>
<%# GetSitemapItem("lastmod") %>
<%# GetSitemapItem("changefreq") %>
<%# GetSitemapItem("priority") %>
</url>

The GetSitemapItem transformation method generates XML tags according to the sitemap protocol. The method's parameter specifies the
type of the tag, and the value is dynamically loaded from the data of the transformed pages.
In the final XML output, the web part automatically encloses the transformed items within either a <urlset> or <sitemapindex> element
depending on the selected Sitemap mode.

Creating sitemaps for multilingual websites


Websites that offer content in multiple languages use different URLs for different language versions of the same page.
To include pages from all languages in your sitemap, you need to use one of the approaches described below.

Submitting separate sitemaps for different language versions of the website


One way to handle multilingual content is to present a separate sitemap for each language version of the website. This approach works best
if your website is fully translated into all supported languages.
You do not need to create multiple sitemaps. When submitting your sitemap to search engines, add the appropriate language modifiers to the
sitemap URL. The format must match the URL structure that you use to identify language versions on your website.
See Configuring URLs for multilingual websites for detailed information about the available options.
Multilingual URL structure

Description

Separate domain names

Use the appropriate domain name when


submitting the sitemap URL.

http://domain.com/googlesite
map.xml

The sitemap automatically loads the page


URLs for the language that matches the
domain name.

http://domain.fr/googlesitem
ap.xml

Include the language prefix when


submitting the sitemap URL.

http://domain/en-us/googlesi
temap.xml

URL language prefixes

Examples of full sitemap URLs

http://domain/fr-fr/googlesi
temap.xml
URL language parameters

Add the language query string parameter


when submitting the sitemap URL.

http://domain/googlesitemap.
xml?lang=en-us

Warning: This approach is not


recommended. If your website does not use
culture-specific domains or language
prefixes, URL conflicts may occur between
the different language versions of the same
page.

http://domain/googlesitemap.
xml?lang=fr-fr

The sitemap automatically lists the pages from the language version of the website specified by the full sitemap URL.
Important
To ensure that the sitemap dynamically presents pages for the language determined by the sitemap URL, you need to leave the C
ulture code property of your Google Sitemap web part with an empty value.

Preparing one sitemap for all languages used on the website


You can list the URLs of the pages from all language versions of the website inside a single sitemap. This approach is most suitable for
websites that are not fully available in the non-default languages, i.e. if only a limited number of pagesis translated.
1. Create a separate sitemap page for each language, each one containing its own Google Sitemap web part.
Assign the language through the Culture code property of the web part.
Set the Combine with default culture property to No (prevents duplicate entries if your website uses the default content for
untranslated pages).
2. Add a sitemap index page and configure it to load the language-specific sitemap pages.
Each sitemap page lists the URLs of the pages available for a particular language. The sitemap index combines the output of all
language-specific sitemaps. You can then submit the URL of the sitemap index to search engines without any language modifiers.

Managing robots.txt
You can give instructions to web crawlers and other robots using the Robots Exclusion Protocol, i.e. a robots.txt file. The primary purpose of
robots.txt files is to exclude certain pages from search engine indexing. Like with Sitemaps, the provided instructions are only considered as
recommendations and may be ignored by some robots.

Creating a robots.txt file for your website


The most direct way to use robots.txt in Kentico is to physically add the text file into the root of your web project. However, this scenario does
not allow you to assign different robots.txt files to specific websites (if there are multiple sites running on your installation). Additionally, it may
be difficult to access the file system in certain types of hosting environments.
The recommended approach is to create a dedicated page in your site's content tree and make it return the appropriate text response:
1. Open the Pages application.
2. Create a standard Page (menu item) page.
You can use the predefined SEO -> Robots.txt page template to quickly implement robots.txt pages.
3. Add a Custom response web part to the page.
4. Configure (double-click) the Custom response web part to generate a valid robots.txt response according to the following steps:
a.
b.
c.
d.

Set the Content type property to text/plain.


Enter an appropriate Encoding type, for example UTF8.
Set the Status code of the response to 200.
Add the actual robots.txt instructions into the Content property, just like you would in a physical text file. This property
supports K# macro expressions, so you can dynamically load values from the current system data if needed.

5. Open the Settings application and select the URLs and SEO category.
6. Enter the path of your robots.txt page into the Robots.txt path setting.
You can specify a different value for each site by using the Site selector above the settings tree.
The output of the specified page is always available under the standard <website domain>/robots.txt URL, regardless of the page's location
in the content tree. Compliant web crawlers read the instructions from this URL before processing other pages on the website.
Enabling the .txt extension
To ensure that the <domain>/robots.txt URL is available, you need to configure your application to handle all request extensions:
1. Edit your application's web.config file.
2. Find the system.webServer section directly under the web.config root (i.e. not under a specific <location> element).
3. Add the following attribute to the <modules> element:

<modules runAllManagedModulesForAllRequests="true">

Excluding pages manually


You can also configure individual pages to be excluded from search engine listings without the need to prepare a robots.txt file.
1.
2.
3.
4.
5.

Open the Pages application.


Select the given page in the content tree.
Open the Properties -> Navigation tab.
Enable the Exclude from search property.
Click Save.

The system automatically adds the following meta tag to the <head> section in the HTML output of such pages:

<meta name="robots" content="noindex,nofollow" />

This instructs web crawlers not to index the page and to ignore any links in the content.

Optimizing website performance


The performance of your website depends on many factors:
The total number of pages on your website
The complexity of the website (the depth of the content tree, number of page nesting levels, number of web parts per page)
Custom functionality added to the application or individual sites
The hardware and environment on which the Kentico application and database server are running
The available resources if the server is shared with other applications
Tip: Finding sources of performance problems
Check the system's event log for errors
Use the built-in debugging tools to investigate pages with low performance
Monitor your application using performance counters (EMS license required)

Configure caching for your website


See the Configuring caching chapter for detailed information about the caching mechanisms available in Kentico.
The following basic settings work well for most websites:
1. Go to Settings -> System -> Performance.
2. Choose your website in the Site selector.
3. Set the caching settings:
Cache page info (minutes): 10 or more
Cache content (minutes): 10 or more
Cache files (minutes): 10 or more
Client cache (minutes): 0
Allow client cache revalidation: yes (checked)
4. Click Save.
Note: Caching only improves performance on the second and subsequent page loads.

Use output caching


Output caching is the best way to significantly increase the performance of pages. We recommend caching page output whenever possible,
particularly for high-traffic pages.
See Caching page output for detailed information.
To enable output caching:
1.
2.
3.
4.

Go to Settings -> System -> Performance.


Check Enable output caching.
Save the settings.
Set up output caching for individual pages in Pages -> Edit -> Properties -> General -> Output cache.

Note: You may need to take additional steps to ensure that cached pages do not display outdated content.

Configure file storage and processing


Loading files from the database is a demanding operation. Storing files on the server's file system provides better performance in most
cases:
Requirement: Your application needs to have the Modify permission for the web project directory in the server's file system.
1. Go to Settings -> System -> Files.
2. Enable the following settings:
Store files in file system
Generate thumbnails
3. Consider disabling the following settings to improve loading time of page attachments:
Check if files are published (if you do not use workflow or content scheduling on your website)
Check files permissions (if you do need to restrict access to the attachments of secured pages)
4. Click Save.
See also: Storing files

Organize your website's content in the most effective way


You can store your site's content either in Pages, Custom tables or Media libraries. Each storage type is designed for a different type of data.
Refer to Storing data effectively for more information.

Optimize your data source components


Check the configuration of all components (web parts or controls) that load data from the database or other sources. For best practices and
examples, see Loading data efficiently.

Minimize compilation requirements for pages


If your pages have long initial load times (for example after application restarts), try to reduce the number of components that need to be
compiled:
Switch to the HTML type for page layouts that do not contain controls or inline code.
Use the Text / XML type for simple transformations (if the code is pure HTML or only performs basic loading of field values). For
complex transformations with method calls or other advanced logic, the ASCX transformation type generally provides better
performance.
Consider precompilation of the entire project before deploying to the production environment.

Check custom code


If you integrated custom code into the application (including JavaScript), please make sure it works correctly.
Avoid excessive database operations
Reuse objects whenever possible
Use custom caching when you load data through the API
Try to comment out your code and see if the performance improves.

Disable debugging tools


Always disable all Kentico debugging tools before deploying websites to the production environment:
1. Go to Settings -> System -> Debug.
2. Check the Disable debugging setting.
3. Click Save.

Disable output filters


Applying output filters adds steps to the processing of pages, and may slow down the website. If the output code of your pages is valid
without filtering, you can disable the filters:
1. Go to Settings -> System -> Output filter.
2. Choose your site in the Site selector.
3. Type the / character (forward slash) into the following settings:
Excluded output form filter URLs
Excluded resolve filter URLs
Excluded XHTML filter URLs
Excluded HTML5 filter URLs
4. Save the settings.
The system excludes all pages on the website from the output filter. If you resolve your performance issues by disabling the output filter, but
need to keep the functionality to produce valid code, please contact Kentico support to find a workaround.

Limit scheduled tasks


You can conserve system resources by limiting the execution of scheduled tasks:
Disable all unnecessary tasks
Increase the execution intervals of tasks
Run tasks using the external Windows service if possible

Enable minification and compression of resources


Use code minification and compression to reduce the size of CSS and JavaScript resources. This helps limit the volume of traffic between
the server and clients.

Increase the application pool Idle Time-out in IIS


If your website has periods of inactivity (no requests for over 20 minutes by default), users may experience long delays when first opening
the site. To prevent this, set the Idle time-out (minutes) property of your IIS application pool to a higher value:
1. Open your Internet Information Services (IIS) Manager console (Start -> Control Panel -> Administrative tools -> Internet
Information Services (IIS) Manager).
2. Select <machine>/Application Pools.
3. Right-click the application pool used by the Kentico application and select Advanced Settings.
4. Enter the required value into the Idle Time-out (minutes) property in the Process Model section.

Scale the hosting environment


If performance is still not satisfactory after you have taken all possible steps to optimize your website, you may need to upgrade your hosting
environment:
Scale out - add more servers hosting the same content, and set up a web farm
Scale up - upgrade the hardware of your server
One way to create an easily scalable website is to deploy your instance to cloud hosting.

Loading data efficiently


Many pages use components (web parts or controls) to load and display data from the Kentico database, or other external sources.
Transferring data between storage spaces and the application can be a performance bottleneck.
To maximize data loading efficiency, consider the following points when setting up data source components.

Only load the data columns that you need


When loading data, you usually do not need all columns available in the source. The less data you retrieve, the faster your pages will be.
You can limit which columns data sources load through the Columns (or Selected columns) property. Enter a list of column names separat
ed by commas. We recommend loading only the columns that your components need to display the required results:
Columns used in the code of transformations
Columns inside Where conditions, Order by clauses etc.
When loading Kentico pages, the behavior of the Columns property depends on the type of the data source:
Standard

Standard page data sources load all columns if you leave the Colu
mns property empty. The full list includes the columns of the View
_CMS_Tree_Joined database view, and the coupled data columns
of individual page types.
By setting the Columns property, you specify exactly which of the
columns the data source retrieves.
Note: The system always loads the following columns used to
identify pages:
DocumentCulture, NodeID, NodeLinkedNodeID,
SiteName, ClassName, NodeLevel, NodeOrder,
NodeParentID

Navigation

Data sources of navigation components always load a set of


default columns required to correctly display pages in menus.
The Columns property only allows you to add extra columns.
Leave the property empty unless your component requires a field
that is not included in the defaults.
Note: To find a full list of the default navigation columns, use the S
QL queries debugging tool and inspect the query performed by
your navigation component.

To learn how Kentico stores pages in the database, refer to Page database structure.

Disable unnecessary processing


Page data sources provide features for filtering data according to the settings and status of the website's pages. All such operations add
steps to the data retrieval process and use the system's resources. By disabling filtering options that you do not need, you can reduce

processing overhead when loading uncached data.


Consider the following when configuring the properties of page data sources:
If you are not loading sensitive data (secured pages), disable the data source's Check permissions property.
If the website's pages do not use workflow or content scheduling (i.e. pages are always published immediately), disable the Select
only published property.

Disable view state for web parts


By default, web parts store data in the page's view state. If view state contains a large amount of information, it can slow down page
performance.
You can turn off view state for web parts that do not need to preserve their state across postbacks:
1.
2.
3.
4.

Open the Pages application.


Select the page containing the web part.
On the Design tab, configure the given web part instance (double-click).
Enable the Disable view state property in the Performance category.

Disabling view state reduces processing overhead and the size of the page output that clients need to download. As a result, page load time
improves (depending on the size of the view state).
Note: Test your web parts carefully after disabling view state. Web parts may not work correctly without view state in some
scenarios.

Example - Optimizing a news list


The following example demonstrates how to maximize the performance of a Repeater web part. Repeaters load data from pages in the
website's content tree, and use transformations to format the data into HTML output.
In this sample scenario, the Repeater displays news pages with the following configuration and environment:
The website does not use workflow, all pages are published.
All of the website's pages are publicly available without security requirements.
The Repeater web part:
loads CMS.News pages as the data
uses an ORDER BY expression: NewsReleaseDate DESC
renders the data using the following Text type transformations:

List item transformation


<div class="listBoxWithTeaser">
<div class="teaser">
{% GetImage(NewsTeaser, "", 90) %}
</div>
<div class="description">
<a class="header bold" href="{% GetDocumentUrl() %}">
{% HTMLEncode(NewsTitle) %}
</a>
<p>
<span class="black bold">
By {% GetUserFullName(NodeOwner) %}
</span><br /><br />
{% NewsSummary %}
</p>
</div>
</div>

Expand source

Item detail transformation

Expand source

<div class="listDetail">
<h1>
{% HTMLEncode(NewsTitle) %}
</h1>
<div class="teaser">
{% GetImage(NewsTeaser, "", 230, 230, 500) %}
</div>
<div class="contentText contentTextTeaser">
<div class="summary">
<p>{% NewsSummary %}</p>
</div>
<div class="text">
<p>{% NewsText %}</p>
</div>
</div>
</div>

To optimize how the Repeater loads data, perform the following steps:
1. Open the Pages application.
2. Configure the Repeater web part on the Design tab.
3. Set the following Columns (in the Content filter category):
NewsReleaseDate, NewsTeaser, NewsTitle, NewsSummary, NewsText, NodeOwner, NodeAlias, DocumentURLPath, NodeAliasPat
h
Column used in the ORDER BY expression
Columns accessed directly inside the transformations
Column required by the GetImage method in the transformations
Columns required by the GetDocumentUrl() transformation method

4.
5.
6.
7.

Disable Select only published (Content filter category).


Disable Check permissions (System settings category).
Check the Disable view state property (Performance category).
Configure caching for the web part:
Content caching (caches the data loaded by the web part)
Partial output caching (caches the web part's output code, the best option for static lists)
8. Click OK.
The web part now loads only the required data columns, skips unnecessary processing, and uses caching. This Repeater does not use
filtering or paging, so it is safe to disable view state.

Configuring caching
Cache is a storage space that duplicates previously requested data, and allows faster access to the data in the future. Correctly using
caching can significantly improve the performance of your website.
Caching the content of web pages provides two primary benefits:
Quicker loading of data (retrieving data from the cache avoids communication with slower storage spaces, such as the website's
SQL database and file system)
Reduction of unnecessary page processing on repeated requests
The built-in caching mechanisms of Kentico work primarily on the server side, and utilize the application's memory to store data. The system
saves data into the cache in the form of cache keys. Cache keys have unique names that exactly identify the cached content. Each key
stores the cached data itself (depending on the type of the cache), as well as other information such as the expiration time or dependencies.

Cache types
Kentico provides the following types of caching:
Output cache (full page) - caches the full HTML output of pages.
Partial output cache - caches the HTML output of individual page components (web parts).
File cache - stores files and resources, such as images, CSS stylesheets or JavaScript files. Supports both server and client-side
caching.

Content cache - stores structured data loaded by web parts and controls (for data sources, repeaters, etc.).
Page info cache - stores basic information about pages.
Custom code cache - allows developers to cache data used in custom code.
You can also configure IIS Output caching for your web application. IIS Output caching is completely separate from the caching
mechanisms in Kentico. When clients request a page whose valid output is cached on the IIS level, the server returns the response
without requiring any processing from the Kentico application.
The following diagram shows the order in which the cache types are checked when handling requests (from top to bottom). If the required
content is found in one of the cache layers, the system stops processing the request and sends the response without executing the page
code or accessing the database. The cache types shown at the top of the diagram provide the best performance the page response time
and processing costs increase as the request progresses through the cache layers.

Page info caching


When a visitor requests an uncached page, the system queries the database for basic information about the page, including the following:
alias path
ID and name
page metadata and other properties
SKU information (for products)
workflow information
The Page info cache stores the retrieved information in the application's memory, which allows quicker access on subsequent requests. The
system reuses the information multiple times during the processing of a single page, so page info caching is an important factor in the
website's performance. Page info caching cannot cause sites to display outdated information. The system automatically clears the cache for
pages that are modified.
You can change the expiration time of the page info cache:
1.
2.
3.
4.

Open the Settings application.


Expand the System -> Performance category.
Type a number of minutes into the Cache page info (minutes) setting. Do NOT set the value lower than 10 minutes.
Save the settings.

When a user requests a page, the basic information stays in the cache for the specified number of minutes, or until someone modifies the
related page.
Tip: You can view the cache keys that store page info through the cache debugging interface. The names of page info cache keys
begin with pageinfo or pageinfobyurl.

Clearing the cache

To delete all data from the application's cache:


1. Open the System application.
2. On the General tab, click Clear cache.
The system removes all cached content managed by Kentico.

Caching page output


Output caching is the most effective way to increase page performance. The output cache stores the full source code of pages, i.e. the HTML
and client script that the server sends to browsers for rendering. When a visitor views a page, the server caches the output code in the
application's memory. Until the cache expires, the system displays the page using the cached output. As a result, the application can quickly
serve requests without running the page code or communicating with SQL servers.
We recommend using output caching for all possible pages. The drawback is that cached output can become outdated on dynamic
pages, or if the website's content is updated. Output caching is not suitable for pages that need to refresh frequently (for example pages that
update based on user input, or have randomly generated content). You cannot disable output caching for parts of pages.
However, the system provides several solutions that allow you to cache output even for pages with dynamic content:
Set dependencies for the output cache (allows automatic clearing of the cache)
Adjust how the system caches multiple versions of pages
Use substitution macros to create dynamic content inside cached pages
Disable full page output caching, but use partial caching for sections of the page (individual web parts)
Caching page output on the IIS level
You can also configure IIS Output caching for your web application. IIS Output caching is completely separate from the caching
mechanisms in Kentico. When clients request a page whose valid output is cached on the IIS level, the server returns the response
without requiring any processing from Kentico.

Configuring full page output caching


To use output caching for your website's pages:
Allow output caching globally:
1.
2.
3.
4.

Open the Settings application.


Select the System -> Performance category.
Check Enable output caching.
Save the settings.

Enable output caching for individual pages:


1.
2.
3.
4.
5.

Open the Pages application.


Select the page in the content tree.
Open the Properties -> General tab.
Set the Use output cache property to Yes (in the Output cache section).
Specify the number of Cache minutes. The value must be greater than 0, and determines the expiration time of the page's output
cache.
6. Save the page.
To enable output caching for all pages on your site, edit the properties of the root page. The underlying pages need to have the Us
e output cache property set to Inherit (this is the default state).
When a visitor requests the page, the system saves the full output code into the cache. Until the cache expires, the system displays the
cached output without processing the page.

Setting output cache dependencies


The output cache of pages can become outdated when users update the website's pages and objects. Dependencies allow the system to
automatically delete cached content whenever related objects are modified. The output cache provides default dependencies that clear the
cache for pages:
When a user modifies the given page's content, properties or page template
Whenever a postback occurs on the page
By default, pages do NOT delete their output cache when you modify other pages or objects whose data is displayed on the page. For
example, if a page contains a list of news articles and you update one of the news pages, the page displays the old content until the output
cache expires.
To ensure that pages are always up-to-date, you need to set your own output cache dependencies:
1. Edit the page in the Pages application.
2. Switch to the Design tab.
3.

3. Add the Output cache dependencies web part anywhere on the page.
4. Define the dependencies in the web part's Cache dependencies property. For more information and examples, refer to Setting
cache dependencies.
5. Click OK.
The system clears the page's output cache whenever an object specified by the dependencies is modified. With the cache cleared, the
system fully processes the page on the next request, and caches the new output.
Note: If the page uses a shared page template, the dependencies apply to all pages with the given template.

Using persistent storage for the output cache


By default, the application stores the output cache of pages in the memory. Websites lose all cached content if the application restarts. You
can configure the system to save the output cache in the server's file system, which provides more persistent storage.
To allow storage of output cache in the file system:
1. Go to Settings -> System -> Performance.
2. Type a number of minutes into the Cache output in file system (minutes) setting. The value must be greater than 0, and
determines the expiration time of the output cache files.
3. Save the settings.
To enable persistent output caching for pages:
1.
2.
3.
4.

Open the Pages application.


Edit individual pages on the Properties -> General tab.
Set the Allow file system cache property to Yes (in the Output cache section).
Save the page.
To enable file system output caching for all pages on your site, edit the properties of the root page. The underlying pages need to
have the Allow file system cache property set to Inherit (this is the default state).

The output cache stores the content of the selected pages in both the application's memory and file system. When processing page requests,
the system checks both types of output cache.

Deleting the output cache of pages


To manually clear the output cache of a page:
1.
2.
3.
4.

Open the Pages application.


Select the page in the content tree.
Open the Properties -> General tab.
Click Clear output cache in the Output cache section.

The page's output is removed from the cache. The next time a visitor opens the page, the system runs the page's code and saves the output
into the cache again.

Caching portions of the page output


If you cannot use full output caching on a page, consider enabling Partial caching for sections of the page. The partial cache stores the
HTML output of individual web parts (components that make up the content of pages). Partial caching allows the system to refresh pages on
every request, but still improves performance by caching at least portions of the page output. You can set up partial caching for any number
of web parts on a single page.
Web parts do not use partial caching by default. You need to allow partial caching globally for your website, and then enable it for individual
web part instances.
To allow partial caching:
1.
2.
3.
4.

Open the Settings application.


Select the System -> Performance category.
Check the Enable partial caching setting.
Save the settings.

To enable partial caching for web part instances:


1.
2.
3.
4.

Open the Pages application.


Edit the page containing the web part on the Design tab.
Configure the web part instance (double-click).
Expand the Performance category, and type a number of minutes into the Partial cache minutes property. The value must be
greater than 0, and determines the expiration time of the web part's partial cache.
5. Click OK.
When a visitor opens the page, the system saves the HTML output generated by the web part into the cache. Until the cache expires, the
system renders the page without processing the web part, and displays the cached output instead.

Automatic clearing of partial cache


By default, the system deletes the partial cache of web part instances:
When you modify the property configuration of the given web part instance.
Whenever a postback occurs on the page containing the web part.
Editable web parts (Editable text, Editable image) automatically clear their partial cache when the content of the parent
page is updated.
You can set additional cache dependencies for web parts through the Partial cache dependencies property (in the Performance
category). The system uses the dependencies to automatically clear the partial cache when the related objects are modified.
To disable the default dependencies listed above, uncheck Use default cache dependencies and enable the Preserve partial
cache on postback property.

Tip: If you wish to use partial caching on pages that are not based on the portal engine, you can leverage standard ASP.NET
output caching for controls.

Caching multiple output versions of pages


Web pages often display different content based on variable parameters, such as user permissions, language preferences, or the device and
browser used to view the page. To compensate, the output cache stores multiple versions of pages. The system then automatically serves
the appropriate cache version to visitors.
The output cache always creates separate cache items for pages according to the following variables:
The page path (including the virtual directory and extension)
The protocol in the request URL
You can configure the conditions that determine when the system uses separate or shared output cache:
1.
2.
3.
4.

Open the Settings application.


Select the System -> Performance category.
Click Edit next to the Output cache variables setting.
Enable or disable the following output cache variables:
Cache key variable

Ensures separate output cache for

username

Every logged in user. Public users share the same output


cache.

sitename
_____________________

Every site in the system.


Important: Leave the sitename variable 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

Different cookie level preferences of visitors.

deviceprofile

Different device profiles detected for visitors.

domain

Website domain names. Check to disable output cache


sharing between domain aliases of sites.

viewmode

The page view modes used by Kentico, such as design, edit, p


review or live site. Currently, the system only uses caching for
the live site view mode.

5. Click Save.
The system adds the selected variables and their values into the names of output cache keys. As a result, the cache keys are unique for all
combinations of the required conditions.
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 you disable the username option, 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).
Tip: You can configure how the system shares partial output cache through the Partial cache variables setting. The variables
apply globally to the partial cache of all web parts.

Using output cache substitutions


Output caching is a powerful tool for improving page performance. However, some pages have sections of content that need to be dynamic.
Substitution macros allow you to add variables onto pages, which the system dynamically resolves even when loading the content from the
output cache. By using substitutions, you can cache the output of pages, but still keep pieces of content that update according to the current
time or other context information.
By default, the system does not provide any substitution macros. Developers need to define the substitutions according to the requirements
of your website.
To insert output cache substitutions into page content, write expressions in format: {~SubstitutionName~}
Note: Substitution macros work even on pages that do not use output caching.

Tip: You do not need to create substitution macros for all types of dynamic content. By default, the output cache stores multiple
versions of pages based on variables such as the user name, language and browser type. The system serves the appropriate
cache version to visitors according to these variables.
See the Caching multiple output versions of pages section for more information.

Defining substitution macros


The system resolves substitution macros by calling the methods registered as handlers for the ResponseOutputFilter.OnResolveSubstitut
ion event. To define substitutions, implement a handler method that converts individual substitution expressions into the appropriate results.
You need to register the event handlers at the beginning of the application's life cycle. Choose one of the following options:
During the initialization process of the application itself use the CMSModuleLoader partial class in the App_Code folder.
When initializing custom modules override the OnInit method of the module class.
Example

The following example demonstrates how to create a substitution macro that displays the current time:
1. Open your project in Visual Studio.
2. Create a class in the App_Code folder (or CMSApp_AppCode -> Old_App_Code on web application projects).
3. Edit the class and add the following references:

using CMS.Base;
using CMS.OutputFilter;

4.
5.
6.
7.

Extend the CMSModuleLoader partial class.


Create a new class inside CMSModuleLoader that inherits from CMSLoaderAttribute.
Add the attribute defined by the internal class before the definition of the CMSModuleLoader partial class.
Override the Init method inside the attribute class and assign a handler method to the ResponseOutputFilter.OnResolveSubstitut
ion event.

[SubstitutionLoader]
public partial class CMSModuleLoader
{
/// <summary>
/// Attribute class that registers substitution handlers.
/// </summary>
private class SubstitutionLoader : CMSLoaderAttribute
{
/// <summary>
/// Called automatically when the application starts.
/// </summary>
public override void Init()
{
// Assigns a handler method to the event that the system triggers when
resolving substitution macros
ResponseOutputFilter.OnResolveSubstitution +=
ResolveCustomOutputSubstitutions;
}
/// <summary>
/// Resolves output substitutions.
/// </summary>
/// <param name="sender">Sender object</param>
/// <param name="e">Event argument object representing the substitution
expression that is being resolved</param>
private void ResolveCustomOutputSubstitutions(object sender,
SubstitutionEventArgs e)
{
// Checks that the substitution expression is not resolved yet
if (!e.Match)
{
// Branches according to the expression text of the substitution macro
// You can define any number of substitution macros by adding further
cases
switch (e.Expression.ToLower())
{
// Handles the {~TimeStamp~} substitution macro
case "timestamp":
// Flags the substitution expression as resolved
e.Match = true;
// Returns the current time as the result of the substitution
e.Result = DateTime.Now.ToString();
break;
}
}
}
}
}

8. Save the class file. Build the solution on web application installations.
The system now recognizes the {~TimeStamp~} expression, and resolves it into the current time. You can place the expression directly into
the text content of pages, or anywhere within the output code.
Output substitutions vs. Macro expressions
The functionality of output substitutions is similar to Kentico macro expressions. The main difference is that the system resolves
substitutions even when loading pages from the output cache.

For example, the {% DateTime.Now %} macro also displays the current time. If you place both the macro and the sample {~TimeSt
amp~} substitution onto a page that uses output caching, you get the following results:
Macro - displays the time when the page was loaded for the first time and saved into the output cache.
Substitution - updates the time whenever the visitor refreshes the page, even if the system loads the content from the
output cache.

Caching files and resources


Files represent a significant part of the data that browsers load when rendering web pages. Common examples of files are images, and web
resources such as CSS stylesheets or JavaScript code files. The system provides two types of file caching mechanisms:
Client-side
Server-side
File caching works for the CSS stylesheet objects used in Kentico, even if they are not stored as physical files.

Client-side file caching


Client-side caching duplicates the data of previously requested files directly within browser applications. Client cache is the most efficient
type of caching, because it allows browsers to access files without communicating with the web server. The system controls caching in client
browsers (and intermediate network caches) by modifying the HTTP headers of file request responses.
To configure client-side file caching:
1. Open the Settings application.
2. Select the System -> Performance category.
3. Edit the settings in the Client-side file caching category. You can set up the following client caching scenarios:
Client caching settings
Client cache (minutes) > 0
______________________________________

Result
Enables client caching for files, and sets the expiration time to
the specified number of minutes. Browsers save files retrieved
from the server into their client cache. Until the cached files
expire, browsers load the file data from the cache without
sending any requests to the server.
This configuration provides the best file performance, but may
cause browsers to display outdated content (if cached files are
modified before the expiration interval ends).

Client cache (minutes) = 0


Allow client cache revalidation enabled

Enables client caching for files. Cached files are always


flagged as expired, so browsers revalidate files on each
request:
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, and the file stays in the client cache.
The client and server only exchange HTTP header
information, which is much faster than fully reloading files.
This configuration is recommended, since it significantly
improves file performance while ensuring that the cached files
are always up-to-date.

Client cache (minutes) = 0

Completely disables client caching of files (not recommended).

Allow client cache revalidation disabled

4. Save the settings.


The system allows browsers to cache files according to the settings.

Server-side file caching


When a client requests an image or other file, Kentico stores the file's data in the application memory.
For files stored in the database, the cache holds the entire file, including binary data.
For files stored in the file system, the cache stores only the main file records. Binary data is streamed directly from the file system.
The system can then serve subsequent requests for the file without needing to access the database or file system.

Note: The system always caches files for at least one minute to prevent the application from overloading in case of DoS attacks.
The cache automatically removes files if they are modified and cannot cause the website to display outdated content.
To change how long the server-side cache retains files:
1.
2.
3.
4.

Open the Settings application.


Select the System -> Performance category.
Type a number of minutes into the Cache files (minutes) setting.
Save the settings.

Files stay in the cache for the specified number of minutes.


If your website stores large files in the database, you can limit the maximum size of files allowed in the cache. Setting a limit stops
the file cache from using an excessive amount of memory. Type the allowed number of kilobytes into the Maximum file size to
cache setting.

Caching the data of page components


Many pages contain components (web parts or controls) that load and display data from the Kentico database, or other external sources. For
example, when displaying a page with a list of news articles, the system retrieves text from the fields of news pages stored in the database,
and then formats the data on the page.
Communication with storage spaces and processing of data are common weak points in the performance of pages. Content caching helps
the system maximize the efficiency of data. The content cache saves data loaded by page components into the application's memory.
Components then re-use the cached data on future requests.
The following types of web parts and controls support content caching:
Dedicated data sources
Repeaters and viewers with built-in data sources
Navigation components

Configuring content caching


You can set up content caching on two levels:
Globally for entire sites (all data components on the given site)
For individual instances of web parts or controls
We recommend caching all possible content. You can ensure that components do not display outdated content by setting cach
e dependencies. Most non-custom data sources have default dependencies that automatically clear the content cache whenever
the stored data is modified.
To enable content caching globally:
1. Open the Settings application.
2. Select the System -> Performance category.
3. Type a number of minutes into the Cache content (minutes) setting. The value determines how long the content cache retains
data, and must be greater than 0.
4. Save the settings.
With content caching enabled globally, the system caches the structured data of all page components by default.
To enable content caching for individual web part instances:
1.
2.
3.
4.

Open the Pages application.


Edit the page containing the web part on the Design tab.
Configure the web part instance (double-click).
Type a number of minutes into the Cache minutes property (in the System settings category). The value determines how long the
cache stores the web part's data, and must be greater than 0.
5. (Optional) Add dependencies via the Cache dependencies property.
6. Click OK to save the web part's properties.
The system caches the data loaded by the given web part instance.
To disable content caching for specific web parts when content caching is enabled globally:
1. Configure the web part instance on the Design tab.
2. Type 0 (zero) into the Cache minutes property.
3. Click OK to save the web part's properties.
The web part instance reloads data from the data source without caching.

Setting dependencies for content cache


Cache dependencies allow the system to automatically clear cached data when related objects are modified. Web parts with data sources

provide default dependencies for the content cache, and you can also add your own custom dependencies for individual instances:
1.
2.
3.
4.

Open the Pages application.


Edit the page containing the web part on the Design tab.
Configure the web part instance (double-click).
Add the dependencies into the Cache dependencies property (in the System settings category). For more information and
examples, see Setting cache dependencies.
If you leave the Use default cache dependencies box checked, the system automatically clears the web part's content
cache:
Whenever the loaded data changes (depends on the web part)
When you modify the property configuration of the given web part instance
Default dependencies do NOT cover data loaded via external or custom data sources. For example, custom query data
sources only clear the content cache when the query itself changes, not the loaded data.

5. Click OK.
The system deletes the web part's content cache whenever the specified objects change. With the cache cleared, the web part reloads the
data from the source the next time a visitor opens the page.

Sharing the content cache between components


The content cache stores the data loaded by page components (web parts or controls) under cache keys. By default, the system generates a
unique cache key name for each component. The default name contains variables such as the web part ID, the name of the user viewing the
page, or the code name of the language selected for the page.
If you have multiple web part instances that load exactly the same data, you can share the cached content:
1.
2.
3.
4.

Open the Pages application.


Configure one of the web parts on the Design tab.
Enter a custom key name into the Cache item name property (in the System settings category).
Copy the key name into the Cache item name property of all web part instances that load the same data.

When a visitor opens a page containing one of the web parts, the system loads the data and saves it into the cache under the specified key.
While the cached content is valid, other web parts to which you assigned the same Cache item name retrieve the data directly from the
cache. This setup optimizes loading of content from the database (or other source) and avoids redundant keys in the cache.
Tip: You can use macro expressions to create dynamic cache item names based on variables such as query string parameters, or
other context data.

Caching the page output of web parts


In addition to content caching, web parts also support Partial output caching. The partial cache stores the full HTML output code of web part
instances.
See Caching portions of the page output for more information.
Partial caching has the following advantages and disadvantages when compared with content caching:
Better efficiency the partial cache allows the system to directly send the web part's HTML output to the browser,
without loading data or processing the web part at all
Usable by all web parts with visible output, not just web parts that load structured data
Not suitable for web parts whose output changes very frequently (for example lists with filtering)
No default dependencies on the data loaded by web parts you need to set custom partial cache dependencies to
ensure that the content of web parts is up-to-date
Note: Set up partial caching for the web part that actually renders the content on the page (this may not always be the same web
part as the data source).

Setting cache dependencies


Cache dependencies allow the application to automatically clear cached data when related objects are modified.
The system uses dummy cache keys to create dependencies between cached data and other objects. Dummy keys are cache items
without any data that represent objects or groups of objects. When an object is modified, the system "touches" the corresponding dummy
keys, which causes the cache to delete all items that depend on the given dummy keys.
Sample scenario

A page with the /Products alias path contains a Repeater web part with content caching enabled. The repeater displays a list of
products (pages) placed under the Products page. When a visitor requests the Products page, the repeater loads the list of
products from the database, and stores the data in the content cache. The cached data has a dependency on the node|corporate
site|/products|childnodes dummy key, which the system automatically creates. If a child page of the Products page is modified,
the dummy key is touched, and the cache deletes the dependent data.
The following table shows which dummy cache keys are touched when objects are modified:
Object type

Touched dummy keys

Sample dummy key values

Pages
(content tree nodes)

node|<site name>|<alias path>|<culture>


node|<site name>|<alias path>
nodeid|<node id>
nodeid|<linked node id>
nodeguid|<node guid>
nodes|<site name>|<page type code
name>|all
documentid|<document id>

node|corporatesite|/home|en-us
node|corporatesite|/home
nodeid|12
nodeid|34
nodeguid|a58ed488-5545-48d0- ...
nodes|corporatesite|cms.menuitem|all
documentid|39
node|sitename|/|childnodes

+ for all ancestors of the modified page:


node|<site name>|<alias path>|childnodes
Objects
(not pages)

<object type name>|all


<object type name>|byid|<id>
<object type name>|byname|<code name>
<object type name>|byguid|<guid>

cms.user|all
cms.user|byid|53
cms.user|byname|administrator
cms.user|byguid|1ced44f3-f2fc- ...

Metafiles

metafile|<guid>

metafile|1ced44f3-f2fc- ...

Page attachments

cms.attachment|all
documentid|<attachment document id>
documentid|<attachment document
id>|attachments
attachment|<guid>

cms.attachment|all
documentid|32
documentid|32|attachments
attachment|1ced44f3-f2fc- ...

Forum attachments

forumattachment|<guid>

forumattachment|1ced44f3-f2fc- ...

Avatars

avatarfile|<guid>

avatarfile|1ced44f3-f2fc- ...

Media files

mediafile|<guid>
mediafile|preview|<guid>

mediafile|1ced44f3-f2fc- ...
mediafile|preview|1ced44f3-f2fc- ...

Page templates

template|<id>

template|12

Custom table data records

customtableitem|<custom table code


name>|all
customtableitem|<custom table code
name>|byid|<id>

customtableitem.customtable.sampletable|
all
customtableitem.customtable.sampletable|
byid|2

Adding custom cache dependencies


You can set custom cache dependencies for the following types of cache:
Full output cache of pages (add the Output cache dependencies web part onto the page)
Partial output cache of web parts or controls (Partial cache dependencies property)
Content cache of web parts or controls (Cache dependencies property)
Cached data in custom code
Create the dependencies by typing the names of dummy cache keys into the appropriate Cache dependencies property. Each dummy key
must be on a separate line when entering dependencies in the web part properties dialog. The system automatically clears the related cache
when the specified dummy keys are touched (i.e. when the corresponding objects are modified).

Examples
Scenario: You have a web part displaying information about users. You need to clear the web part's partial output cache whenever one
of the user's data is modified.
Solution: Add the cms.user|all dummy key into the web part's Partial cache dependencies property. The system touches this dummy
key whenever the data of a user in the system changes.

Scenario: You have a web part displaying information about one specific user the administrator (UserID is 53, UserGuid is 849711D0
-739D-412E-92B6-FE40EDCADC4A). You need to clear the web part's partial output cache when the administrator's user account data
is modified.

Solution: Add any of the following dummy keys into the web part's Partial cache dependencies property:
cms.user|byid|53
cms.user|byname|administrator
cms.user|byguid|849711D0-739D-412E-92B6-FE40EDCADC4A

Scenario: You have a web part displaying a list of news articles. The web part loads the data from all CMS.News pages on the website.
The site's code name is NewsSite. You need to clear the web part's partial output cache when any of the news pages is updated.
Solution: Add the nodes|newssite|cms.news|all dummy key into the web part's Partial cache dependencies property.

Debugging cache
If you encounter unexpected caching behavior or any problems related to the cache, you can use the system's debugging functionality to:
Check the exact content of the application's cache
Monitor caching operations for web requests
You can access the system's debugging interface through the Debug application.

Viewing the stored cache items


On the Cache items tab, you can see which Data items and Dummy keys (cache dependencies) are currently stored in the system's
server-side cache.

You can delete individual cache keys by clicking Delete (


r cache.
Clicking View (

) next to the corresponding items. To remove all items from the cache, click Clea

) next to a cache key opens a new window showing detailed information about the cached object:

Key - the key under which the object is stored in the cache.
Expiration - date and time when the cache item will expire (i.e. will be removed from the cache).
Priority - Kentico uses two priorities for cache items: High and NotRemovable (will not be deleted from the cache as the server frees
system memory).
Dependencies - list of dummy keys on which the cache item depends. The system removes the cache item if any of the dummy
keys are touched (modified).
Object type - the type of the cached item.
Fields - the fields storing the actual data of the cached item (depend on the item's object type).

If you need even more information about a cached object, click Debug ( ) next to the item in the list of cache keys. Debugging cache keys
allows you to browse the full system data of the given object, including all properties, variables and related objects.
Note: The list of cache items does not display the partial output cache stored for page components.

Debugging cache access


The cache access debug allows you to view the cache operations that the system performs for individual web requests (adding items to the
cache, loading data from the cache).

Enabling the cache access debug


To use cache access debugging, you need to adjust the settings in Settings -> System -> Debug:
Setting

Description

Enable cache access debug

Enables cache access debugging and the Cache access tab in the
Debug application.

Display cache access debug on live site

If enabled, cache access debug information is also displayed at the


bottom of each page on the live site. Requires cache access
debugging to be enabled.

Debug cache access of UI pages

If enabled, the cache access debug also covers requests for pages
of the administration interface. Requires cache access debugging
to be enabled.

Cache access debug log length

Sets the maximum length of the cache access debug log on the Ca
che access tab of the debugging interface, i.e. the number of
requests for which debug information is preserved and displayed.
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


cache access 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 logcache.log file.

Log cache access to file

If enabled, the system saves the cache access debug log into the l
ogcache.log file in the ~\App_Data folder. This option does not
require cache access debugging to be enabled.

Tip: You can also enable cache access debugging through the "debug everything" settings in the All section of the Debug settings
category.

Monitoring cache access


To view which cache operations the system performed for recent web requests:
1. Open the Debug application.
2. Select the Cache access tab.
You can see the URLs of web requests and the time when the system processed the requests. The table below each request contains the
cache items that the system accessed during the request. The table provides the following information for each cache item:
The type of Access (Get, Add)
The name of the accessed Cache key
The cache item's dependencies
The object type and size of the cached Data
The Context in which the cache item was accessed (API method)
Click on the method to see the stack trace of the cache access
If you enable the Show complete context option at the top of the interface, the stack trace is displayed for all cache items.
Click Clear debug log to remove all records in the cache access debug. To remove the actual data from the system's cache, click Clear
cache.

Clicking View (

) next to a cache key opens a new window showing detailed information about the cached object:

Key - the key under which the object is stored in the cache
Expiration - date and time when the cache item will expire (i.e. will be removed from the cache)
Priority - Kentico uses two priorities for cache items: High and NotRemovable (will not be deleted from the cache as the server frees
system memory)
Dependencies - list of dummy keys on which the cache item depends. The system removes the cache item if any of the dummy
keys are touched (modified).
Object type - the type of the cached item
Fields - the fields storing the actual cached data (different for each object type)

Reference - Cache settings


Global settings
You can configure the following cache settings through the Settings application, in the System -> Performance category:
Server content caching
Cache page info (minutes)

Sets the number of minutes for which the system caches page
information. This option caches 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, so the website will not
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.
See also: Caching the data of page components

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.
See also: Caching files and resources

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 checked, file requests are redirected to the corresponding


physical file (if the requested file is stored in the file system).

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.
See also: Caching files and resources

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.
See also: Caching page output

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 checks both types of 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.

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 d
esign, edit, 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 and you need to
enable it for individual instances using their Partial cache minutes
property.
See also: Caching portions of the page output

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
design, edit, preview or live site. Currently, the system only
uses caching for the live site view mode.

Page settings
You can configure the following output cache settings for individual pages in the Pages application on the Properties -> General tab:
Output cache
Use output cache
_______________________________

Indicates if the system caches the full HTML output of the page.
Output caching can greatly improve the performance of the page,
but is not suitable for pages with dynamic content.
You can inherit the output cache settings from the parent page.
Important: Output caching must also be allowed in the website's
settings. Administrators can enable output caching in Settings ->
System -> Performance.
See also: Caching page output

Cache minutes

Determines how long the system keeps the output code of the
page in the cache (if output caching is enabled).
By default, the system automatically clears the output cache of the
page if you update the page's content, properties or page template.
You can manually remove the page from the output cache by
clicking Clear output cache.

Allow file system cache

Indicates if the system stores the page's output cache on the


server's file system. This provides persistent caching in case of
application restarts.
If disabled, the application only caches the page output in its
memory. If enabled, the system checks both types of cache.
You can inherit the setting from the parent page.
The file system cache is stored for the number of minutes specified
in the Cache output in file system (minutes) setting in Settings
-> System -> Performance.

Web part settings


Instances of web parts provide the following properties for configuring content caching and partial output caching:
System settings

Cache item name


_______________________________

Sets the name of the cache key used for the content of the web
part. If not specified, this name is generated automatically based
on the site, page path, Web part control ID and current user.
Cache keys can be shared between multiple web parts displaying
the same content on different pages in order to avoid keeping
redundant data in the memory.
See also: Caching the data of page components

Cache minutes

Sets the number of minutes for which the content of the web part
remains cached before the latest version is reloaded from the
database.
If empty, the web part uses the value entered into the Settings ->
System -> Performance -> Server content caching -> Cache
content (minutes) setting.
If set to 0, the web part does not use content caching.

Cache dependencies

Allows you to specify a list of cache keys on which the content


cache of the web part depends. When the specified cache items
change, the system deletes the content cache of the web part. Add
one cache key per line.
If you check Use default cache dependencies, the web part uses
dependencies that include all possible object changes that could
affect the content of the given web part.
See also: Setting cache dependencies

Performance
Partial cache (minutes)

Sets the number of minutes for which system caches the output
HTML code of the web part. Partial caching is similar to to full-page
caching, but only for the code of the web part specifically.
If left empty or set to 0, partial caching is not used for the web part.
Important: Partial caching must also be allowed in the website's
settings. Administrators can enable partial caching in Settings ->
System -> Performance.
See also: Caching portions of the page output

Partial cache dependencies

Allows you to specify a list of cache keys on which the partial


cache of the web part depends. When the specified cache items
change, the system clears the partial cache of the web part. Add
one cache key per line.
If you check Use default cache dependencies, the web part uses
dependencies that include all possible object changes that could
affect the given web part.

Preserve partial cache on postback

By default, the system clears the partial cache of web parts


whenever a postback occurs on the page. If you enable this
property, the partial cache of the given web part instance persists
through postbacks.

Using code minification and compression


An important factor that influences the performance of a website is the size of code resources, which are requested by client browsers when
rendering pages. The most significant among these are CSS stylesheets and JavaScript source files, which can in some cases reach sizes
that considerably impact page load time.
Kentico provides two types of builtin functionality that help optimize the performance of requests for CSS and JavaScript resources:
Code minification

Removes all unnecessary characters from the code that are not
required by the browser to correctly process the resource. This
includes white spaces, line break characters, comments,
bookmarks etc.
Minified resources behave in exactly the same way as the original.
Browsers can immediately handle minified resources without any
additional steps.
Note: Minified code is difficult to read (for humans) and is therefore
unsuitable for debugging.

Resource compression

Reduces the size of resources by encoding their data. To apply


compression, you must also enable minification for resources of
the given type.
When a client browser receives a compressed resource, it must
first decompress the data. All browsers officially supported by
Kentico should be able to correctly decompress files. In cases
where the client cannot process compressed data, the system
automatically sends the unmodified resource instead.

You can enable or disable code minification and compression globally for all sites in Settings -> System -> Performance, through the
settings in the Resources category.
Reducing the size of requested resources saves bandwidth and improves the response time of your website. Minification can decrease the
size of a resource by approximately 2040%, depending on the code of the given object. If compression is also used, resources can be
reduced to roughly 30% of their original size.
Note: The reductions only apply to resources stored individually in the file system or database. Inline code inserted into the HTML
markup of pages is not affected.
The minification and compression process slightly increases the server CPU load and adds a short delay to resource requests. To counter
this issue, the system uses server-side caching for resource files:
Minification/compression only occurs once when a resource is requested for the first time (the cache stores the result).
On subsequent client requests, the system provides the transformed version of the resource from the cache.
The cache stores both compressed and uncompressed versions of resources, so the data is readily available even for clients without
compression support.
The duration of the server-side caching is always at least one minute. You can change the number of minutes through the Cache
files (minutes) setting in Settings -> System -> Performance.
Additionally, you can use clientside browser caching for resources (enabled by default):
With client caching, browsers only reload resources from the server if the cached data expires or the content of the resource
becomes outdated.
Set the expiration time of the client cache through the Client cache (minutes) setting in Settings -> System -> Performance. Enter
0 to completely disable the client caching.
See also: Caching files and resources

Requesting minified resources


Compression and minification is automatically ensured by the ~/CMSPages/GetResource.ashx handler, which manages resource requests
according to the specified settings. If minification is enabled, CSS and JavaScript requests generated by the system use this handler.
You can manually load resources in your code by using the following URL parameters with the handler:
stylesheetname - used to request a CSS stylesheet from the database. The code name of the requested stylesheet must be
entered as the value of the parameter.
Link example:
<link href="/Kentico/CMSPages/GetResource.ashx?stylesheetname=CorporateSite" type="text/css" rel="stylesheet">
_transformations, _layouts, _templates, _devicelayouts, _webparts, _webpartlayouts, _containers - used to request the
internal stylesheets of the corresponding type of page component. The object ID values of the given components must be entered as
the value of the parameter, separated by semicolons (if multiple component stylesheets are requested). See Adding CSS
stylesheets to page components.
Link examples:
<link href="/Kentico/CMSPages/GetResource.ashx?_containers=1;14" type="text/css" rel="stylesheet"/>
<link href="/Kentico/CMSPages/GetResource.ashx?_transformations=3511" type="text/css" rel="stylesheet">
stylesheetfile - used to request static CSS resources from the file system. The relative path of the requested .css file must be
entered into the parameter.
Lnk example:
<link href="/Kentico/CMSPages/GetResource.ashx?stylesheetfile=/Kentico/App_Themes/Design/OnSiteEdit.css" type="text/css"
rel="stylesheet">
scriptfile - used to request static JavaScript resources from the file system. The relative path of the requested .js file must be
entered into the parameter.
Link example:
<script src="/Kentico/CMSPages/GetResource.ashx?scriptfile=%7e%2fCMSScripts%2fmootools.js" type="text/javascript"></script>
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 a web farm environment


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

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.

Web farm synchronization mechanisms


When you make changes to content on a server, the system logs the changes into the database as web farm tasks. The server then notifies
other servers in the web farm, which retrieve the web farm task data from the database and make appropriate changes in their file system or
memory.
The system provides two ways to notify servers about changes in the web farm.

URL notifications
Every Kentico instance contains a page that web farm servers can send 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.
This is the default behavior in instances not running on Microsoft Azure.

Database notifications
With database notifications, a column in the CMS_WebFarmServer database table is used. The column contains a time stamp, which
indicates the time of the last change made on a server. On the application side, a routine runs in a separate thread which continuously polls
the database to find out whether a time stamp changed.
To enable this mechanism, add the following key to your web.config file. You don't need this key if your application runs on Microsoft Azure,
as this mechanism is used on Azure by default.

<add key="CMSWebFarmUseDBUpdater" value="true" />

Defining web farm servers


To use web farm synchronization, you need to enter the internal URLs of all your servers into the system. Perform at least the following
steps:
1. Add web farm servers.
2. Enable web farm functionality.
3. Add license keys for your web farm servers.

Adding web farm servers


To add a server to the web farm:
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.

3.

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.
Server enabled - allows you to manually enable or disable web farm synchronization for the server.
4. Click Save to register the server.
Repeat the process for every server in your web farm.

You also need to update the web.config file on each server and add the CMSWebFarmServerName key into the appSettings section:

<add key="CMSWebFarmServerName" value="servername"/>

Where servername is the 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.

Enabling web farm functionality


After you define your web farm servers, you need to enable web farm synchronization in the settings:
1.
2.
3.
4.

Open the Settings application.


Expand the Versioning & Synchronization -> Web farm category.
Check the Enable web farm setting.
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.

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

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

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:

<add key="CMSHashStringSalt" value="e68b9ad6-a461-4707-8e3e-ece73f03dd02" />

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.

Setting the server synchronization interval


By default, web farm servers are updated with changes made on other servers once per request. Synchronizing this frequently may be
impractical for hightraffic websites. To change the synchronization interval, set the value of the CMSWebFarmUpdateWithinRequest web.c
onfig key to false:

<add key="CMSWebFarmUpdateWithinRequest" value="false"/>

and use the Synchronize web farm changes scheduled task instead, which has a configurable execution interval:
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 an appropriate task interval.
5.

5. Select the Task enabled check box.


6. Click Save.
You also need to create the task for each server in the web farm. To create the tasks quickly:
Note: All web farm servers that you wish to use need to be registered in the system before performing the following steps.
1.
2.
3.
4.
5.

Return to the list of scheduled tasks.


Click New task.
Fill in the same properties as those of the Synchronize web farm changes task (the Task name must be different)
Check Create tasks for all web farm servers below the Server name property.
Click Save.

Your web farm now synchronizes according to the interval of the scheduled tasks.

Monitoring web farm synchronization tasks


If synchronization doesn't work as expected, you can check the Tasks tab of the Web farm application's interface. The tab provides
information about all synchronization tasks that are currently active (waiting to be processed).
Click Run tasks to manually execute tasks, regardless of how the synchronization interval is currently configured.
You can remove all listed tasks by clicking Clear task list, or individual tasks via the Delete ( ) action. Clearing the list is not necessary if
the web farm is working correctly the system automatically removes successfully processed tasks.
A similar user interface can be found on the Anonymous tasks tab. This 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

Creating web farm servers automatically


An alternative way of defining web farm servers is letting the system create the servers automatically on application start.
Prerequisite: You need to have web farm synchronization enabled on all the servers.
1.
2.
3.
4.

Open the Settings application.


Select the Versioning & Synchronization -> Web farm category.
Enable the Generate servers dynamically setting.
Click Save.

Alternatively, you can add the following key to the appSettings section of your web.config file:

<add key="CMSWebFarmGenerateServers" value="true"/>

All servers with enabled web farm support add themselves into the list of servers when the application starts. If a server doesn't have a
server name defined in the web.config, it uses its machine name.

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

3.
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/<Index code name> folder within your web project directory.
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.
2.
3.
4.

A user creates a new page.


Upon the page's creation, the system logs a new indexing task in the database.
The Smart search either runs the indexing task immediately or processes it later using a scheduled task.
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.
2.
3.
4.

Open the Settings application.


Select the System -> Search category.
Check Enable smart search indexing.
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:

<add key="CMSProcessSearchTasksByScheduler" value="true" />

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.

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
Display name

Description
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
User
______________

Description
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):
Index the following page data:

Pages

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.
3.
4.
5.
6.

Edit ( ) the index.


Select the Indexed content tab.
Click Add allowed content or Add excluded content.
Open the Sites tab and assign the websites where you wish to use the index.
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: /%
Page types: empty

Indexes all pages on the site.

Path: /Partners
Page types: empty

Only indexes the /Partners page, without the child pages placed
under it.

Path: empty
Page types: CMS.News

Indexes all pages of the CMS.News page type on the entire site.

Path: /Products/%
Page types: CMS.Smartphone;CMS.Laptop

Indexes all pages of the CMS.Smartphone and CMS.Laptop page


types found under the /Products section.

In this case, an empty path field value is equal the /% expression.

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
Page types: empty

Excludes the /Partners page from the index. Child pages are not
excluded.

Path: empty
Page types: CMS.News

Excludes all pages of the CMS.News page type from the index.

Path: /Products/%
Page types: CMS.Smartphone;CMS.Laptop

Excludes all pages of the CMS.Smartphone and CMS.Laptop page


types found under the /Products section from the index.

In this case, an empty path field value is equal the /% expression.

Excluding individual pages from all indexes


You can also exclude specific pages from all smart search indexing:
1.
2.
3.
4.
5.

Open the Pages application.


Select the given page in the content tree.
In Edit mode, open the Properties -> Navigation tab.
Enable the Exclude from search property.
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:
<field code name>:<searched phrase>
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 <field code name>:<searched
phrase> search expressions.
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.
3.
4.
5.
6.

Edit ( ) the E-commerce module.


Open the Classes tab.
Edit the SKU class.
Select the Search tab.
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:

<add key="CMSCrawlerAllowSiteAliasRedirect" value="false" />

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
{
/// <summary>
/// Attribute class for assigning event handlers.
/// </summary>
private class DocumentCrawlerContentLoaderAttribute : CMSLoaderAttribute
{
/// <summary>
/// Called automatically when the application starts.
/// </summary>
public override void Init()
{
// Assigns a handler for the OnHtmlToPlainText event
SearchCrawler.OnHtmlToPlainText += new
SearchCrawler.HtmlToPlainTextHandler(SearchHelper_OnHtmlToPlainText);
}
// 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 (
Delete (

) the way listed custom tables are indexed or

) 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:
<field code name>:<searched phrase>
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.
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.

Tokenized

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 <field code name>:<searched
phrase> search expressions.
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.
3.
4.
5.

Edit ( ) the form that you want to configure.


Open the Search fields tab.
Make sure that the Search is enabled box is checked.
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:
<field code name>:<searched phrase>
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 <field code
name>:<searched phrase> search expressions.
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.
3.
4.
5.
6.

Edit ( ) the Membership module.


Open the Classes tab.
Edit the User class.
Select the Search tab.
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:
<field code name>:<searched phrase>
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 <field code name>:<searched
phrase> search expressions.
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:
<field code name>:<searched phrase>
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 <field code name>:<searched
phrase> search expressions.
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:

<add key="CMSProcessSearchTasksByScheduler" value="true" />

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
Indexes

Description
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 <fieldname> does not appear to be
indexed" error when using multiple indexes, try specifying the type
of the field, for example: (date)documentcreatedwhen

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.
2.
3.
4.
5.

Open the Pages application.


Edit the page containing your Smart search box on the Design tab.
Configure the Smart search box web part (double-click).
Check the Enable predictive search property.
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 <a> 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.
2.
3.
4.
5.
6.
7.

Open the Pages application for the sample Corporate site.


Select the website root page in the content tree (Corporate Site).
Open the Design tab and double-click the Smart search box web part.
Check the Enable predictive search property.
Select one or more Indexes (in the Predictive settings category).
Uncheck Group results by index (in the Predictive results category).
Click New next to the Search result transformation property (in the Predictive results category). Create the following ASCX
transformation:

7.

<div class="customPredictiveResultItem">
<a href='<%# SearchResultUrl() %>'>
<%# HTMLHelper.HTMLEncode(DataHelper.GetNotEmpty(Eval("Title"), "/")) %>
</a>
<span style="font-size: 7pt">
<%#
CMS.Search.SearchIndexInfoProvider.GetSearchIndexInfo(Eval<string>("index")).I
ndexDisplayName %>
</span>
</div>

8. Click Save and close the dialog.


9. Save & Close.
Modifying the Smart search box CSS styles

1.
2.
3.
4.

Open the Web parts application.


Select the Smart search box web part in the tree (Full-text search -> Smart search).
Open the CSS tab.
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:

<add key="CMSSearchSynonymsWeight" value="0.8" />

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.
3.
4.
5.

Edit ( ) the index.


On the General tab, select the Analyzer type.
Click Save.
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
Subset

Description
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:

<add key="CMSSubsetAnalyzerWordRegex" value="(\w|@|\.|\$)+" />

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 Field type set to File or Page 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 applicaton.
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.
2.
3.
4.
5.

Open the Smart search application.


Create or edit a Page search index.
When defining the search content on the Indexed content tab, check Include attachment content for the index's allowed content.
Click Save.
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:

<add key="CMSSearchMaxAttachmentSize" value="10000" />

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:

<add key="CMSSearchIndexXmlComments" value="true" />


<add key="CMSSearchIndexXmlAttributes" value="true" />

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:

<add key="CMSSearchDetectTextEncoding" value="true" />

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.

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

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 Field type set to File or Page 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.
2.
3.
4.

Open the Page types application.


Edit the Root page type.
Select the Queries tab.
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
Search dialog web part ID

Description
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: <index field
name>,<value of the field>,<displayed text>
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: <field name>:yyyymmddhhmm.


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:

<i class="<%# Eval("imageClass")


%>"></i>

In the code of ASCX transformations, you can get the values from the dataset by using the Eval("<field name>") function: Eval("score"), Eva
l("title"), etc.
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.
2.
3.
4.
5.

Open the Pages application.


Select the page in the content tree.
Open the Properties -> Navigation tab.
Check Exclude from search.
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.
2.
3.
4.

Open the Settings application.


Select the System category.
Adjust the settings in the Scheduler section.
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.
2.
3.
4.

Open the Settings application.


Select the System category.
Type a number of seconds into the Application scheduler interval setting.
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:

<add key="CMSUseAutomaticScheduler" value="true" />

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.
2.
3.
4.

Open the Settings application.


Select the System category.
Enable the Use external service setting.
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.
2.
3.
4.

Open the Settings application.


Select the System category.
Type a number of seconds into the Service scheduler interval setting.
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.

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 (<CMSApplicationName web.config key value>) service in the list.
6. Click the Start Service button on the top toolbar.

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
Start time
Every
Between
Days

Set the time interval between the execution of the task. The interval
settings do not ensure that the system executes the task at the
exact time, only that the task is considered ready for execution.
The precise execution time depends on the scheduling settings
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
Newsletters
Various types of confirmation messages
Content subscriptions
To allow the application to send out e-mails, 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 -> E-mails 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 mails 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. E-mails 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 e-mails:
Network - e-mails 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 -> E-mails.
Pickup directory - use this option if you expect high e-mail traffic on your servers (the method is faster and safer then the Network
method). The e-mails 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 E-mail (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 e-mail 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 e-mail processing


You can configure how the system delivers e-mails to the SMTP servers through the settings in Settings -> System -> E-mails.
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 e-mails
to learn more about the e-mail 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 e-mail 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 e-mails 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. e-mails 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 e-mails 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 e-mails in the System application on the Email tab.

Debugging e-mails
Debugging can help resolve problems with e-mails sent by Kentico.
To enable e-mail debugging, add the following keys to the configuration/appSettings section of your project's web.config file:

<add key="CMSLogEmails" value="true"/>


<add key="CMSDebugEmails" value="true"/>

CMSLogEmails - logs all sent e-mails to the ~/AppData/logemails.log file. The log contains each e-mail's recipient and subject.
CMSDebugEmails - disables sending of e-mails to the actual recipients. The system only logs e-mails into the event log. Helpful if
you need to test the functionality, but do not want the e-mails to actually reach the recipients.
To view the event log, open the Event log application.
The e-mails are logged as Information type events.
The Event code column contains the recipient's address.
The system randomly generates Sending failed for <recipient's e-mail address> errors to simulate sending errors.

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

Advanced

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.

Delivery method

The delivery method for e-mails sent from the system:


Network - the e-mail is sent directly to the SMTP server
defined by the server name and credentials.
Pickup directory - the e-mails 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 E-mail (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 e-mails will be stored until the
SMTP server processes them.
The IIS_IUSRS group must be granted write permissions for this
folder.

Managing e-mail templates


Kentico sends automatic system e-mails for various purposes, for example workflow notifications. The content of such e-mails is determined
by templates according to the type of the given e-mail. Many Kentico features send e-mails based on predefined templates that are included
in the default installation.
To edit the templates, open the E-mail 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 e-mail templates:
Global - only users with the Global administrator privilege level can manage global e-mail 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 e-mail 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 e-mail template (for example in


the API).

E-mail type

Identifies the type of functionality to which the template is related.


This can be used to categorize and filter e-mail templates.

From

E-mail address used as the sender (From) address of the e-mail.

Cc

E-mail addresses of copy recipients.

Bcc

E-mail addresses of blind copy recipients (receive a copy of the


e-mail, but cannot see the addresses of other recipients in the
mail).

Subject

Subject of the e-mail.

HTML version

Defines the content that is used for the template when sending
e-mails 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 e-mail template.

Example of the HTML version of a template:

<html>
<head>
</head>
<body style="font-size: 12px; font-family: arial">
<p>
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.
</p>
<p>
<strong>Page:</strong> <a href="{%DocumentEditUrl%}">{%documentname%}</a> {%
ifEmpty(DocumentPreviewUrl, "", "(<a href=\"" + DocumentPreviewUrl="" +
"\">preview</a>)")|(encode)false %}
<br />
<strong>Last approved by:</strong> {%approvedby%}
<br />
<strong>Last approved when:</strong> {%approvedwhen%}
<br />
<strong>Original step:</strong> {%originalstepname%}
<br />
<strong>Current step:</strong> {%currentstepname%}
<br />
<strong>Comment:</strong>
<br />
{%comment%}
</p>
</body>
</html>

Most templates contain macro expressions (such as {% currentstepname %}), which the system resolves dynamically when sending the
e-mails. The use of macros is necessary to ensure that individual e-mails contain information relevant to the situation that caused the e-mail
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 e-mail template through the Attachments button in the header of the template editing page. The
attachments are included when the system sends out e-mails 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 (
full content of the widget.
Remove widget (

) to restore the

) - 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.
2.
3.
4.

Open the Widgets application.


Select the widget in the catalog tree.
Open the Security tab.
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:

<table border="0" width="100%" cellspacing="0" cellpadding="0">


<tr>
<td colspan="2">
<div class="DashboardActions PageTitleHeader">
<cms:CMSWebPartZone ID="zoneTop" runat="server" />
</div>
</td>
</tr>
<tr>
<td colspan="2">
<cms:CMSWebPartZone ID="DashboardTop" runat="server" />
</td>
</tr>
<tr valign="top">
<td style="width:50%">
<cms:CMSWebPartZone ID="DashboardLeft" runat="server" />
</td>
<td style="width:50%">
<cms:CMSWebPartZone ID="DashboardRight" runat="server" />
</td>
</tr>
</table>

3. Click Save.
4. Switch to the Design tab.
5.
6.
7.
8.

Expand the menu (


) of the DashboardTop zone and click Configure.
Switch the Widget zone type property from None to Dashboard.
Click Save & Close.
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.
2.
3.
4.

Open your website in Visual Studio.


Create a New folder under the root called CMSGlobalFiles (if it doesn't already exist).
Rightclick the folder and select Add -> Web form.
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%>
<html xmlns="http://www.w3.org/1999/xhtml" <%=XmlNamespace%>>
<head id="Head1" runat="server" enableviewstate="false">
<title id="Title1" runat="server">Dashboard</title>
<asp:Literal runat="server" ID="ltlTags" EnableViewState="false" />
<style type="text/css">
body
{
margin: 0px;
padding: 0px;
height: 100%;
font-family: Arial;
font-size: small;
}
</style>
</head>
<body class="<%=BodyClass%>">
<form id="form1" runat="server">
<cms:Dashboard ID="ucDashboard" runat="server" ShortID="d" />
</form>
</body>
</html>

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:

[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 <script> tags.
Enforcing lower case - all HTML tags and attributes are
generated in lower case.
Fixing self closing tags - all HTML elements without closing
tags are properly closed. For example <br> is replaced by <br
/>.
Indentation - the HTML code of pages is organized into a
properly indented, easier to read format.
You can also enable fixing of XHTML errors for content entered
and saved in the system's WYSIWYG editors. This can be
configured globally by adding the CMSWYSIWYGFixXHTML key
into the /configuration/appSettings section of your application's web
.config file:

<add key="CMSWYSIWYGFixXHTML"
value="true" />

HTML 5 filter

The output filter provides a way to replace tag attributes that are
obsolete in HTML5. Such attributes are removed and the system
instead assigns CSS classes named in format <attribute
name>_<attribute value>. You need to define these classes in the
CSS stylesheet used by the website's pages.
The affected attributes are:
cellpadding
cellspacing
width
height
border
align
valign
For example:

<table cellpadding="2"
cellspacing="4">

is replaced by:

<table class="cellpadding_2
cellspacing_4">

Converting Tables to Div tags

You can use the output filter to automatically convert <table> elem
ents and their child <tr> and <td> tags to <div> elements with
appropriate CSS classes assigned (named according to the
replaced tag). You need to define these classes in the CSS
stylesheet used by the website's pages.
For example:

<table>
<tr><td>A</td><td>B</td></tr>
</table>

is replaced by:

<div class="table">
<div class="tr">
<div class="td">A</div>
<div class="td">B</div>
</div>
</div>

Tip: You can enable or disable table conversion for


specific blocks of HTML code by marking them with class
="_divs" or class="_nodivs" attributes. The filter then
allows you to convert only tables designated by the _divs
class, or all tables except for those marked with _nodivs.
See the descriptions of the output filter settings below.

Applying output filters to your website


By default, the system applies the output filters to all pages. If you do not wish to use the filters for specific sections of the website (for
example due to performance reasons), you can disable them through the Settings application in the System -> Output filter category.
Individual Excluded URLs fields are available for particular filter types.
You can disable output filters for all pages that start with a specific URL path by entering this path into the corresponding field
(without the ~ character and extension).
Multiple URL paths may be added, separated by semicolons (;).
Note: The settings only exclude specific URLs, not entire pages. For example, if you exclude the /Home URL path, but then access
the Home page through a different URL or alias (such as the website root configured to display the Home page), output filtering will
still be enabled.
Examples:
/ - disables the filter for the entire website.
/Products - disables filtering for the Products page under the website root and all other pages whose URL path starts with /Products
(e.g. child pages).
/Services;/News - excludes all pages whose URL path starts with /Services or /News.
/Company. - by adding the period character (".") after the URL path, you can exclude only one specific page, but not its child pages
(this does not work with extensionless URLs).
The following table describes all website settings available in the Output filter category:
General
Excluded output form filter URLs

Specifies the URLs of the pages that the system excludes from the
Form output filter.

Excluded resolve filter URLs

Specifies the URLs of the pages that the system excludes from the
URL resolving output filter.

XHTML filter
Excluded XHTML filter URLs

Specifies the URLs of the pages that the system excludes from all
functionality provided by the XHTML output filter.

Excluded XHTML attributes filter URLs

Specifies the URLs of the pages that the system excludes from the
Tag attribute XHTML filter.

Excluded XHTML JavaScript filter URLs

Specifies the URLs of the pages that the system excludes from the
JavaScript tag XHTML filter.

Excluded XHTML lower case filter URLs

Specifies the URLs of the pages that the system excludes from the
Lower case XHTML filter.

Excluded XHTML self close filter URLs

Specifies the URLs of the pages that the system excludes from the
Self closing tag XHTML filter.

Excluded HTML5 filter URLs

Specifies the URLs of the pages that the system excludes from the
HTML5 output filter.

Indent output HTML

Indicates if the system processes the HTML output of all pages into
a properly indented, easier to read format. The indentation applies
to all where the XHTML output filter is enabled.

Convert TABLE tags to DIV tags

Determines which tables the output filter converts to <div> element


s. Table conversion can be:
Disabled completely
Enabled for all tables except for those marked by the _nodivs
CSS class
Only enabled for tables designated through the _divs class

Enabling output filters for specific web parts


You can enable the output filters separately for the code generated by web parts. This allows you to filter the output of specific instances of
web parts, even if their page is excluded from the output filter via the website settings.
Note: The system always uses output filtering for web parts on pages that are not excluded through the website settings.
To access the output filter settings of web parts:
1.
2.
3.
4.

Open the Pages application.


Edit a page on the Design tab.
Configure (double-click) the web part.
Enable the Filter output HTML of web part property in the Output filter section.
This section of properties is available for all web parts.

5. Adjust the remaining properties in the Output filter section.


The configuration options correspond with the available types of output filters.

Configuring time zones


The Time zones application enables you to configure time zones for the physical location of your server, for particular websites and even for
particular users. This can be useful if your site has an international audience and you want the date and time displayed on your site to be
correct for users from across the world.
Before you can use this application, you must enable it by selecting the Enable time zones check-box in Settings -> System. See Settings System for additional options.
Time zones are currently supported in:
Pages, My desk, Events applications
Web parts of the Blogs, Forums, Message boards, Messaging and Smart search applications

Usage examples
A typical example of use is displaying the time of forum posts when you have a global community while the server may be located in New
York (GMT -5:00), visitors coming from Paris (GMT +1:00) may see their new posts were added at 8am, while they would expect to see 2pm
according to their current time.
Another example is a website of a global company that runs on a server in New York, but contains content for a French office. In this case,
French visitors may wonder why the current time displayed by the server is 8am while its 2pm in Paris. Thats when you use the built-in
support for multiple time zones.

Time zones web parts


Web parts of the Blogs, Forums, Message boards, Messaging and Smart Search applications have the Time zones section in their web part
properties, where you can set the applied time zone. The section contains the following two properties:
Time zone

Specifies the type of time zone that the web part uses for its
content. The following types are available:
Inherit - inherits the time zone settings from the Page
placeholder web part that displays the page template
containing the web part (only applies to nested pages).
Server - uses the server time zone settings.
Web site - uses the website time zone settings.
User - uses the time zone settings of individual users.
Custom - uses the time zone selected in the Custom time
zone property.

Custom time zone

Assigns a custom time zone specifically for the content of the web
part. The web part uses the selected time zone regardless of the
time zone settings of the website or user viewing the page.

In the case of the Calendar and Event calendar web parts, these web part properties take no effect. Instead, you have to ensure the
displaying of the correct time zone in the used transformation, as described in Displaying correct time in your code.

Setting time zones for users


Each user can have their own time zone settings. Where applicable, these time zone settings are used instead of the website's default time
zone. A user's time zone can be set in the administration interface on the Users -> edit user -> Settings tab. On the tab, you can select a
time zone using the Time zone drop-down list.
Users can also select their time zone on the live site, if you place the My Account or My Profile web part on one of your pages. If they have
access to the administration interface, they can select their time zones in the My profile application using the Time zone drop-down list.

Managing time zones


You can manage time zones in the Time zones application, where you can see a list of defined time zones.

Creating a new time zone


In the following example, you will learn how to create a new time zone:
1. Open the Time zones application.
2. Click New time zone.
3. Fill in the details of the new time zone.
See Configuring daylight saving time below.
4. Click OK.
You have just created the time zone. Now if you switch back to the time zones list, you should see the new time zone present among the
records.

Time zone properties


When defining a new time zone or editing an existing one, you can set the following properties:
Time zone name

Display name of the time zone.

Code name

Code name of the time zone.

GMT difference

Difference in hours between the time zone and Greenwich Mean


Time.

Use daylight saving time

If checked, daylight saving time (DST) will be used for this time
zone. Values set in the DST start rule and DST end rule properties
will be used to define the DST interval.

DST starts at

Based on values set in DST start rule, this field will display the
exact time when the time advance will occur.

DST ends at

Based on values set in DST end rule, this field will display the
exact time when the time advance will be rolled back.

DST start rule & DST end rule

Using these sets of properties, you can exactly define when the
time advance should be carried out.

Month

Month in which the time advance occurs.

Condition

Condition specifying the day that the change occurs on. Based on
the selected option, you can select day of the week, day number or
a combination of both.

Day

Two fields day of the week and day number can be used based
on the selected condition.

Time

Exact time of the time advance.

Value

Number of hours that will be added to the current time when the
time advance occurs.

Configuring daylight saving time


When creating a time zone or modifying an existing one, you may need to specify the daylight saving time (DST). This is a convention of
setting clocks so that afternoons have more daylight and mornings have less of it. The amount of time advance and dates of change vary
from country to country, however, it is usually a one hour advance at the beginning of spring and the advance is rolled back in autumn.
For more information about DST, see this article: http://en.wikipedia.org/wiki/Daylight_saving_time.
You can set the daylight saving time separately for each of the time zones when creating a new time zone or when editing an existing one:
1. Select the Use daylight saving time check-box.
2. Set the DST start rule for the current time zone.
a. First, select the month in which the change will be carried out using the Month drop-down list.
b. Specify on which day of the selected month the change will be carried out using the Condition drop-down list and the two D
ay drop-down lists.
FIRST

Day of the week can be selected. If you select Monday,


the time advance will occur on the first Monday of the
selected month.

LAST

Day of the week can be selected. If you select Monday,


the time advance will occur on the last Monday of the
selected month.

>=

Day of the week and day number can be selected. If you


select Monday and 15, the time advance will occur on the
first Monday after the 15th day of the selected month.

<=

Day of the week and day number can be selected. If you


select Monday and 15, the time advance will occur on the
last Monday before the 15th day of the selected month.

Day number can be selected. If you select 15, the time


advance will occur on the 15th of the selected month.

.
c. Set the time when the change will occur on the specified date using the Time field.
d. Set the time difference between the standard time and DST in the Value field.
This value represents the difference from standard time in hours.
Use this value (usually 1) for the DST start rule and 0 for the DST end rule.
3. Set the DST end rule as specified in the previous step. Set Value as 0.
4. Click OK to save the settings.

Working with object versioning


When using object versioning, the system creates and stores separate versions of objects when they are edited and saved. This allows you
to compare versions or roll back objects to a previous version.
Object versioning is about automatically creating versions of objects (CSS stylesheets, e-mail templates, web part containers, etc.).
If you are looking for versioning of content (pages), refer to the Configuring and using page versioning chapter.

Supported object types

In the following table, you can find all object types that support object versioning. In the Editing interface column, you can find the exact
location within the Kentico administration interface where you can edit objects of the given type. If versioning is enabled for a particular object
type, the Versions tab appears in the interface, where you can view and manage the edited object's versions.
Object type

Editing interface

Alternative forms

Forms -> edit a form -> Alternative forms -> edit an alternative
form
Page types -> edit a page type -> Alternative forms -> edit an
alternative form
Custom tables -> edit a custom table -> Alternative forms ->
edit an alternative form

CSS stylesheets

Pages -> Properties -> General -> click Edit


CSS stylesheets -> edit a stylesheet
other interfaces containing the stylesheet selector (e.g. when
editing a site, department, etc.)

Custom table definitions

Custom tables -> edit a table

Page type definitions

Page types -> edit a page type

E-mail templates

E-mail templates -> edit a template

Form definitions

Forms -> edit a form

Media files

Media libraries -> edit a library -> select a file

Newsletter issues

Newsletters -> edit a newsletter -> Issues -> edit an issue

Newsletter templates

Newsletters -> Templates -> edit a template

Page layouts *

Page layouts -> edit a layout

Page templates

Page templates -> select a template


Pages -> Design -> Open the page template menu (
hover over Edit template -> Template versions
other interfaces that allow editing of page templates

) ->

Queries **

Page types -> edit a page type -> Queries -> edit a query
Custom tables -> edit a table -> Queries -> edit edit a query
web part properties dialogs of web parts that have query
properties

Report graphs

Reporting -> select a report -> General -> select a graph and
click Edit

Report tables

Reporting -> select a report -> General -> select a table and
click Edit

Report values

Reporting -> select a report -> General -> select a value and
click Edit

Report definitions

Reporting -> select a report

Transformations

Page types -> edit a page type -> Transformations -> edit a
transformation
Custom tables -> edit a table -> Transformations -> edit a
transformation
web part properties dialogs of web parts that have
transformation properties

Web part containers

Web part containers -> edit a container

Web part layouts **

Web parts -> select a web part -> Layout -> edit a layout
Pages -> Design -> Configure a web part -> Layout

* Only shared page layouts are versioned custom layouts are versioned as part of the data of the parent page template.
** Only custom queries and web part layouts are versioned system queries and default web part layouts are not versioned.

Settings
Even though object versioning is enabled and functional by default, we recommend configuring the related settings for your system.
1. Open the Settings application.
2. Select the Versioning & synchronization -> Object versioning category.
3. Configure the available settings.
4.

4. Click Save.

Using object versioning


If object versioning is enabled, the Versions tab is displayed in the editing interface of objects that support versioning. Here you can see and
manage the versions that the system creates for the edited object.

How versions are created and numbered


The system creates and numbers object versions according to the following rules:
The current version is always the one at the top of the list. If you disable object versioning when existing versions already exist for
the object, the version at the top may not match the current status of the object.
If you create a new object, the system automatically creates the initial 0.1 version.
If you edit an existing object that had been created before object versioning was enabled, there are no versions on the tab initially.
When you edit the object and save the modifications, two versions are created: 1.0 with the original data and 1.1 with the currently
saved data.
When an object is edited and saved, the system checks the interval configured in the Save to last version if younger than
(minutes) setting.
If the time interval has not passed yet since the last save, the data is saved into the last version.
If the interval has passed, saving creates a new minor version (the version number is incremented by 0.1).
If you edit and save after the number of hours configured in the Promote to major version if older than (hours) setting, the latest
version is promoted to a major version and the new version follows the new major numbering (i.e. latest 2.3 is promoted to 3.0 and
the new one is numbered 3.1).
The current version can also be promoted to a major version manually by clicking Make current version major above the Object
history listing.

Managing versions on the Versions tab


You can perform a number of actions when editing objects on the Versions tab.
Make current version major - manually promotes the current object version to a new major version (for example, if the latest
version is 2.3, it is promoted to 3.0).
Destroy history - deletes all listed versions of the object.
The following Actions are available for each version:
View version - opens a new window where you can compare the object's data between different versions. See Viewing and
comparing version data.
Rollback version - returns the object to the given version. The rollback does NOT include the object's child objects, if there are
any (for example alternative forms, transformations, queries).
Delete - deletes the version from the object's history.
... -> Rollback with children - if the object has child objects, you can use this action to perform the rollback including the child
objects.

Managing page template and layout versions in Design mode


When editing pages in the Pages application on the Design tab, you can manage the versions of the page template and page layout.
Expand the menu (

) in the green page template header.

To manage the page template's versions, hover over Edit template... and click Template versions.
For templates that use shared page layouts, you can access the shared layout's versions by hovering over Edit layout... and clicking Shared
layout versions.

Clicking either of the items opens a dialog, where you can manage the corresponding object versions (see Managing versions on the
Versions tab for details).

Viewing and comparing version data


If you click View version ( ) when managing an object's versions, a dialog opens, where you can view the data stored in the object's fields
for the given version. You can also compare the data with other versions.
The following options are available:
Compare to - select the version that you want to compare with the viewed version.
Display all data - if checked, the dialog displays all data related to the given object, including child objects.

Objects recycle bin


You can configure the system to remove deleted objects to a recycle bin instead of deleting them permanently:
1.
2.
3.
4.

Open the Settings application.


Select the Versioning & synchronization -> Object versioning category.
Set Delete objects to recycle bin to either Versioned objects only, or All objects.
Click Save.

Deleted objects that match the setting are now moved to the recycle bin.

Managing objects in the recycle bin


To access deleted objects, open the Recycle bin application and select the Objects tab.
Standard users of the Kentico administration interface can only work with objects that they deleted
Users with the Global administrator privilege level can manage objects removed by any user
The following actions are available for each deleted object:
View - opens a new window with the data of the deleted object.
Restore - moves the object from the recycle bin back into the system (in the corresponding application).
Delete - permanently removes the object (cannot be restored).
Click Other actions (...) to access additional options. The options depend on the type of the object:
Global objects without site bindings:
Restore without site bindings - performs the standard restore action.
Restore to current site - performs the standard restore action.
Global objects with site bindings:
Restore without site bindings - restores the object, but does not assign it to any website.
Restore to current site - restores the object and assigns it to the current website (the one that is using the domain in the current
URL).
Site objects (objects whose definition contains the SiteID column):
Restore without site bindings - performs the standard restore action.
Restore to current site - restores the object and assigns it to the current website (the one that is using the domain in the current
URL).
To perform operations for multiple deleted objects, use the selection boxes and selectors below the list.

Creating alternative forms


Alternative forms allow you to create different versions of existing forms. The alternative forms can then be used instead of the default form in
the system's administration interface or on the live site. You can create multiple alternative forms for a single object and use each of them in
a different situation.

Object types for which you can create alternative forms


Object

Usage

UI for creating alternative


forms

Example

Forms

Live site - you can choose


to display an alternative
form using the On-line
form web part.
Administration interface to replace the default forms
for creating and editing
entries using the Automatic
ally used alternative forms.

Forms -> Edit form ->


Alternative forms

Creating alternative forms for


on-line forms

Custom tables

Administration interface to replace the default forms


for creating and editing
data entries.

Custom tables -> Edit custom


table -> Alternative forms

Creating alternative editing


forms for custom tables

Page types
_______________

Live site - using for


example the Contribution
s list web part (see the Us
er contributions chapter for
more details).
In the Pages application to
replace the default forms
for adding or editing pages
(after clicking New or on
the page's Form tab).

Page types -> Edit page type ->


Alternative forms

Creating alternative forms for


page types

System objects

Both on the live site and in


the administration
interface, depending on the
object type.

Modules -> Edit module ->


Classes -> Edit class ->
Alternative forms

Using the Custom registration


form web part

Alternative forms have no dedicated application in the administration interface, only the Alternative forms tab available when editing one of
the listed objects.
Additional topics:
Code names of automatically used alternative forms - provides a list of special code names, which can be assigned to alternative
forms. The system uses such forms automatically for certain actions (typically creation of new items or editing of existing ones).
Displaying filters using alternative forms - explains the usage of alternative forms as filters for displaying large numbers of records.

Alternative form properties


When creating new alternative forms or when editing existing alternative forms, you can set the following properties:
Display name

The name shown to users in the administration interface, e.g. when


selecting alternative forms.

Code name

A unique name that serves as an identifier for the alternative form.

Make new fields hidden

Enabling this property ensures that any new fields added to the
main form are not visible in the alternative form by default (the
system adds the fields to the alternative form with the Display
attribute in the editing form flag set as false).
Note: If the form uses a custom layout, it will not automatically
display new fields even if this property is disabled. In this case, you
must also add the new fields to the form layout.

Code names of automatically used alternative forms


If you create an alternative form and give it one of the reserved code names listed below, the system automatically uses the alternative form
when performing the corresponding action.
For example, if you create an alternative form for a page type and give it the insert code name, the form is used when pages of the type are
created in the Pages application.
The following table shows the reserved code names and the actions for which the particular forms are used:
Alternative form code name

Usage

Supported by

filter

Filter displayed above a list of items. See Di


splaying filters using alternative forms for
more details.

Forms, Custom tables

insert

Form used when creating a new item.

Forms, Custom tables, page types, system


classes

newculture

Form used when creating a new culture


version of a page.

Page types

update

Form used when editing an existing item.

Forms, Custom tables, page types, system


classes

Displaying filters using alternative forms


By creating an alternative form named filter for a form or a custom table, you can create filter used when a large number of records is
displayed in:
Forms -> Edit a form -> Recorded data
Custom table data -> Edit a custom table
Custom tables -> Edit a custom table -> Data
The number of records required for the filter to be displayed is 25 by default. You can change this value by adding the following key into the a
ppSettings section of your web.config file:

<add key="CMSDefaultListingFilterLimit" value="5" />

Filtering is possible based on all fields that store the following types of values:
Text
Boolean (Yes/No)
Integer numbers
Long integer numbers
Decimal numbers
Date & time
The required fields need to be displayed in the alternative form and an appropriate form control must be assigned to each field. A filter form
control is available for each data type:
Text filter
Boolean filter
Number filter
Date & time filter

Example - Contact us form filter


The following example demonstrate how to create a filter for the Contact Us form on the sample Corporate Site. The same procedure can
be used for any other form or a custom table.
In the default installation, the Contact Us form already has a pre-defined filter alternative form. You can just inspect its setting
instead of going through the example.

Adding the filter form


1. Open the Forms application.
2. Edit ( ) the Contact Us form.
3. Switch to the Alternative forms tab.

4.
5.
6.
7.

There should already be a pre-defined filter form. Click Delete ( ) so that you can go through the rest of this example and
create your own filter from scratch.
Click Create new form.
Enter the Display name: Filter. The code name is filled in automatically based on the display name.
Select the Make new fields hidden check box.
Click Save.

Configuring the filter fields


After you create the form, you need to modify the fields:
1. Switch to the Fields tab. In the listbox on the left, you should see all fields defined for the form. The first three are system fields and
they are not needed in the filter, so you can leave them as they are.
2. Select the fourth field - FirstName.
3. In the Field appearance section, set the Form control to Text filter.

4. Click Save.
5. Repeat the steps 3 and 4 for the LastName and Email fields. This ensures that these fields are also included in the filter.
6. Disable the Phone number and Message fields by unchecking the Display attribute in the editing form option and clicking Save i
n both fields.

Result
Once you have the filter created, return to the form's editing interface and select the Recorded data tab. You can try filtering based on
various parameters.

The default number of 25 records has to be present in the list in order for the filter to be displayed.
Therefore to see the filter, you either need to create the required number of records, or use the CMSDefaultListingFilterLimit web
.config key to lower the filter limit accordingly.

Health monitoring
Health monitoring enables website administrators to monitor and record load and performance of Kentico instances. The feature only stores
monitored values about the system in Windows performance counters. It does not perform the actual monitoring. For this purpose, you can
use external applications, for example the built-in Performance monitor in Microsoft Windows.

Monitoring of some of the values requires database access. To optimize performance in this case, you can install a dedicated Windows
service and let it handle monitoring of these values instead of the application.

To start using health monitoring:


1. Register performance counters in Windows
2. (Optional) Install the Health monitoring Windows services
3. Enable Health monitoring in Kentico
4. Use an external application to monitor values (for example, the Performance monitor)

Application name web.config key


Before getting to the counters, it is important to explain the following key in the appSettings section of the instance's web.config file:

<add key="CMSApplicationName" value="Default Web Site/CMS" />

This key is added to the web.config file automatically during installation. In case of IIS installation, the path to the instance in IIS is used as
the key's value. In case of a Visual Studio web server installation, the name of the target web project root folder is used. The value must be
less than 60 characters long. In general, the value of the key is used by Kentico Windows services to identify Kentico instances. Specifically
for Health monitoring, the value is used to identify performance counters to which the monitored values about the instance are written.
In case of Visual Studio web server installation, it is possible that multiple instances running on a single server may have identical
values of the key (if the instances are installed into folders with the same names). In this case, you need to ensure that the keys
have different values. Otherwise, values from these instances may be written to the same counters.

Performance counter categories


Kentico performance counters are stored in two categories:
Kentico - General (<CMSApplicationName>) - contains general counters monitoring the Kentico instance as a whole. It contains
singleinstance counters, which means each of the counters can be added to the list of monitored counters just once. If a counter is
present in this category as well as in the Sites category, its value in this category is a sum of values of all site instances of the
counter in the Sites category.
Kentico - Sites (<CMSApplicationName>) - contains site specific counters monitoring particular websites running in the Kentico
instance. It contains multiinstance counters, i.e. each of the counters can be added to the list of monitored counters multiple times
once for each website running in the instance. These counters are used only if the Enable site counters option is enabled in Settings
-> System -> Health monitoring.
The <CMSApplicationName> part of the category names is the value of the CMSApplicationName web.config key explained in the previous
section. For IIS installations, the value is reversed in the category names so that website name is stated first and the IIS path after it. For
example, if the IIS path is Default Web Site/CMS, you would have CMS/Default Web Site in the name of the category. This should provide
better orientation in the category list in Performance Monitor.

Performance counters definition XML


In ~\CMS\App_Data\CMSModules\HealthMonitoring, you can find the counters.xpc file. This is a file in XML format which contains
definitions of default performance counters for the respective instance of Kentico. It contains definitions of both General and Site counters.
When performance counters are registered in Windows, this file is accessed to get the list of counters to be registered.
Apart from this default file, the whole folder structure under ~\CMS\App_Data\CMSModules\ is also searched for other files with the .xpc exte
nsion when counters are registered. The other files can contain definitions of additional performance counters and when found, the counters
are registered as well.
The following code is an extract from the counters.xpc file:

<?xml version="1.0" encoding="utf-8"?>


<Counters>
<Counter
Key="allocatedmemory" Name="Allocated memory in MB" Description="The
size of allocated memory in megabytes." Type="NumberOfItems32"
Enabled="True" OnlyGlobal="True" />
<Counter
Key="pendingrequestspersecond" Name="Pending requests/sec"
Description="The number of pending requests per second."
Type="NumberOfItems32" Enabled="True" OnlyGlobal="True" PerSecond="True"
/>
...
</Counters>

Each counter element has the following attributes:


Key - counter key used for identification.
Name - name of the counter displayed in Performance Monitor or another monitoring tool.
Type - the type of the counter, all types are listed and explained at: http://msdn.microsoft.com/en-us/library/system.diagnostics.perfo
rmancecountertype.aspx
Enabled - indicates if the counter is enabled.
OnlyGlobal - indicates if the counter is included in the General category (true) or in both General and Sites categories (false).

Registering performance counters


There are three ways to register performance counters for a Kentico instance in Windows.

Registering counters during the installation


In the Components step of the custom installer, select the Register performance counters for Health Monitoring check box. The installer
automatically registers the performance counters for the given instance of Kentico.

Enable the Install Windows services for Scheduler and Health Monitoring option to install the Kentico Scheduler and Kentico Health
Monitor services. Installing these services can optimize the monitoring performance.

Registering and removing counters manually using the Windows service


To register performance counters manually:
1. Navigate to the CMS\Bin folder of your Kentico project folder (typically C:\inetpub\wwwroot\Kentico\CMS\bin)
2. Execute the HealthMonitoringService.exe file from the Windows command line with the following parameters:

HealthMonitoringService.exe /webpath=<disk path to web project root>


/createcounters

To remove already existing performance counters, execute the HealthMonitoringService.exe file with the following parameters:

HealthMonitoringService.exe /webpath=<disk path to web project root>


/deletecounters

Registering performance counters in Windows registry


Registration of performance counters is technically performed by adding specific keys to Windows registry. In the registry, these keys are
located in HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services. The keys represent individual registered counter categories and
have the same names as the respective registered counter categories.

When you delete the registry keys, you also remove the respective counter categories, which unregisters the counters.

Installing the Health monitoring Windows service


Kentico provides a dedicated Windows service for Health monitoring purposes called Kentico Health Monitor.
You can use this service to additionally register performance counters. This service is also useful for writing values to the Scheduled tasks in
queue, E-mails in queue and Error e-mails in queue performance counters. As these three counters require database access to get their
values, using the Windows service for their monitoring instead of the application itself can provide better performance.

Installing the Health monitoring Windows service using Kentico Service Manager
The easiest way to install the Health monitoring 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 Health Monitor service.
4. Click Install.

5. Click Start to start the service after it is installed.


You have installed the Kentico Health Monitor 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 Health monitoring Windows service using 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 /webpath="C:\inetpub\wwwroot\Kentico\CMS"
"c:\inetpub\wwwroot\Kentico\CMS\bin\HealthMonitoringService.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 HealthMonitoringService.exe file in the Bin folder


inside the application (typically c:\inetpub\wwwroot\Kentico\CM
S\bin\HealthMonitoringService.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 Health Monitoring (<CMSApplicationName web.config key value>) service.
6. Click the Start Service button on the top toolbar.

Uninstalling the Health monitoring Windows service using 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 Windows command line with the following parameters:

InstallUtil /webpath="C:\inetpub\wwwroot\Kentico\CMS"
"c:\inetpub\wwwroot\Kentico\CMS\bin\HealthMonitoringService.exe"
/LogToConsole=true /u

After executing this command, the Health monitoring Windows service for the Kentico instance specified by the /webpath parameter is
uninstalled.

Enabling health monitoring


Once you have Kentico performance counters registered in Windows, you need to enable Health monitoring in the Kentico settings:
In the Settings application, select the System -> Health monitoring category, and check the Enable health monitoring setting.
You can also adjust additional settings related to performance counters:
Setting

Description

Enable health monitoring

Indicates 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 the external Windows service is used to read and write


monitored values to the Scheduled tasks in queue, E-mails in
queue and Error e-mails in queue performance counters.
These counters require database access to get their values, so
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
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.

Monitoring using the Performance monitor


When you have registered the performance counters for your instance of Kentico in Windows and you have enabled Health monitoring
settings in the Kentico administration interface, you can start monitoring values written to the counters. You can use several applications for
this purpose, but this page describes how to use the Performance monitor, which is a native part of Windows.
To monitor values of Kentico counters using the Performance monitor:
1. Type perfmon in Windows Start menu search box and press Enter.
The system launches the Performance monitor.
2. Select Monitoring Tools -> Performance monitor in the navigation tree.
As you can see, only the default % Processor Time counter is monitored initially.
3. Click the Add.

4. From the Select counters from computer list, choose <Local computer>.
In the section below, you will see a list of all counter categories currently registered in Windows.
5.
6.
7.
8.

Select the Kentico - General (<IIS path>/<IIS website>).


Click Add >>.
Select Kentico - Sites (<IIS path>/<IIS website>).
Click Add >>.

Added counters will be added to the Added counters list on the right.
9. Click OK.
Back in the monitoring UI you can now see that the Performance monitor displays the values in counters in the graph. The values reflect the
real activity of the Kentico instance. You can switch between different ways how monitored values are displayed using the Graph type dropdown list.

Clearing counter values


1. Log in to the Kentico administration interface.
2. Open the System application.
3. On the General tab, click Clear performance counters.
This action clears values stored in all counters registered for the current Kentico instance.

Reference - default performance counters


The following table lists the default counters that are pre-defined in the counters.xpc file and registered in Windows by default:
Counter name

Category

Description

Values written by

Allocated memory in MB

Global

The size of memory allocated


by the application in
Megabytes.

Application

Cache expired items/sec

Global

The number of expired cache


items per second.

Application

Cache removed items/sec

Global

The number of items removed


from cache per second.

Application

Cache underused items/sec

Global

The number of underused


cache items per second.

Application

Content page views/sec

Global and Sites

The number of content pages


viewed per second.

Application

E-mails in queue

Global and Sites

The number of e-mails in the


E-mail queue.

Application or Windows
service*

Error e-mails in queue

Global and Sites

The number of e-mails in the


E-mail queue whose sending
failed.

Application or Windows
service*

Errors

Global

The number of errors in event


log since last application
restart.

Application

File downloads/sec

Global and Sites

The number of files


downloaded per second.

Application

Non-page requests/sec

Global

The number of non-page


requests per second.

Application

On-line users total

Global and Sites

The total number of on-line


users.

Application

On-line users authenticated

Global and Sites

The number of authenticated


on-line users.

Application

On-line users anonymous

Global and Sites

The number of anonymous


on-line users.

Application

Pages not found/sec

Global and Sites

The number of not found pages


(404 error) per second.

Application

Pending requests/sec

Global

The number of pending page


requests per second.

Application

Robots.txt views/sec

Global and Sites

The number of robots.txt page


requests per second.

Application

Important: For values to be


written to this counter, IIS must
be configured to handle .txt ext
ensions. See Custom and
extensionless URLs.
Running SQL queries

Global

The number of running SQL


queries.

Application

Running threads

Global

The number of running threads.

Application

Scheduled tasks running

Global

The number of running


scheduled tasks.

Application

Scheduled tasks in queue

Global

The number of scheduled tasks


in the queue.

Application or Windows
service*

System page views/sec

Global

The number of system pages


viewed per second.

Application

Warnings

Global

The number of warnings in


event log since the last
application restart.

Application

* The Windows service is used to write values to these counters only if it is installed and if the Use external service option is enabled in S
ettings -> System -> Health monitoring.
You can also define custom counters to monitor other system values.

Adding cookie law consent to web pages


The Cookie law is in effect in some European countries, which requires websites to ask visitors for consent to use cookies. You can find
more information at http://www.ico.gov.uk/. Kentico provides functionality that helps you comply with the law. ----------------

Quickly including cookie consent on your website


1.
2.
3.
4.

Open the Pages application.


Select the page where you want to display the consent message.
Switch to the Design tab.
Add the Simple cookie law consent web part onto the page.

Kentico cookies are separated into several cookie levels according to their importance in the system. There are three main levels designed to
comply with the law regulations.

Available cookie consent web parts


To display a text message and buttons asking visitors for consent to store cookies in their browsers, use one of the following web parts:
Cookie law consent
Simple cookie law consent
Both web parts are implemented by the ~/CMSWebParts/General/CookieLaw.ascx control. The "simple" variant is only a preconfigured
version of the same web part. By default, the web parts are not styled, so you need to update your site's CSS stylesheet to get the required
look and feel.

Cookie law consent


This web part offers three cookie levels to choose from:

No cookies
Only essential cookies
All cookies
On each level, actions to switch to the remaining levels are offered. You may customize the text messages, available actions as well as
button texts.
The Default user cookie level property sets the enforced cookie level before the user makes a choice.
(Use the system settings) option sets the default user cookie level to the settings defined for the web.config CMSDefaultCookieLevel
key (available values are None, System, Essential, Editor, Visitor, All as specified on the Cookie levels page).
The Compare current cookie level to property is a basis for other settings in the web part. It defines a level to which the user's current
cookie level is compared. Three states with their own settings are defined depending on the selected level:
When the current level is below the compared level (Below level behavior settings).
When the current level exactly matches the compared level (Exact level behavior settings).
When the current level is above the compared level (Above level behavior setings).
This should give you enough options to configure the web part.
The Preview cookie level property allows you to simulate the user cookie level in Edit and Preview mode.

Simple cookie law consent


This is a preconfigured version of the previous web part. The preset behavior is: Disable cookies by default, request allowing, and once
allowed, hide the web part.
Live site
Once you place the web part into your website, you might not see the message after switching to the live site. The reason is that all
users who access the Kentico administration interface have cookies enabled by default and the cookies are already stored in the
browser you are working with. To check whether your configuration of the cookie web part is correct, log out of the administration
interface and clear all cookies in your browser. Or try the website in a different browser or computer.

Cookie levels
Kentico classifies cookies into several levels according to their purpose. The levels allow you to set cookie levels for users. The following are
the default levels available in the cookie API (CMS.Helpers.CookieLevel class):
Cookie level

Description

None (-1000)

Absolutely no cookies are allowed, including the cookie that stores


the cookie level selected for users. This makes sense only if you
want to disable absolutely every cookie by default.

System (-100)

This level allows the session cookie (due to security on postback),


and CookieLevel cookie which remembers the cookie level
selected by the user. In terms of the end user and the Cookie law,
this means "Cookies are not allowed".

Essential (0)

Cookies which are required for all website functionality needed by


site visitors. This includes authentication, shopping cart, votes in
polls etc. From the visitor's perspective, this means "Allow only
cookies that I may need, but do not track me".

Editor (100)

Cookies which are needed for the administration interface to work


correctly. For example used to track the selected view mode,
remember tabs and sliders, etc.

Visitor (200)

All cookies that are not assigned to an explicit level (which also
includes your custom cookies if you use any) are considered to be
cookies identifying the visitor, i.e. user tracking cookies, which are
not really needed, but are useful for the site owner if using EMS.

All (1000)

This is a system level, that allows all cookies, no matter what their
level is. From the site visitor's perspective this means "Allow all
cookies now and in the future".

The numbers associated with each cookie level are integer constants, which allow you to further customize the levels or add custom levels.
The levels "None" and "All" have an absolute value of 1000 to provide enough space for future updates or custom levels.
For simplicity, there are 3 main levels, which represent the choices offered to visitors when asking for consent to use cookies:
Simplified cookie level

Corresponding API level

Description

No cookies

System

Enables the minimum cookies required for


the website to work, and remembers
whether the user allows cookies or not.

Only essential cookies

Essential

Enables all cookies required for website


functionality, but no tracking cookies.

All cookies

All

Enables all cookies used on the website.

These three levels are also used in the provided cookie web parts.
Automatic cookie consent for administrators and editors
If a user logs in to the administration interface, cookies are automatically enabled to provide full editing functionality. We expect
that loggging in to the administration interface identifies a user as staff, so there is no need for cookie consent.

Reference - Kentico cookies


The following table describes the cookies used in Kentico, and lists the level of each cookie:
Cookie name

Level

Description

CMSCookieLevel

System

Specifies which cookies are allowed by the


visitor.

ASP.NET_SessionId

System

Keeps the user session ID for security


reasons.

CMSPreferredCulture

Essential

Stores the visitor's preferred content culture


.

CMSMobileRedirected

Essential

Indicates if the visitor has been redirected


to the mobile version of the website by the
Mobile device redirection web part.

CMSCurrentTheme

Essential

Stores the name of the current visual theme


to provide proper design to the dialog
windows.

Webauthtoken

Essential

Live ID authentication cookie.

CMSForumPostAnswer

Essential

Keeps a list of Question-Answer forum post


s in which the user user voted for an
answer to prevent repeated votes.

CMSVotedPolls

Essential

Keeps a list of polls where the user voted to


prevent repeated votes.

CMSRatedDocuments

Essential

Keeps a list of pages that the user rated to


prevent repeated votes.

CMSShowDesktopVersion

Essential

Indicates that the visitor has switched to the


desktop (default) version of the website
from a specific device profile.

.ASPXFORMSAUTH

Essential

Stores the user's encrypted authentication


ticket when using forms authentication.

FormState

Editor

Form state flag to allow restoration of failed


requests.

CMSPreferredUICulture

Editor

Stores the preferred UI culture of the user.

CMSViewMode

Editor

Stores the user's current view mode (Edit,


Preview, Design, etc.).

CMSUserWords

Editor

User's custom word dictionary kept by the


spell checker.

DisplayContentInDesignMode

Editor

Remembers the user's setting of the Web


part content checkbox on the Design tab
(for example in the Pages application).

DisplayContentInUIElementDesignMode

Editor

Remembers the user's setting of the Web


part content check box on the Design tab of
UI elements.

CMSMacroDesignerTab

Editor

Remembers the last active tab of the Edit


macro condition dialog.

CMSSplitMode

Editor

Remembers the state of the language


version split-view mode when editing
multilingual websites.

CMSPreviewState

Editor

Stores the user's latest page design


preview preferences.

CMSPropertyTab

Editor

Remembers the last active tab of the


Properties section in the Pages application.

CMSViewTab

Editor

Remembers the last active tab of the View


section in the Preview mode of the Pages
application.

CMSValidationTab

Editor

Remembers the last active tab of the


Validation section in the Preview mode of
the Pages application.

CMSEdVariantSliderPositions<templateid>

Editor

Remembers the position of the variant


slider when defining variants for MVT or Co
ntent personalization.

CMSWebPartToolbarCategory

Editor

Stores the selected web part category on


the web part toolbar.

CMSWebPartToolbarMinimized

Editor

Remembers if the user minimized the web


part toolbar on the Design tab.

CMSCurrentDeviceProfileName

Editor

Stores the selected device profile when


editing pages.

CMSCurrentDeviceProfileRotate

Editor

Remembers whether the device preview


uses the landscape or portrait view.

CMSUniGraph

Editor

Stores the user's Snap to grid preference in


the advanced workflow and marketing
automation designer.

CMSSessionToken

Editor

Stores the token used by the web service


that provides the advanced workflow and m
arketing automation designer.

ABSelectorState<ABtestname>

Editor

Stores the state of the selectors on AB test


overview page.

VisitorStatus

Visitor

Indicates if the visitor is new or returning.


Used for tracking the visitors statistic in We
b analytics.

Campaign

Visitor

Stores the web analytics Campaign assign


ed to the visitor.

TrackedCampaigns

Visitor

Stores all the web analytics Campaigns,


which should be tracked within a JavaScript
snippet.

UrlReferrer

Visitor

Stores the URL referrer from which the user


arrives on the website.

CurrentContact

Visitor

Stores the GUID of the contact related to


the current site visitor. Used to track
activities on the website.

CMSAB<ABtestname>

Visitor

Used to track conversions for the test and


maintain consistent page content for the
visitor.Stores the name of the page variant
assigned to the visitor, the list of performed
conversions and information whether visitor
is included in A/B testing specified by an A/
B test.

CMSMVT<mvtestname>

Visitor

Stores the combination of variants assigned


to the visitor by an MVT test. Used to track
conversions for the test and maintain
consistent page content for the visitor.

CMSNoTestMVT<templateid>

Visitor

Stores the currently selected MVT


combination for editors in the administration
interface.

CMSShoppingCart

Visitor

Stores a reference to the user's active


shopping cart.

CMSBodyClass

Visitor

Body element class to provide accessibility


standards.

CMSEd<GUID>Current

Visitor

Stores the current step of Wizard layout we


b parts.

ChatLoggedInToken

Visitor

Stores the login state for the Chat applicati


on (indicates if the user is in the online
state).

ChatSupportLoggedInToken

Visitor

Indicates if the user is logged in to the


support chat.

<Window name>_<Group ID>_roomID

Visitor

Stores bindings between groups of chat


web parts and chat rooms (for a specific
window or tab).

chat_autoinitchat_displayed_<GUID>

Visitor

Remembers if the Automatically initiated


chat web part was shown to the user
(prevents multiple chat initiation
messages).

chat_kick_roomid_<room ID>

Visitor

Indicates that the user was kicked from the


specified chat room (and is not allowed to
return).

StrandsSBS_*

Visitor

Used by the Strands Recommender solely


for its own purposes. The cookies are
managed on the Strands side.

CMSStrandsTrackEvent_*

Visitor

Stores persistent HTTP context after a


page is reloaded. Used for tracking of
shopping cart events.

__openid_selector_*

Visitor

Stores OpenId user identification for


authentication purposes.

Third party

Cookie level

Notes

Social media

All (by default)

Social media integration web parts use the


corresponding social media's cookies.

Third party cookies

If social media web parts are not displayed


on your pages, lower the default social
media cookie level using this web.config
key.

Example Settings social


media cookie
level to "Visitor"
<add
key="CMSSocialMediaC
ookieLevel"
value="200" />

CKEditor

All

jQuery UI Layout

All

Step carousel viewer

All

51D

All

Used when the system is configured for 51


degrees.mobi mobile device detection.

Banning IP addresses
The Banned IPs functionality is useful when you want to prevent users with certain IP addresses from accessing or using your website in a
certain way. This typically happens when a user posts offensive material on a website (e.g. on a forum), harasses site members or behaves
in some other unwanted way.
IP banning can also be used to restrict access to your websites from certain areas of the world. These bans can be set either for individual
websites or globally for all websites in the system.

Enabling Banned IPs


To enable this functionality, select the Enable banned IPs check-box in Settings -> Security & Membership -> Protection.
Users attempting to perform an action from an IP address that is banned will get a page with a message displayed in their browsers (the
HTTP response code of the page will be 403.6). The default banned IPs redirect page can be found at ~/CMSMessages/BannedIP.aspx. You
can create your own page and set its URL using the Redirect banned IPs to URL setting.

Banning IP addresses
1. Open the Banned IPs application
2. Click New banned IP.
3. Enter the required details:
New banned IP settings...
IP Address

IP address to be banned.
The asterisk ( * ) wildcard can be used as a substitute for
any number in the IP address, substituting for all values from
0 to 255.
Example: 192.168.1.*

Ban type

Type of the ban. The following types are available:


Access to the website - users cannot access the site
from the entered address at all.
Login - users cannot log in from the entered address.
Registration - users cannot register from the entered
address.
All user actions - users can enter the site from this IP,
but they are not allowed to register or log in, and they
are not allowed to add any content to the site (e.g., blog
comments, board messages, etc.).

Enabled

If unchecked, the ban takes no effect.

Ban Reason

Text description of why the IP was banned.

Ban IP address

If selected, this IP address will be banned.

Allow IP address for this site if the IP address is banned


globally

If selected, this IP address will be allowed for the selected


site even if it is banned globally.

Allow site to override the ban

If checked, this ban can be overridden by bans set for


particular sites; can be set only for global bans.

4. Click Save.
Now if you go back to the list of banned IPs, you should see the newly created record present in the list.

Finding users' IP addresses


If you wish to find the IP address of a user responsible for a certain event:
1. Open the Event log application
2. Find the event you are interested in.
The IP address of the user who caused the event has its own column in the displayed table.
For example, if you want to find a user who often uses Bad words, enter BADWORD into the Event code field of the event log filter and
make sure Contains is selected. This displays a list of all Bad word violations and all relevant information including user names and their IP
addresses.
To find the IP address used by a specific user when they last logged on:
1. Open the Users application.
2. Edit the user whose IP address you wish to find.
You can find it on the General tab in the Last logon information field.
This can be useful if you get multiple abuse reports about some users and want to quickly find their IP address.

Configuring countries
The Countries application allows you to configure a list of countries, which is used in various places throughout the system. The countries
defined in this list are offered in forms, where the Country selector form control is used (for example in Contact management). Also, the list is
used for defining countries from which the customers can order products in an on-line store.

Creating new countries


Click New country to define a new country. The following properties are available when creating or editing a country object:
Country display name

The name of the country displayed to the users of your website.

Country code name

The string identifier of the country object used by developers in the


code. Unless there is a reason to set a particular value, you can
leave the default (automatic) option, and the system generates an
appropriate code name.

Country 2-letter code

Can be used to enter the country's two-letter country code.

Country 3-letter code

Can be used to enter the country's three-letter country code.

Working with system reports


The Reporting application allows you to create internal reports to watch the activity in the Kentico system and on websites, such as
recently created pages, expired pages, website visits, user registration etc.
The application gathers data from the database by using SQL queries and displays the results in highly customizable reports including tables
and graphs.

Creating reports
To watch the activity in the system and on websites, you need to create reports. Then you can add components to the report to display the
collected data, such as graphs, tables and values.
1.
2.
3.
4.
5.

Open the Reporting application.


Select a category in the tree.
Click New report.
Type in the Report display name.
Click Save.
The General tab of the report editing interface opens.
General tab properties
Report display name

Sets the name of the report displayed in the


administration interface.

Report code name

A unique name that serves as an identifier of the report,


for example in the API or URLs.

Report category

Shows the category under which the report belongs. You


can move the report to a different category by selecting
one from the drop-down.

Connection string

Sets the database connection string used by the report's


components (graphs, tables and values) when loading
data. You can override this value for individual
components by editing their details.
Only users who have the Set connection string permis
sion for the Reporting module are allowed to change this
property's value.
The system retrieves the list of connection strings from
the <connectionStrings> section of the application's
web.config file. The (default) option represents the CMS
ConnectionString added by the application's initial
database installer.
You can check the Inherit box to load the value from the
Default report connection string setting configured in
Settings -> Security & Membership.
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

Allow public users to see this report

Indicates if the report should be visible by public users if


it is published on the website using a reporting web part.

Enable subscription

If enabled, users with the Subscribe permission for the R


eporting module are allowed to subscribe to the report a
nd its components (graphs, tables or values).
This setting is also available when configuring the details
of individual components. Subscribing to specific
components is only possible if both settings are enabled.

6. Define the Layout of the report using the WYSIWYG editor. To retrieve and display information from the Kentico database, add the
following objects into the report's layout:
Tables
Graphs
HTML graphs
Values
Additionally, macro expressions are supported in the report layout.
You can view the output of the report on the View tab.
Localizing strings in reports
If you need to create a single report in multiple languages, follow the instructions given in Working with resource strings.

Creating tables in reports


Tables allow you to retrieve data from the Kentico database using an SQL query.
1. In the Reporting application, edit a report on the General tab.
2. Click New in the Tables section below the layout editor.
3. Define the properties of the new table:
Report table properties
Default
Display name

The name of the table shown in the user interface.

Code name

Name used in your code.

Enable export

If enabled, users who view the table are able to export the
displayed data to external files using the Microsoft Excel
(XLSX), CSV or XML format. The data export feature may be
accessed by rightclicking the table in the report, which opens
a menu with possible export actions.

Enable subscription

If enabled, users will be able to subscribe to the currently


edited report table. To allow subscriptions, it is also
necessary to have the Enable subscription box checked on
the General tab of the given report.

Query
Query

Here you can add the SQL query used to retrieve data to be
displayed by the table.

Is stored procedure

Indicates if the query is a stored procedure or not.

Connection string

Sets the database connection string used by the table's


query.
Only users who have the Set connection string permission
for the Reporting module are allowed to change this value.
The system loads the list of connection strings from the <con
nectionStrings> section of the application's web.config file.
The (default) option represents the CMSConnectionString ad
ded by the application's initial database installer.
You can check the Inherit box to load the Connection
string value set for the parent report.

No record text

Text to be displayed if the query doesn't return any data.

Skin
Skin ID

ID of the .NET skin (stored in the .skin files in ~/AppThemes/


<theme name>) which will be used for the table.

Paging
Enable paging

If enabled, paging will be enabled when the report table is


displayed. The paging can be configured by the two
properties below.

Page size

Number of table rows per page.

Paging mode

Type of paging controls displayed below the table. The


following options are available:
Previous-next buttons - displays buttons leading to the
previous and next page
Page numbers - displays page numbers leading to the
corresponding pages
Previous-next-first-last buttons - displays buttons
leading to the first, last, previous and next page
Page numbers-first-last buttons - displays page
numbers leading to the corresponding pages and
buttons leading to the first and last page

4.
5.
6.
7.

Click Save & Close.


Place the cursor in the layout editor where you want to put the table.
Select the defined table from the list in the Tables section.
Click Insert.
Tables are entered into the report layout editor as an expression in the following format: %%control:ReportTable?<report
code name>.<table code name>%%.

8. Click Save.

Writing queries for tables


The queries you write for tables are standard SQL queries that pull data from the Kentico database. For information about pages,
you can use the View_CMS_Tree_Joined table that returns published versions of all pages.

Table column names


The table column names use the same names as the column names from the returned data set. If you need to use user friendly
names, you can use the following syntax in the query:

SELECT PageTemplateDisplayName AS [Template Name], ...

Creating graphs in reports


Graphs allow you to retrieve data from the Kentico database and display it in various types of visual formats.
1. In the Reporting application, edit a report on the General tab.
2. Click New in the Graphs section below the layout editor.
3. Define the properties of the new graph:
Report graph properties:
Default
Display name

Display name of the graph shown in the user interface.

Code name

Code name of the graph.

Enable export

If enabled, users who view the graph are able to export the
displayed data to external files using the Microsoft Excel
(XLSX), CSV or XML format. The data export feature may be
accessed by rightclicking the graph in the report, which
opens a context menu with possible export actions.

Enable subscription

If enabled, users will be able to subscribe to the currently


edited report graph. To allow subscriptions, it is also
necessary to have the Enable subscription box checked on
the General tab of the given report.

Query
Query

Database query that extracts the data that will be displayed


in the graph. It must return at least two columns: first one for
categories, the other columns are used for values.

Is stored procedure

Indicates if the specified query is a stored procedure.

Connection string

Sets the database connection string used by the graph's


query.
Only users who have the Set connection string permission
for the Reporting module are allowed to change this value.
The system loads the list of connection strings from the <con
nectionStrings> section of the application's web.config file.
The (default) option represents the CMSConnectionString ad
ded by the application's initial database installer.
You can check the Inherit box to load the Connection
string value set for the parent report.

No record text

Text to be displayed if the query doesn't return any data.

Chart type
Graph type

The following graph types are available:


Bar chart - bar graph, accepts multiple values and displays
them next to each other.
Bar stacked chart - bar graph, accepts multiple values and
displays them on top of each other.
Pie chart - pie graph, accepts only one column for values.
Line chart - line graph, accepts multiple values and displays
them as separate lines.

Drawing style

The following chart styles are available:


Bar chart:
Bar - uses rectangular column bars

Cylinder - uses cylinders

Bar stacked chart:


Bar - uses rectangular bars

Cylinder - uses cylinders

Area - uses a line chart with the space under the lines
filled with the respective color

Pie Chart:
Pie - uses a standard circular chart divided into sectors

Doughnut - uses a circular chart with a blank center

Line chart:
Line - uses straight lines to connect values

SpLine - uses smooth curved lines

Overlay

If enabled, charts with multiple values display them behind


each other with the lower values in the front. Only available
for Bar charts displayed in 3D.

100% stacked

If enabled, values are displayed as a percentage of their


category's column. Only available for Bar stacked charts.

Orientation

Determines if bars are displayed horizontally or vertically.


Only available for Bar and Bar stacked charts with the Bar
drawing style.

Drawing design

Determines the aesthetic design of Pie charts.

Label style

Determines the style of 'pie piece' descriptions for Pie charts


.

Doughnut radius

Determines the width of Doughnut style Pie charts. Larger


numbers decrease the size of the center. Only available for
Pie charts with the Doughnut drawing style.

Collect pie slices

Items that represent a smaller percentage of the Pie chart th


an the value entered here will be added together and
displayed as a single item labeled Others. This ensures that
pie charts remain legible, even if there are many items with
very small values.

Show as 3D

If enabled, charts are displayed in 3D.

Rotate X

Rotates the chart around its X axis. Accepts values from -90
to 90. Only available if Show as 3D is enabled.

Rotate Y

Rotates the chart around its Y axis. Accepts values from


-180 to 180. Only available if Show as 3D is enabled.

Width

Determines the width of the chart image.

Height

Determines the height of the chart image.

Show Grid

Shows a thin dotted line grid in the graph chart, Not available
for Pie charts.

Title
Title

Title of the chart.

Title font

Determines font properties of the chart title.

Title color

Determines the color of the chart title. Accepts standard


HTML color names and hexadecimal color codes or the color
selector can be used.

Title position

Determines the position of the chart title.

Legend
Background color

Determines the background color of the legend. Accepts


standard HTML color names and hexadecimal color codes or
the color selector can be used.

Border color

Determines the border color of the legend. Accepts standard


HTML color names and hexadecimal color codes or the color
selector can be used.

Border size

Determines the size of the legend border.

Border style

Determines the style of the legend border.

Position

Determines the position of the legend in the chart.

Legend inside

If enabled, the legend is displayed inside the chart area.

Fixed legend

Allows a custom description to be set for the value in the


legend that will be used instead of the name of the source
column. This field is only usable for charts that display one
type of series, i.e. each item has a single value. It also
cannot be used for Pie charts.
It is possible to enter static text or use a macro that resolves
into the currently selected value of a report parameter in
format {%<parameter name>%}.
For example, if the report has a parameter named Campaign
Name that allows users to display the statistics of a selected
marketing campaign, {%CampaignName%} could be entered
into this field, and the legend value description would
automatically contain the name of the currently displayed
campaign.

Legend title

Sets the text caption of the legend.

X-axis
X axis title

Title of the horizontal axis in the chart.

Title color

Determines the color of the X axis title. Accepts standard


HTML color names and hexadecimal color codes or the color
selector can be used.

X axis angle

Determines the declination angle of X axis descriptions.


Setting this parameter to 90 causes upright descriptions.
Accepts values from -90 to 90.

X axis format

Can be used to specify the format of item descriptions on the


X axis that are in numerical or datetime format.
Numeric formatting:
Numbers can be formatted using .NET Custom numeric
format strings enclosed in curly brackets.
Examples:
{Item #} - X axis descriptions will be displayed as Item 1, Ite
m 2 etc.
{0.00} - numeric X axis descriptions will be displayed with
precision of two decimal places.
Date and time formatting:
The format can be set using singleletter .NET Standard date
and time format specifiers without quotes.
In addition, any custom formatting can be defined using
expressions enclosed in curly brackets. For example, {yyyy MM - dd - hh:mm} would specify a date and time format like:
2010 - 08 - 19 - 12:30

Title font

Determines font properties of the X axis title.

Position

Determines the position of the X axis title.

Axis label font

Determines font properties of X axis descriptions.

X axis interval

Sets the interval between X axis descriptions.

Use X axis sorting

If enabled, values are connected in the order they appear in


on the X axis, otherwise they are connected in the order they
have in the returned dataset. Only used by Line charts and
Bar Stacked charts with the Area drawing style.

Y-axis
Y axis title

Title of the vertical axis in the chart.

Title color

Determines the color of the Y axis title. Accepts standard


HTML color names and hexadecimal color codes or the color
selector can be used.

Y axis angle

Determines the declination angle of Y axis descriptions.


Setting this parameter to 90 causes upright descriptions.
Accepts values from -90 to 90.

Y axis format

Can be used to specify the format of value descriptions on


the Y axis that are in numerical or date-time format. The
same formatting options can be used as in the X axis
format field described above.

Use X axis settings

If enabled, X axis settings are used for the Title font, Positi
on and Axis label font properties.

Title font

Determines font properties of the Y axis title.

Position

Determines the position of the Y axis title.

Axis label font

Determines font properties of Y axis descriptions.

Series
Primary background color

Determines the primary color of series items in the chart.


Accepts standard HTML color names and hexadecimal color
codes or the color selector can be used. Not available for Li
ne charts.

Secondary background color

Determines the secondary color of series items in the chart.


Accepts standard HTML color names and hexadecimal color
codes or the color selector can be used. Not available for Li
ne charts.

Gradient

Gradient of the colors of the series items in the chart.


Transitions from Primary to Secondary background colors
. Not used when displayed in 3D. Not available for Line
charts.

Border color

Determines the border color for series items in the chart. Not
available for Line charts.

Border size

Determines the border size for series items in the chart. Not
available for Line charts.

Border style

Determines the border style for series items in the chart. Not
available for Line charts.

Display item value

If enabled, values are displayed above series items.

Item value format

Sets the format of the text displaying the values of series


items in the chart. This overrides the Display item value pro
perty.
Standard MS chart keywords can be placed into this field,
such as for example:
#VALX - displays the current value of the X axis.
#VALY - displays the current value of the Y axis.
#AXISLABEL - displays the current X axis label.
#INDEX - displays a number determined by the order of
the series item on the X axis, starting from 0.
#SER - displays the name of the current series, i.e. the
type of the value.
If the current value is numerical, the displayed format can be
modified by adding the following parameters after the
keyword:
{P} - displays the number as a percentage.
{C} - displays the number as a monetary amount in the
currency of the current language culture. specified in the
browser; please be aware that this does not convert the
value, it only influences the format.
{F} - displays the number with a floating point, this is the
default parameter.
{E} - displays the number in exponential format.
The number of digits after the decimal point can be specified
within the curly brackets.
For example #VALY{F2} displays Y axis values with a
floating point and a precision of 2 decimal places.

Line color

Determines the line color used in Line charts. Accepts


standard HTML color names and hexadecimal color codes or
the color selector can be used.

Line size

Determines the line size used in Line charts.

Line style

Determines the style used in Line charts. Not used when


displayed in 3D.

Symbols

Determines the symbols used for values in Line charts.

Item tooltip

Determines the content and format of the tooltip that is


displayed when hovering over a series item in the chart. This
field supports both Kentico macro expressions and standard
MS chart keywords as described in the Item value format pr
operty.

Item link

Causes the series items in the chart to serve as links to the


specified URL when clicked. The same macro expressions
and keywords as described in the Item tooltip property can
be used here as well.

Values as percent

If checked, graphs with multiple types of series (several


values per item) will convert item values into a percentage
out of the sum of all values for that item.
For example, if an item has two values, 3 and 9, they would
be converted to 25 and 75 respectively.
When using this setting, it is necessary to set the Chart
Area -> Scale max property to at least 100 to ensure that all
types of data are displayed correctly.
Not available for Pie charts, since these already display one
type of value as a percentage.

Chart area
Primary background color

Determines the primary background color of the chart area.


Accepts standard HTML color names and hexadecimal color
codes or the color selector can be used.

Secondary background color

Determines the secondary background color of the chart


area. Accepts standard HTML color names and hexadecimal
color codes or the color selector can be used.

Gradient

Gradient of the chart area background colors. Transitions


from Primary to Secondary background colors.

Border color

Determines the border color of the chart area. Accepts


standard HTML color names and hexadecimal color codes or
the color selector can be used.

Border size

Determines the size of the chart area border.

Border style

Determines the style of the chart area border.

Scale min

Sets the minimum Y axis value that is required for an X axis


category to be displayed. Not used by Pie charts.

Scale max

Sets the maximum value that is displayed on the Y axis. Not


used by Pie charts.

Ten powers

If large values are present in the chart, they are divided by


appropriate ten powers and the division ratio is displayed
with the y-axis title. Not used by Pie charts.

Reverse Y axis

If enabled, the vertical axis is reversed. Not used by Pie


charts.

Border skin style

Determines the skin of the chart area border.

Plot area

4.
5.
6.
7.

Primary background color

Determines the primary background color of the plot area.


Accepts standard HTML color names and hexadecimal color
codes or the color selector can be used.

Secondary background color

Determines the secondary background color of the plot area.


Accepts standard HTML color names and hexadecimal color
codes or the color selector can be used.

Gradient

Gradient of the plot area background colors. Transitions from


Primary to Secondary background colors.

Border color

Determines the border color of the plot area. Accepts


standard HTML color names and hexadecimal color codes or
the color selector can be used.

Border size

Determines the size of the plot area border.

Border style

Determines the style of the plot area border.

Click Save & Close.


Place the cursor in the layout editor where you want to put the graph.
Select the defined graph from the list in the Graphs section.
Click Insert.
Graphs are entered into the report layout editor as an expression in the following format: %%control:ReportGraph?<report
code name>.<graph code name>%%.

8. Click Save.

Writing queries for pie charts


The queries for pie chart graphs must return two columns: the item categories and their values. The graph automatically calculates
the displayed size of the given category.

Writing queries for bar graphs


The queries for bar chart graphs must return at least two columns: the item categories and their values. If you specify more than
two columns, the additional columns will be displayed side-by-side (Bar charts), in front of each other (Bar charts with the Overla
y setting enabled), on top of each other (Bar stacked charts) or they will divide one column by percentage (Bar stacked charts w
ith the 100% stacked setting enabled).

Writing queries for line charts


The queries for line chart graphs must return at least two columns: the item categories and their values. If you specify more than
two columns, the additional columns will be displayed as separate lines.

Creating HTML graphs in reports


In addition to the image-based graphs, data can be visually represented in HTML graphs. Graphs of this type are composed purely out of
HTML code (table and DIV elements). As a result, they can be dynamically scaled according to the amount of data that needs to be
displayed, unlike an image with a predefined size.
HTML graphs always use a horizontal bar layout, which can easily be extended to display any number of items. In most cases where scaling
is not an issue, it is recommended to use standard graphs, since they offer more customization options and graphical flexibility.
Like other reporting tools, HTML graphs retrieve the data to be displayed using queries. The queries must return at least two columns: the
first column is used for items and the others for their values. If more than two columns are specified, the values of these additional columns
are displayed below each other as differently colored bars.

By default, data is displayed in descending order, i.e. with the newest items at the top of the graph. To create a HTML graph:
1. In the Reporting application, edit a report on the General tab.
2. Click New in the HTML graphs section below the layout editor.
3. Define the properties of the new HTML graph:
HTML graph properties
Default:
Display name

Display name of the graph shown in


the user interface.

Code name

Code name of the graph.

Enable export

If enabled, users who view the graph


are able to export the displayed data to
external files using the Microsoft Excel
(XLSX), CSV or XML format. The data
export feature may be accessed by
rightclicking the graph in the report,
which opens a context menu with
possible export actions.

Enable subscription

If enabled, users will be able to


subscribe to the currently edited HTML
graph. To allow subscriptions, it is also
necessary to have the Enable
subscription box checked on the Gen
eral tab of the given report.

Query:
Query

Database query that extracts the data that will be displayed in the graph. It must
return at least two columns: first one for categories, the other columns are used
for values.

Is stored procedure

Indicates if the specified query is a stored procedure.

Connection string

Sets the database connection string used by the graph's query.


Only users who have the Set connection string permission for the Reporting mo
dule are allowed to change this value.
The system loads the list of connection strings from the <connectionStrings> secti
on of the application's web.config file. The (default) option represents the CMSCo
nnectionString added by the application's initial database installer.
You can check the Inherit box to load the Connection string value set for the
parent report.

No record text

Text to be displayed if the query doesn't return any data.

Title:
Title

Sets the title of the graph.

Legend:
Legend title

Sets the text caption of the legend.

Display legend

Indicates if the legend should be displayed.

Series:
Item name format

Can be used to specify the format of item descriptions on the X axis that are in
numerical or datetime format.
Numeric formatting:
Numbers can be formatted using .NET Custom numeric format strings.
Examples:
Item # - X axis descriptions will be displayed as Item 1, Item 2 etc.
{0.00} - numeric X axis descriptions will be displayed with precision of two decimal
places.
Date and time formatting:
The format can be set using singleletter Standard date and time format specifiers
without quotes.
In addition, any custom formatting can be defined. For example, yyyy - MM - dd hh:mm would specify a date and time format like: 2010 - 08 - 19 - 12:30

Item value format

Sets the format of the text displaying the values of series items on the Y axis of
the graph.
This field supports all types of Kentico macro expressions. The following macros
should be used most frequently:
{%ser%} - resolves into the name of the current item's series, i.e. the type of
the value.
{%xval%} - resolves into the X axis value of the current item.
{%yval%} - resolves into the Y axis value of the current item.
{%pval%} - resolves into the percentage that the value of the current item
represents out of the sum of all values in the graph. If there are multiple types
of Y axis values, they are all included in the total sum.
Examples:
{%ser%} = {%yval%} - displays the name of the series and its value (e.g. Visit
s = 287).
{%pval|(todouble)0.0|(format){0:0.0}%}% - displays the item's percentage
value rounded to one decimal place (e.g. 5.1%).

4.
5.
6.
7.

Item tooltip

Determines the content and format of the tooltip that is displayed when hovering
over a series item in the graph. The macro expressions described in the Item
value format property can also be used in this field.

Item link

Causes the series items in the graph to serve as links to the specified URL when
clicked. The macro expressions described in the Item value format property can
also be used in this field.

Click Save & Close.


Place the cursor in the layout editor where you want to put the HTML graph.
Select the defined HTML graph from the list in the HTML graphs section.
Click Insert.
HTML graphs are entered into the report layout editor as an expression in the following format: %%control:ReportHtmlGrap
h?<report code name>.<graph code name>%%.

8. Click Save.

HTML graphs on the live site


Because of the way they are constructed, HTML graphs are only displayed correctly in the administration interface. The necessary
styles will not be applied on the live site.
Therefore, it is recommended to avoid publishing reports containing HTML graphs on your website (you can find more information
about this process in Displaying reports on websites).

Creating values in reports


A value is an object that you can place into the layout of a report, which can be used to display a single scalar value returned by a query in a
specified string format.
1. In the Reporting application, edit a report on the General tab.
2. Click New in the Values section below the layout editor.
3. Define the properties of the new value:
Report value properties
Default
Display name

The name of the item in the list

Code name

Name used in your code

Enable subscription

If enabled, users will be able to subscribe to the currently


edited report value. To allow subscriptions, it is also
necessary to have the Enable subscription box checked on
the General tab of the given report.

Query
Query

Here you can add the SQL query used to retrieve data to be
displayed by the value.

Is stored procedure

Indicates if the query is a stored procedure or not.

Connection string

Sets the database connection string used by the value's


query.
Only users who have the Set connection string permission
for the Reporting module are allowed to change this value.
The system loads the list of connection strings from the <con
nectionStrings> section of the application's web.config file.
The (default) option represents the CMSConnectionString ad
ded by the application's initial database installer.
You can check the Inherit box to load the Connection
string value set for the parent report.

Format
Formatting string

You can format the displayed value using standard .NET


expressions. For example:
{0} - displays the value
{0:F1} - displays the value as a floating point number
with one digit displayed after the decimal point

4.
5.
6.
7.

Click Save & Close.


Place the cursor in the layout editor where you want to put the value.
Select the defined value from the drop-down list in the Values section.
Click Insert.
Values are entered into the report layout editor as an expression in the following format: %%control:ReportValue?<report
code name>.<value code name>%%.

8. Click Save.

Writing queries for scalar value


The queries for scalar values may return any number of columns and rows, but the only value that will be displayed is the value in
the first column of the first row of the result set.
See Example - creating a simple report for an example on how to create a report with a table, graph and a value.

Creating report categories


All reports are organized into categories in a hierarchical tree. We recommend keeping reports that monitor related actions in one category.
You can manage the categories in the Reporting application.

Creating new categories


1.
2.
3.
4.
5.
6.

Open the Reporting application.


Select the root of the reporting tree (the All reports category by default).
Click ... next to the New report button and select New category.
Type a name of the new category into the Category display name field.
Type a code name or leave it as (automatic).
Click Save.

The system creates a new report category.

Defining report parameters


Reports and their data can be filtered using parameters.
To create parameters for reports:
1.
2.
3.
4.
5.

Open the Reporting application.


Select the report in the tree.
Switch to the Parameters tab.
Click New field.
Define the properties of the parameter (using the field editor).

6. Click Save.
7. Switch to the General tab.
8. Add the parameter to the queries of the report objects (table, graph or value).
All parameters that you define can be used in the query using the @<parametername> expression (e.g., DocumentCreated
ByUserID = @UserIDParameter).
For an example of using parameters in reports, see the Defining report parameters section of Example - simple report.

Context parameters
In your queries, you can use parameters that provide information about the current context when the report is viewed, such as current user,
current site, etc.
@CMSContextCurrentUserID
@CMSContextCurrentUserName
@CMSContextCurrentUserDisplayName
@CMSContextCurrentSiteID
@CMSContextCurrentSiteName
@CMSContextCurrentSiteDisplayName
@CMSContextCurrentDomain
@CMSContextCurrentTime
@CMSContextCurrentURL
@CMSContextCurrentNodeID
@CMSContextCurrentCulture
@CMSContextCurrentDocumentID
@CMSContextCurrentAliasPath
@CMSContextCurrentDocumentName
@CMSContextCurrentDocumentNamePath
For example, if you want to display a list of all expired documents of the current website, you can use a query like this:

SELECT DocumentNamePath AS [Document path]


FROM View_CMS_Tree_Joined
WHERE DocumentPublishTo < @CMSContextCurrentTime AND NodeSiteID =
@CMSContextCurrentSiteID

Displaying parameter values in the report using macros


If you need to display the parameter values in the report, you can place the following macro expression in the report text: {%parametername
%}

For example:
List of pages expired on or before {%CMSContextCurrentTime%}
displays:
List of pages expired on or before 2/12/2013 12:06:49 PM
You can use this syntax for both custom report parameters and context parameters.

Storing data from reports


You can save the currently displayed data of a report for printing or for a later reference:
1. In the Reporting application, select a report.
2. Open the View tab.
3. Click Save.
The system archives the entire report into the system history. If the data displayed in the report changes, the saved reports are NOT affected.
You can view the saved reports on the Saved reports tab.

Exporting report data to files


Additionally, you can also export the data displayed in a report into external files using various formats. To export report data:
1. Switch to the View tab.
2. Rightclick on a graph or table in the given report and choose one of the offered options:
Export to Excel - exports the data displayed by the given object to an XLSX spreadsheet.
Export to CSV - exports data to a CSV file.
Export to XML - exports data to an XML file.
For more details on the data export feature, refer to the Exporting data from the user interface chapter.
Note: The data export function may be disabled for some tables and graphs, depending on the configuration of the given reporting
object.

Displaying reports on websites


If you want to display a report on the website or include it on a custom page in the Kentico administration interface, you can use the Report
web part.
To add a report to your website:
1.
2.
3.
4.

Open the Pages application.


Select the page in the content tree and switch to the Design tab.
Add the Report web part.
Define the report properties:
Report name - select the required report.
Display filter - indicates if a parameter filter should be displayed on the page (if the report has parameters specified).
Enable export - if enabled, users can export the data displayed in the report's charts and tables to other formats (Excel,
CSV or XML). Note that data export is not allowed if it is not enabled for the given graph or table (on the General tab of the
main reporting interface, select a graph/table from the list and click ... -> Edit).
Enable subscription - indicates whether authenticated users are allowed to subscribe to the components (graphs, tables or
values) in the displayed report. In addition to this property, subscription also needs to be enabled for the given report (on the
General tab of the main reporting interface) and the specific graph, table or value. See Subscribing to reports for more
information.

5. If the selected report has parameters defined, you can display their values by using the Set parameters button. However, if the Disp
lay filter property is enabled, these settings are ignored, since the parameters are configurable on the live site using the filter.
6. Click OK.
If you view the page on the live site, the report appears just like on the View tab in the Reporting application.

Other web parts


If you only wish to display a certain graph, table or value from the report, use one of the other web parts from the Reporting category:
Report chart
Report table
Report value
You must specify the exact chart/table/value in the respective property of the web part. The first list is used to select the report, the second
one specifies the chart, table or value.
These web parts are also available as widgets.

Subscribing to reports
If users are interested in the content of a specific report or want to follow the progress of its data, they can use the subscription feature.
Subscribers will regularly receive e-mails with the uptodate status of the given report. This way, users can easily keep track of the data
provided by the report simply by checking their e-mail, without having to access the website or its administration interface.

Requirements
There are several levels of settings for enabling report subscriptions:
On the General tab of the report editing interface in the Reporting application, the Enable subscription checkbox applies to the
entire report.
Another Enable subscription setting is available when configuring the details of individual components (graphs, tables or values). If
both these settings are enabled, it is possible to subscribe to specific components.
For reports published on the website's pages, subscription also needs to be allowed through the Enable subscription property of
the web part or widget used to display the given report.
Additionally, subscription is only available for users who belong to a role that has the Subscribe or Modify permission for the Reporting mod
ule.

Subscribing to reports
To subscribe to an entire report, click the Subscribe action in the header of the page. This can be done:
On a report's View tab in the Reporting application.
In any section of the administration interface that provides reports (such as Web analytics).

To subscribe to individual components of the report (graphs, tables or values):


1. Right-click the appropriate component in the report.
2. Select the Subscribe to option in the menu.
To subscribe to a report displayed on the live site:
1. Right-click a chosen component in the report (you cannot subscribe to the whole report).
2. Select the Subscribe to option in the menu.

Report subscription settings


The following settings are available for report subscriptions:
Subscription settings
Send to

Sets the e-mail address to which the subscription e-mails will be


sent. By default, the address of the current user is loaded, but it is
possible to specify a different one.

Subject

Allows you to enter the subject that will be used for the subscription
e-mails.

Subscription item

Determines whether the subscription e-mails should include the full


content of the report or only a specific graph, table or value
component.

Time range

This setting is only available for reports that offer the possibility of
displaying data from a specific time range, selected using From an
d To parameters (e.g. most web analytics and online marketing
reports in the system).
You can choose from the following options:
All available data - the reports in the subscription e-mails will
always include all possible data with an unlimited time span.
Only chosen period - the reports will only contain the latest
data based on the date and time when they were sent. You
can use the Data from last field below to specify exactly how
many hours, days, weeks, months or years of data should be
included.

Sending interval

Through the interval settings, you can define how often and when
exactly the report subscription emails should be sent.

Condition

May be used to enter an additional macro condition that must be


fulfilled in order for the subscription emails to be sent.
For example: SiteObjects.ABTests.HomePageTest.ABTestEnabled
This sample condition ensures that the subscription is active only
while a specific A/B test (with code name HomePageTest) is
enabled. You can write any condition according to your specific
requirements.

Send only if data found

If checked, subscription e-mails will only be sent if the report


contains data at the given time (the subscriber will not receive
empty reports).

Enabled

E-mails will only be sent for subscriptions that are enabled.

Subscription parameters
If the given report has parameters, this section allows you to set the values that should be used in the reports sent to the subscriber. Only
parameters that are configured to be visible when viewing the report can be edited (i.e. those that have the Display attribute in the
editing form checkbox enabled on the Parameters tab of the given report).

Time range parameters


Some reports offer the possibility of displaying data from a specific time span selected through parameters. This functionality is
ensured by two parameters with Column names set to FromDate and ToDate respectively on the Parameters tab.
These two parameters are not displayed in the subscription parameters section. Instead, subscriptions to reports that contain them
provide the Time range and Data from last settings, which may be used to specify the appropriate values.

Unsubscribing
Users can cancel their subscription to a report in the following ways:
By clicking on the unsubscription link included in every e-mail (when using the default email template).
The link leads to the ~/CMSModules/Reporting/CMSPages/Unsubscribe.aspx system page, where the user can confirm that
they wish to unsubscribe from the given report. The appropriate subscription to be removed is automatically identified using
parameters passed in the query string of the link's URL.
Site administrators can manage subscriptions of a chosen report in the Reporting application (edit the report on the Subscriptions t
ab).
Users with access to the administration interface can view their report subscriptions in the My profile application on the Subscriptio
ns tab, and manually Unsubscribe ( ) as needed.
All report subscriptions created by the current user are listed here, even if the target e-mail address belongs to someone
else.

For live site users, the Unsubscribe option can be provided by the My account web part (as long as the web part's Display my
subscriptions and Display report subscriptions properties are enabled).
After unsubscribing through any of the described ways, the system automatically sends a notification e-mail to the given address.

Managing report subscriptions


When editing a report in the Reporting application, you can view and manage all of its subscriptions on the Subscriptions tab.
Creating or editing subscriptions here offers the standard subscription dialog, but with several additional options:
Subscription item selector - can be used to choose whether the subscription e-mails should include the full content of the report or
only a specific graph, table or value component.
Enabled - uncheck to disable individual subscriptions.
Subscription parameters section - if the currently edited report has parameters, this section provides a way to enter the values that
should be used for the reports sent to the subscriber.
You can edit only those parameters that are configured to be visible when viewing the report (i.e. those that have the Displa
y attribute in the editing form flag enabled on the Parameters tab).

Every authenticated user may also configure these options for their own report subscriptions in My profile -> Subscriptions or on a page
containing the My account web part, after editing (

) the appropriate subscription.

Time range parameters


Some reports offer the possibility of displaying data from a specific time span selected through parameters (e.g. most web
analytics and online marketing reports in the system). This functionality is ensured by two parameters with Column names set to F
romDate and ToDate respectively on the Parameters tab.
These two parameters are not displayed in the Subscription parameters section. Instead, subscriptions to reports that contain
them provide the Time range and Data from last settings, which may be used to specify the appropriate values.

Scheduling subscription mailout


To ensure that the report subscription e-mails are sent correctly and at the appropriate time, the system uses a global scheduled task called
Report subscription sender. When executed, this task goes through all enabled reporting subscriptions and checks their settings. If the
time interval requirements and condition of a subscription are fulfilled, the system sends out an e-mail with the current content of the given
report.
By default, the system executes the task every minute. You can change this configuration in the Scheduled tasks application. However, if
you wish to use report subscriptions, the task must always be enabled and scheduled frequently.
Important!
To be able to send e-mails, the system needs to be connected to a working SMTP server. To learn how this can be done, see the
Configuring SMTP servers topic.

E-mail templates
The content of the reporting e-mails sent to subscribers is based on e-mail templates. If you wish to customize the e-mails in some way, you
can edit the templates in the Email templates application. The following templates are available:
Reporting - Subscription template - defines the content of the main subscription e-mails used to send the report status.
Reporting - Subscription confirmation - used for the automatic notification e-mails sent to the recipient when a new subscription is
created.
Reporting - Unsubscription confirmation - used for the notifications that users receive after unsubscribing (or when the
subscription is removed by an administrator).

Reports in plain text


If your system is configured to send e-mails in plain text format, the content of report subscription e-mails will be limited. In this
case, image based graphs are included as attachments and the data from tables is sent in an a CSV file. HTML graphs are not
represented at all.
You can choose the preferred e-mail format using the E-mail format setting in Settings -> System -> Emails.
You can use the following macros in report subscription email templates:
{% SubscriptionBody %} - this macro is resolved into the content of the subscribed report or component.
{% DefaultSubscriptionCSS %} - used to add the CSS styles that are required to properly display report content in the e-mail. This
should always be included in the <head>/<style> element in the HTML version of the subscription template.
{% ItemName %} - for subscriptions to individual reporting components, this macro resolves into the name and type (graph, table or
value) of the given item. In the case of full report subscriptions, it returns an empty string.
{% UnsubscriptionLink %} - generates a link that can be used to cancel the given subscription.
It is also possible to access the following related objects and their properties (e.g. {% Report.ReportDisplayName %} ):
{% Report %} - ReportInfo object representing the report to which the user is subscribed.
{% ReportSubscription %} - ReportSubscriptionInfo object of the subscription for which the e-mail is being sent.

Example - creating a simple report


This example demonstrates how to create a report that displays a table, graph and value, and uses a reporting parameter:

Creating a report category


1.
2.
3.
4.
5.
6.

Open the Reporting application.


Select the root of the reporting tree (the All reports category by default).
Click ... next to the New report button and select New category.
Type User reports as the Category display name.
You can leave the code name as (automatic).
Click Save.

Creating a new report


1. In the Reporting application, click New report.
2. Type Pages by page template as the Report display name.
3. Click Save.
Now you can edit the layout of the report and insert tables, graphs and values.
The General tab of the report editing interface opens.
4. Type Pages by page template into the Layout text area.
5. Select the text and use the editor to set the Format to Heading 1.

6. Click Save.

Creating a new table


1. On the report's General tab, click New in the Tables section below the layout editor.
2. Enter the following values:
Display name: Pages by Page Template
Query:

SELECT PageTemplateDisplayName AS [Template Name], DocumentNamePath AS


[Page]
FROM View_CMS_Tree_Joined
LEFT JOIN CMS_PageTemplate
ON CMS_PageTemplate.PageTemplateID =
View_CMS_Tree_Joined.DocumentPageTemplateID
WHERE PageTemplateDisplayName IS NOT NULL AND PageTemplateIsReusable =
1
ORDER BY PageTemplateDisplayName

3.
4.
5.
6.

7.

Is stored procedure: no
SkinID: ReportGridAnalytics
Enable paging: yes (checked)
Page size: 10
Page mode: Page numbers
Click Save & Close.
Place the cursor in the layout editor on a new line under the heading.
Select the table from the list in the Tables section.
Click Insert.
The system adds a string like %%control:ReportTable?PagesByPageTemplate.PagesByPageTemplate%% into the text
area.
Click Save.

Switch to the View tab to see the report table.

Creating a new graph


1. Switch back to the report's General tab.
2. Click New in the Graphs section below the layout editor.
3. Enter the following values:
Display name: Favorite Page Templates
Query:

SELECT TOP 5 PageTemplateDisplayName AS [Template Name],


COUNT(PageTemplateDisplayName) AS [Usage]
FROM View_CMS_Tree_Joined
LEFT JOIN CMS_PageTemplate
ON CMS_PageTemplate.PageTemplateID =
View_CMS_Tree_Joined.DocumentPageTemplateID
WHERE PageTemplateDisplayName IS NOT NULL AND PageTemplateIsReusable =
1
GROUP BY PageTemplateDisplayName
ORDER BY COUNT(PageTemplateDisplayName) DESC

Graph type: Pie chart


Drawing style: Pie
Title: Favorite page templates
Series -> Display item value: Disabled (not checked)
4.
5.
6.
7.

Click Save & Close.


Place the cursor in the layout editor on a new line under the table.
Select the graph from the list in the Graphs section.
Click Insert.
The system adds a string like %%control:ReportGraph?PagesByPageTemplate.MostFavoritePageTemplates%% into the
text area.
8. Click Save to save the changes.
If you now switch to the View tab, you can see the report graph.

Creating new values


1. Switch back to the report's General tab.
2. Click New in the Values section below the layout editor.
3. Enter the following values:
Display name: Number of pages with page template
Query:

SELECT COUNT(DocumentID)
FROM View_CMS_Tree_Joined
WHERE DocumentPageTemplateID IS NOT NULL

Is stored procedure: no
Formatting string: Pages with template: {0}
4.
5.
6.
7.

Click Save & Close.


Place the cursor in the layout editor under the graph.
Select the new value from the list in the Values section.
Click Insert.

7.
The system adds a string like %%control:ReportValue?PagesByPageTemplate.NumberOfPagesWithPageTemplate%% into
the text area.
8. Click Save.
If you switch to the View tab, you can see the text of the value.

Defining report parameters


1. Switch to the Parameters tab.
2. Click New field and enter the following values:
Field name: UserID
Field type: Integer number
Default value: 53
Field caption: Created by user
Form control: User selector
3. Click Save.
Now you need to add the parameter to your queries. For the purposes of this example, modify only the table query.
1.
2.
3.
4.

Switch to the General tab.


Select Pages by page template in the Table list.
Click ... next to the New button and select Edit.
Modify the table SQL query like this:

SELECT PageTemplateDisplayName AS [Template Name], DocumentNamePath AS [Page]


FROM View_CMS_Tree_Joined
LEFT JOIN CMS_PageTemplate
ON CMS_PageTemplate.PageTemplateID =
View_CMS_Tree_Joined.DocumentPageTemplateID
WHERE PageTemplateDisplayName IS NOT NULL AND DocumentCreatedByUserID =
@UserID
ORDER BY PageTemplateDisplayName

This adds the parameter to the WHERE condition of the query. All parameters that you define can be used in the query
using the @<ParameterFieldName> expression.

5. Click Save & Close.


Now switch to the View tab. You can see that the report has a filter:

The table now only displays template names of pages that were created by the user specified in the filter.

Reporting security
You can configure access to reporting features in the Permissions application. Choose the permission matrix for Module -> Reporting and
assign the available permissions to the appropriate user roles.

Permission

Description

Read

Allows users to view existing reports.

Save reports

Allows users to save reports into the report archive.

Modify

Allows users to create, modify and delete reports. This also grants
permission to subscribe to reports.

Destroy

Allows users to delete the version history of reporting objects.

Edit SQL queries

Allows editing of the queries used to retrieve data for reporting


components (graphs, tables and values). This permission is
needed to create new reports, but it can be a security risk, since it
allows users to run queries against the website's database.

Subscribe

Allows users to subscribe to reports and their components.


Subscription also needs to be allowed for individual reports through
their properties. Unauthenticated (public) users cannot subscribe to
reports.

Set connection string

Allows users to change the connection string property of reports


and their components. The report uses the specified connection
string to access the database when loading data.

Making reports available on the live site


1.
2.
3.
4.

Open the Reporting application.


Select the report in the tree and switch to the General tab.
Enable the Allow public users to see this report property.
Click Save.

The system now allows you to display the given report on the live site to non-authenticated (public) users. If the property is disabled, the
report and all of its components (graphs, tables or values) are always hidden from public users

Specifying connection strings for reports


You can restrict the database-level permissions of the SQL queries used for reporting by registering custom connection strings and assigning
them to reports.
1.
2.
3.
4.

Prepare a user account for your Kentico database with the required security configuration.
Edit your application's web.config file.
Add a new connection string into the <configuration><connectionStrings> section.
Enter authentication information (the user id and password) for the appropriate database user account.

<add name="CMSReadOnlyConnectionString" connectionString="Persist Security


Info=False;database=DBName;server=ServerName;user
id=DBUser;password=password;Current Language=English;Connection Timeout=240;"
/>

5. Open the Settings application.


6. Select the Security & Membership category.
7. Choose the Default report connection string (in the Reporting section).
Connection string names
The setting loads the list of connection strings from the web.config and displays their name attribute values. The (default)
option represents the CMSConnectionString added by the application's initial database installation.
The system assigns the specified connection string to newly created reports. By default, all existing reports also inherit the connection string
value from this setting.

Assigning a connection string to a specific report


1. Open the Reporting application.
2. Edit any reports for which you wish to set a non-default connection string.
3. On the General tab, uncheck the Inherit box below the Connection string property and select a different option. You can also
override the connection string value for individual reporting components (graphs, tables and values).
The system now uses the assigned connection string when executing the queries of reports. This limits the functionality of the queries
according to the database permissions of the user account specified in the connection string. Only users who have the Set connection
string permission for the Reporting module are allowed to change the connection strings of individual reports.

Configuring Windows Communication Foundation


This page describes the installation and configuration process of Windows Communication Foundation (WCF). You have to configure
WCF to use the following features:
Advanced workflow designer
Marketing automation process designer
Chat application

WCF overview
WCF is a component of the .NET Framework that provides a programming model for building service-oriented multi-platform applications that
communicate across the web. For more information on the technology, visit http://msdn.microsoft.com/en-us/netframework/aa663324.

Installing WCF
WCF is automatically installed with .NET 3.0 and any higher version. However, you still need to install the WCF HTTP Activation feature
yourself:
1.
2.
3.
4.

Open the Start menu in Windows.


Navigate to Settings -> Control Panel -> Programs -> Programs and Features.
Click on Turn Windows features on or off.
Under the Microsoft .NET Framework 3.5 node, select the Windows Communication Foundation HTTP Activation check box.

5. Click OK to start the installation.


The system installs WCF on your computer.
If you've installed WCF on a machine that had ASP.NET already installed, re-register ASP.NET into IIS. Use the ASP.NET IIS
Registration Tool (aspnet_regiis.exe) with the -i parameter.

aspnet_regiis.exe -i

Configuring WCF services to use SSL


WCF services in Kentico applications are defined as service endpoints. By default, the service endpoints point to HTTP bindings. To use the
services with SSL enabled, you must point the service endpoints to secure HTTPS bindings. Service endpoints and bindings are defined in
local, application-specific, web.config files. You configure each service separately.
1. Locate the application-specific web.config file according to the following table:
Application

Web.config location

Chat

/CMSModules/Chat

Marketing automation

/CMSModules/Automation

Workflow

/CMSModules/Workflows

2. Open the web.config file and uncomment the secure endpoint code. The endpoint is defined in the configuration/system.serviceMod
el/services section.

Example - commented HTTPS (secure) endpoint for Workflow


<!--<endpoint name="Secure" address=""
behaviorConfiguration="WorkflowDesignerEndpointBehavior"
binding="webHttpBinding" bindingConfiguration="WorkflowDesignerSecureBinding"
contract="CMS.WebServices.IWorkflowDesignerService" />-->

3. (Optional) If you don't want the service to use the non-secure HTTP, comment out (or delete) the non-secure endpoint code.

Example - HTTP (non-secure) endpoint for Workflow


<endpoint name="Public" address=""
behaviorConfiguration="AutomationDesignerEndpointBehavior"
binding="webHttpBinding" contract="CMS.WebServices.IWorkflowDesignerService"
/>

The system now communicates with the services defined in the services section using the specified endpoints.

Configuring the administration interface URL


Users access the Kentico administration interface via the /admin URL path. You can change the URL path to a different string if, for example,
you want to prevent random visitors viewing the logon page.
Backward compatibility
Prior to version 8, Kentico used /cmsdesk and /cmssitemanager paths to access the administration interface. Do not change the
primary path back to /cmsdesk or /cmssitemanager.
1. Open the web.config file in the root folder of your project.
2. Add the following key into the appSettings section:

<add key="CMSAdministrationPath" value="NewAdministrationPath"/>

3. In the root folder of your project, create a folder with the same name as the URL path that you chose.
4. Download the attached archive and place the archive's contents inside the folder.
The code in these files redirects requests made to your new URL path to the ~/Admin/CMSAdministration.aspx page, which
handles administration interface requests.
5. Build the solution.
The administration interface is now accessible via <your_website_url>/NewAdministrationPath. The original /admin path returns error 404
page not found. Regardless of the current URL path, you can access the administration interface by requesting the ~/Admin/CMSAdministrati
on.aspx page.

Configuring the code editor


The interface of Kentico contains areas where users can enter code that defines the appearance or behavior of websites. The code fields use
an editor that provides syntax highlighting and other features to help website developers write and maintain sections of code.
Highlighting ensures that text elements are displayed in different colors depending on the syntax of the given language. Syntax highlighting
improves the readability of code and makes it easier to spot and avoid mistakes. All languages commonly used for web development are
supported, including HTML, ASPX markup, CSS, JavaScript, SQL, XML and C#. Each language has its own set of highlighting rules for code
formatting.

In addition to syntax highlighting, the editor also provides other types of functionality:
Show/hide line numbers - enables or disables the panel that displays line numbers.
Toggle fit-to-window mode - toggles the editor between its normal size and an expanded editor covering the entire window (frame).
Show hide/bookmarks - enables or disables the bookmark panel on the side of the editor. Only available for CSS code by default.
Undo (CTRL+Z) - removes the last change made to the code in the editor, restoring it to its previous state. The editor stores the
history of changes, so you can use the Undo action multiple times.
Redo (CTRL+Y) - reverses one previously made Undo action.
Search - opens a dialog that allows users to search the code in the editor for a word or phrase.
Replace - opens a dialog that allows users to find a word or phrase and replace it with the entered text.
Edit source - opens a resizable dialog where the code can be edited without syntax highlighting or any other advanced functionality.
Indent all - sets the indentation of all code in the editor according to the conventions of the given language.
Insert macro - allows you to add Kentico macro expressions in to the code.
The panel on the right is an alphabetical list of bookmarks that allows users to jump to marked sections in the code. By default, the
bookmarks panel is only displayed when editing CSS stylesheets. You can insert bookmarks using code blocks (regions) following the syntax
of the currently edited language, for example /* #<bookmark name># */ for CSS.

Customizing the syntax highlighting


You can modify how the code editor applies colors and other styles to various syntax tokens of individual languages:
1. Open the ~/CMSAdminControls/CodeMirror/theme folder in your web project
2. Edit the cms.css stylesheet.

Disabling the advanced code editor globally


You can adjust the behavior of all code editors in the administration interface by adding the following keys into the /configuration/appSettings
section of your project's web.config file:
Web.config key

Description

CMSEnableSyntaxHighlighting

Globally enables or disables the code editor


and syntax highlighting support for all code
fields in the user interface. You can disable
the editor if it is causing performance
issues or other problems.
The default value is true.

Sample value

<add
key="CMSEnableSyntax
Highlighting"
value="false" />

CMSEnableSyntaxHighlighting.<Language
>

Allows you to disable the code editor and


syntax highlighting support for fields that
display code in a specific language.
Replace <Language> in the key name with
the name of the language that you wish to
disable. The following language options are
available:
Text
HTML
CSS
JavaScript
XML
CSharp
SQL
HTMLMixed
ASPNET
CMSSharp
All languages are enabled by default.

<add
key="CMSEnableSyntax
Highlighting.CSS"
value="false" />