Kentico 8.2

1. Integrating 3rd party systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.1 Integrating Kentico with other applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.1 Child web application fails to start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.1.2 Running .NET 4.0 child application under a .NET 2.0 or 3.5 parent application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.2 Kentico REST service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.2.1 Configuring the REST service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.2.2 Authenticating REST requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.2.3 Getting data using REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.2.3.1 Examples of data retrieved via the REST service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181.2.3.2 ODATA service documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

1.2.4 Manipulating data using REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211.2.4.1 Managing pages using REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231.2.4.2 Managing objects using REST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

1.2.5 Sending REST requests from code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291.3 Using the integration bus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

1.3.1 Integration bus overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311.3.2 Enabling the integration bus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371.3.3 Creating integration connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

1.3.3.1 Implementing outgoing synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401.3.3.2 Implementing incoming synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

1.3.4 Managing integration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491.3.5 Example - Integration connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501.3.6 Reference - Integration bus data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521.3.7 Integration bus database model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

1.4 Using Kentico API and Controls externally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551.5 Data.com integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

1.5.1 Mapping Data.com fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621.5.2 Searching Data.com for contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631.5.3 Buying contacts from Data.com . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651.5.4 Customizing the Data.com integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

1.6 Salesforce integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671.6.1 Configuring Salesforce integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671.6.2 Replicating contacts to Salesforce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711.6.3 Example - Replicating a contact into a Salesforce lead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721.6.4 Force.com integration API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

1.7 Strands Recommender integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811.7.1 Integrating the Strands Recommender service into your store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 821.7.2 Placing Strands recommendations on a page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 841.7.3 Placing Strands recommendations into emails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871.7.4 Troubleshooting the Strands Recommender integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871.7.5 Customizing how products are categorized in the Strands integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

1.8 Integrating SharePoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 901.8.1 Configuring SharePoint integration connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

1.8.1.1 Connecting to SharePoint Online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921.8.2 Configuring SharePoint integration web part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931.8.3 Configuring SharePoint integration settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961.8.4 Displaying SharePoint data in Kentico . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961.8.5 Example - Displaying a SharePoint picture library in Kentico . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 991.8.6 Managing SharePoint libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

1.8.6.1 Working with files from SharePoint libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1061.8.7 SharePoint integration (obsolete) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

1.8.7.1 SharePoint integration web parts (obsolete) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1081.8.7.2 SharePoint integration examples (obsolete) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1091.8.7.3 Configuring SharePoint integration settings (obsolete) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Integrating 3rd party systemsOut-of-the-box integrations

Integration tools

Integrating Kentico with other applicationsIf you need to combine your Kentico website with an existing application, consider the issues described on this page.

Location of Kentico and your application

You can organize the Kentico web project and your application in the following ways:

Mixing both applications together

If you wish to share functionality, content, security information and session/application variables between Kentico and your application, youcan mix both applications into a single project. The easiest way is to use the Kentico web project as the main application, since it's alreadycorrectly configured. You can add your own assemblies, projects, ASPX pages and other files to the Kentico solution.

If you need to display your own ASPX pages on the actual website, you can register them as and then createASPX page templatesnew pages in the site's content tree based on the templates.If your website is built using the , see: , portal engine Using both ASPX and portal templates on a single site Adding custom code to

.portal engine page templatesTo integrate applications that extend the system's back-end administration interface, you can create .custom modules

Data.com

Keep your contacts and accounts up to date by comparing them with the Data.com business directory.

Salesforce

Automatically replicate contacts coming from your Kentico websites into your organization in SalesForce.

Product recommendations

Offer relevant products to your customers based on conditions that you define. The functionality uses the Strands Recommenderengine.

SharePoint

Display data from a SharePoint server on your website.

REST service

Access and manipulate Kentico data using a RESTful web API.

Integration bus

Synchronize data between Kentico and any other application in real time.

Other integration options

Use the Kentico API and controls externallyCombine the Kentico project with another application

https://docs.kentico.com/display/K82/Developing+websites+using+ASPX+templateshttps://docs.kentico.com/display/K82/Developing+websites+using+the+Portal+enginehttps://docs.kentico.com/display/K82/Using+both+ASPX+and+portal+templates+on+a+single+sitehttps://docs.kentico.com/display/K82/Adding+custom+code+to+portal+engine+page+templateshttps://docs.kentico.com/display/K82/Adding+custom+code+to+portal+engine+page+templateshttps://docs.kentico.com/display/K82/Creating+custom+modules

Using separate nested applications

If your application needs to run independently from Kentico, you can host separate applications in your IIS. There are two possible scenarios:

Kentico manages the main website - place the Kentico web project (CMS folder) into the root of the website and your externalapplication into a sub-directory. You need to create a virtual directory in IIS for the external application.Kentico only provides a sub-section of the website or serves as a content repository - install the Kentico web project into asub-directory under your application.

Sharing security information between Kentico and your application

If you wish to use shared authentication for both your application and Kentico, you need to configure your environment for single.sign-on

To use a single system of permissions (authorization), you can leverage and .permissions custom modules

Child web application fails to startBy default, child web applications inherit the configuration of their parent application. This can prevent the child application from starting whencertain sections of the aren't compatible across applications. For example, if the child application doesn't share the sameweb.configlibraries, handlers, modules, master pages or themes with the parent application. This page describes how you can solve some of thesituations resulting from nesting different applications together.

Breaking web.config inheritance in child applications

Use the tag with the attribute set to to ensure that the configuration applies to the parent weblocation inheritInChildApplications false application only. This can be useful when you don't want to inherit the parent application's settings to the child application. The path attributeset to "." ensures that the location tag covers the default path.

Example

The following example shows how you can break inheritance for , , , , and in yourcontrols namespaces assemblies modules handlersweb.config file. None of the settings enclosed in the tag with set to are inherited by the childlocation inheritInChildApplications falseapplications.

By default, child applications inherit the configuration specified in the parent application's web.config file. This can make them fail tostart. See for more information.Child web application fails to start

Using the location tag break configuration inheritance

https://docs.kentico.com/display/K82/Configuring+single+sign-onhttps://docs.kentico.com/display/K82/Configuring+single+sign-onhttps://docs.kentico.com/display/K82/Configuring+permissionshttps://docs.kentico.com/display/K82/Creating+custom+modules

Specifying different web.config configurations for child applications

By specifying a value for the attribute in the tag, you can apply different configuration settings to specific folders and files. Thispath locationway, you can distribute parent or child application settings through one configuration file.

The default value for the attribute is ".". You can only specify one value in the attribute.path path

Example

The following example shows a configuration that specifies different settings for two specific folders. One of the folders belongs to a parentapplication and the nested folder belongs to a child application:

Using the location tag break configuration inheritance

A different approach to removing inheritance is using the and tags. The tags remove irrelevant modules in the child web application. However, this approach is not supported and implemented the same way across all the elements and itemsin the web.config file.

1. 2.

3.

Running .NET 4.0 child application under a .NET 2.0 or 3.5 parent applicationNOT PUBLISHED

Child .NET applications that are configured to run newer .NET version than their parent applications might fail to start due to compilation andconfiguration errors.

Running the child application fails because the final merged configuration includes the parent configuration as well. You can solve this bymoving the definition in the web.config file of the parent application into the root web.config file for the .NET Framework 2.0.configSections

Example

The following example shows how you can move the configSections of the .NET 2.0 or 3.5 application into the root config file for the .NET 2.0or 3.5 Framework.

Open the parent application's web.config file.Open the root web.config file for the .NET 2.0 and 3.5 Framework, located in:

for .NET 2.0 and 3.5.C:\Windows\Microsoft.NET\Framework\v2.0.50727\CONFIG

Move the element from the parent application into the root application, directly after the initial elemenconfigSections configurationt.

Taken from ... Could cause too much trouble if misconfigured and customers would thenChild web application fails to startprobably contact us. They can google the solution and put it together from MS materials.

Examples of error messages returned by either IIS or the .NET compilation system:The configuration section 'configSections' cannot be read because it is missing a section declaration.The requested page cannot be accessed because the related configuration data for the page is invalid.

If you run a 64-bit operating system or 64-bit application pools, the root web.config file for .NET 2.0 and 3.5 is located in

C:\Windows\Microsoft.NET\Framework64\v2.0.50727\CONFIG

If you run both 32-bit and 64-bit application pools, you have to move the element up configSections into both the rootfiles.

3.

4.

1. 2.

...

Save the web.config files.

Kentico REST serviceREST is an abbreviation of — a style of software architecture designed for distributed systems, typically forRepresentational state transferthe World Wide Web. Kentico has a built-in REST service, which can be used to read, create, update and delete virtually any object or pagewithin the system. These operations are performed by requesting specific URLs. The Kentico REST service is RESTful, which means that itsupports both directions of data transfer (from and into the system).

Kentico also provides the web part, which can be used to display data obtained from the REST service in a simpleGrid for REST servicegrid. You can find an example of this web part on the page on the sample ./Examples/API/REST-service Corporate Site

Configuring the REST serviceREST prerequisites

Before you can enable the Kentico REST service, you must ensure the following:

In Windows

Go to and click in the left menu.Control Panel -> Programs and Features Turn Windows features on or off

Windows 7 / Windows Server 2008

Expand the node in the dialog window.Microsoft .NET Framework Make sure that both of the following features are installed:

Windows Communication Foundation HTTP ActivationWindows Communication Foundation Non-HTTP Activation

Note that you may need to as well.break web.config inheritance for the child application

https://docs.kentico.com/display/K82/Child+web+application+fails+to+start#Childwebapplicationfailstostart-Breakingweb.configinheritanceinchildapplications

1. 2.

1. 2. 3.

4.

5. 6. 7.

Windows 8 / Windows Server 2012

Expand the node..NET Framework 4.5 Advanced ServicesMake sure that the feature is installed.WCF Services -> HTTP Activation

In IIS Manager

Select the website for which you want REST to be enabled.Open the configuration.AuthenticationEnsure that authentication is enabled. You can also have either or authentication enabled if requiredAnonymous Forms Windowsby your environment.Disable and other types of authentication.Basic

Select in the navigation tree.Application PoolsDouble-click the application pool used by your website.Make sure the pool uses Managed pipeline mode.Integrated

7.

1. 2. 3.

4. 5. 6.

Once you have these prerequisites met, you can proceed to configuring the REST service in the Kentico instance.

Configuring the REST service

Once you meet the prerequisites for using the REST service, configure the following settings for the Kentico instance:

Edit your application's file.web.configFind the section directly under the root (i.e. not under a specific element).system.webServer Add the following attribute to the element:

Log in to the Kentico administration interface.Open the application.SettingsSelect the category and configure the settings:Integration -> REST

REST setting Description

Service enabled Enables or disables the Kentico REST service.

Service enabled for Choose if the REST service allows access to objects, pages,or both.

Authentication type Determines which type of the REST serviceauthenticationuses. Supported types are and authentication.Basic Forms

Note: You can authenticate REST requests using the hashquery string parameter in both modes.

Always check page security If disabled, security is not checked when accessing publishedversions of pages. If enabled, security is always checked.

Page access is read only If enabled, the REST service only allows GET requests forpages (pages cannot be modified).

Object access is read only If enabled, the REST service only allows GET requests forobjects (objects cannot be modified).

Allowed page types Specifies a list of that the REST service is allowedpage typesto access. Enter the code names of page types separated bysemicolons.

If empty, all page types are allowed.

Allowed object types Specifies a list of objects types that the REST service isallowed to access. If empty, all object types are allowed.

https://docs.kentico.com/display/K82/Page+types

6.

1.

2.

Generate authentication hash for URL Click the link to generate an hash for specificauthenticationREST URLs.

Enter the full absolute URL of the REST request, including theprotocol, website domain name, virtual directory, ,REST pathand query string . For example:parameters

http://mywebsite.com/rest/content/currentsite/en-us/all/news?format=json

The system adds the authentication hash parameter to theURL. You can copy the URL and use it to perform the RESTrequest without any other type of authentication.

Restrictions:

Only works for GET requests (read only data retrieval)You cannot use hash parameter authentication for obj/allect retrieval requests ( ).~/rest//all

Default encoding Sets the character encoding that the REST service uses forrequests that do not contain a supported headAccept-Charseter.

Allow sensitive fields for administrators If enabled, REST requests authenticated using the credentialsof users with the Global administrator areprivilege levelallowed to work with data fields that contain sensitiveinformation (for example fields related to passwords).

Requests authenticated under non-administrator users canNEVER access sensitive fields, regardless of this setting'svalue.

Enabling upload of large data

If you are planning to upload large-size data into Kentico through the REST service, it is necessary to specify the required data size limit inthe application's file. This can be done by adding the following pieces of code into the section at the endweb.config of the web.config file:

Insert a element into the sub-section:

Add a element under the sub-section:

Note: This sample sets all limits to 10 MB. You may need to enter different values according to your specific needs.

https://docs.kentico.com/display/K82/User+management

2.

1.

2.

The in the code above only contains a sample value and needs to be replaced with the actual root address of thebaseAddressREST service (depending on your website's domain name).

Authenticating REST requestsEvery REST request needs to be authenticated. You can select the of the REST service in Authentication type Settings -> Integration ->

.REST

Basic authentication

With Basic authentication, you need to specify the username and password through the line in the header of every RESTAuthorizationrequest. The header line consists of:

The authentication type ( )BasicThe username and password connected by a colon ( ), encoded using the Base64 algorithmusername:password

For example, the following header line uses as the authentication credentials:RestClient:MyPassword

Authorization: Basic UmVzdENsaWVudDpNeVBhc3N3b3Jk

Once authenticated, the system allows the REST request to perform operations depending on the specified user's and privilege level permiss.ions

Forms authentication

When using of requests, the system identifies users based on the active session and the authentication ticket stored informs authenticationthe .ASPXFORMSAUTH cookie. You can use forms authentication to create a web interface with a login page, and allow users to sendREST requests through their browser.

You cannot use forms authentication for the Kentico REST service if you have enabled in IIS.Windows authentication

Forms authentication can pose a security threat, because logged in users may unknowingly click links that send malicious REST requests toyour site. To protect yourself from such attacks, take the following steps:

Immediately after creating the session (i.e. first authentication), set up an by sending a POST request to theauthentication tokenfollowing URL:

https:///rest/settoken?username=&password=&token=

The authentication token can be an arbitrary string of characters, for example a GUID.

Include the authentication token in the HTTP header of every REST request:

Cms-Session-Token:

Hash parameter authentication

You can authenticate individual REST requests by adding a hash parameter to the URL. The hash parameter allows you to prepare RESTrequests that can be executed by unauthenticated users. Requests that contain the hash parameter ignore the other types of authentication— the value of the setting does not affect hash authentication.Authentication type

Important: We strongly recommend using to protect the authentication credentials in the request headers. See also: SSL Configuring SSL

Note: The type of the Kentico REST service does not require Basic Authentication to be enabled in IIS. KeepBasic authenticationBasic Authentication disabled in IIS as described in .Configuring the REST service

Restrictions

Only works for GET requests (read only data retrieval)You cannot use hash parameter authentication for ( ). This is an/all object retrieval requests ~/rest//allintentional security limitation that protects global data in the system.

https://docs.kentico.com/display/K82/User+managementhttps://docs.kentico.com/display/K82/Configuring+permissionshttps://docs.kentico.com/display/K82/Configuring+permissionshttp://msdn.microsoft.com/en-us/library/7t6b43z4%28v=vs.100%29.aspxhttp://en.wikipedia.org/wiki/Transport_Layer_Securityhttps://docs.kentico.com/display/K82/Configuring+SSLhttps://docs.kentico.com/display/K82/Configuring+SSL

1. 2. 3. 4. 5.

6.

To get the authentication hash for REST requests:

Prepare the URL of your REST request in advance.Open the application.SettingsSelect the category.Integration -> RESTClick .Generate authentication hashEnter the full absolute URL of the REST request, including the protocol, website domain name, virtual directory, , andREST pathquery string . For example: parameters http://mywebsite.com/rest/content/currentsite/en-us/all/news?format=jsonClick .Authenticate

The system adds the authentication hash parameter to the URL. You can copy the URL and use it to perform the REST request without anyother type of authentication.

Getting data using RESTThe REST service allows you to retrieve page and object data from Kentico instances.

Send requests using the to a URL in format: GET HTTP method /

The base URL of the Kentico REST service is . For example, if your site is running at use /rest ,http://localhost/Kenticoas the base URL of the service. To learn about the available for pages and objects, see the http://localhost/Kentico/rest resource paths

tables in the sections below. The requests return data in either XML, JSON, RSS or Atom format (see Examples of data retrieved via the for more information).REST service

Character encoding

Data retrieval requests return the results in the server's default character encoding. To get the results in a different encoding type, set theencoding in the field of the GET request's HTTP header. If the specified encoding is not available, the system uses the Accept-Charset Defa

configured in .ult encoding Settings -> Integration -> Rest

GET http://localhost/Kentico/rest/cms.user/administrator HTTP/1.1Authorization: Basic UmVzdENsaWVudDpNeVBhc3N3b3JkAccept-Charset: utf-8Content-Type: text\xml

Getting page data

To load the data of pages from Kentico websites, send GET requests to the appropriate URL — append the described resource pathsbelow to the base URL of your REST service.

Resource format and example Description

Single page

/content/currentsite//document/ /content/currentsite/en-us/document/company/careers______________________________________________________

A single page in the given culture from the site running on thedomain in the base URL.

Identify the page using its .alias path

/content/site///document/ /content/site/corporatesite/en-us/document/company/careers_

A single page in the given culture on the specified site.

Multiple pages

Warning: Only use hash parameter authentication for loading data that you want to make publicly available. REST requests withhash authentication can be executed by anyone who obtains the URL (for example by intercepting the web request).

REST base URL

Sending a GET request to the base URL of the REST service exposes the service document (for ODATA browsing). Thedocument contains a list of all available primary object types (without child and binding object types) and the URLs under which theobjects can be accessed. See also: ODATA service documents

Example

You can further configure the data retrieval by adding to the URL.query string parameters

http://en.wikipedia.org/wiki/HTTP#Request_methodshttps://docs.kentico.com/display/K82/Setting+page+aliases

/content/currentsite//all/ /content/currentsite/en-us/all/news

/content/site///all/ /content/site/corporatesite/en-us/all/news_

All pages starting with the specified .alias path

/content/currentsite//childrenof/ /content/currentsite/en-us/childrenof/news

/content/site///childrenof/ /content/site/corporatesite/en-us/childrenof/news_

All child pages under the specified parent page. Does not includethe parent page itself.

Getting object data

To load the data of objects from Kentico, send GET requests to the appropriate URL — append the described below to the resource pathsbase URL of your REST service.

Most object resources start with an name. To find the value for specific object types, view the of classes in the object type Code name Modul application, or the column of the database table.es ClassName CMS_Class

Resource format and example Description

Multiple objects

/ /cms.country_

All objects of the given type assigned to the site running on thedomain in the base URL.

If the object type does not use site bindings, returns all objects ofthe given type.

//site//cms.country/site/corporatesite_

All objects of the given type assigned to the specified site.

If the object type does not use site bindings, returns all objects ofthe given type.

//global /cms.emailtemplate/global_

All global objects of the given type (objects not assigned to anysite).

If the object type does not use site bindings, returns all objects ofthe given type.

//all /cms.emailtemplate/all_________________________________________________________

All objects of the given type (site-related objects from all sites andglobal objects).

Note:

/all object retrieval requests only work if the user account usedfor has the .authentication Global administrator privilege levelThe REST service does not allow object retrieval for/allrequests that use the URL parameter for . hash authentication

These are intentional security limitations that protect global data.

Single object

///cms.country/271/cms.country/e431b7e6-9e6c-409d-a1d9-748cbf51b5d6_

Object of the given type with the specified identifier (ID or GUIDvalue).

Ignores site bindings – object IDs and GUIDs are unique across allsites in the system.

Culture constants

You can use the following constants instead of culture codes in page REST calls:

defaultculture - the page version in the site's default cultureallcultures - page versions in all available cultures

Example: /content/currentsite/defaultculture/document/company/careers

You can further configure the data retrieval by adding to the URL.query string parameters

https://docs.kentico.com/display/K82/Setting+page+aliaseshttps://docs.kentico.com/display/K82/User+management

// /cms.country/usa_

Object of the given type with the specified code name.

For object types with site bindings, always returns the objectassigned to the site running on the domain in the base URL.

//site// /cms.emailtemplate/site/corporatesite/Blog.NotificationToModerators_

Object of the given type with the specified code name, assigned tothe specified site.

//global/ /cms.emailtemplate/global/Blog.NotificationToModerators_

Global object of the given type with the specified code name.

Child objects

///children/cms.country/271/children_

All that are supported as child types for the specifiedobject typesobject. Only ID values can be used to identify the parent object.

///children//cms.country/271/children/cms.state_

All objects of the given type that are children of the specified parentobject. Only ID values can be used to identify the parent object.

Binding objects

///bindings /cms.user/53/bindings_

All that are used as binding types (representobject typesrelationships with other objects) for the specified object. Only IDvalues can be used to identify the object.

///bindings/ /cms.user/53/bindings/cms.usersite_

All objects of the given binding type that exist for the specifiedobject. Only ID values can be used to identify the object.

Custom tables

/cms.customtable//cms.customtable/customtable.sampletable_

The class definition of the specified (includes datacustom tablesuch as the custom table's names, field definitions and searchsettings).

/customtableitem. /customtableitem.customtable.sampletable_

The data records stored in the specified custom table.

Forms

/cms.form//cms.form/contactus_

The class definition of the specified (includes data such as theformform's names, basic settings and field definitions).

/bizformitem.bizform. /bizformitem.bizform.contactus_

The data records stored for the specified form.

Other

//site /cms.country/site_

Lists all sites on which the specified object type is available andprovides the REST URLs under which the object data can beretrieved for individual sites (for ODATA browsing).

/typeinfo/ /typeinfo/cms.user_

The data for the specified object type. The TypeInfo is aTypeInfoset of properties that define the general behavior and basicproperties of object types (classes) in Kentico.

/macro//macro/CurrentSite.SiteName

Evaluates the given and serializes the result.macro expressionOnly works for macros that return a serializable result.

When creating the macro expression:

Do NOT add the encapsulating bracket charactersUse URL encoding for forbidden URL characters

Data loading parameters

When loading data via REST, you can append the following query string parameters to the request URL:

Parameter Value (default bold) Description

https://docs.kentico.com/display/K82/Custom+tableshttps://docs.kentico.com/display/K82/Formshttps://docs.kentico.com/display/K82/Macro+expressions

General

format xml/json/atom10/rss20 Sets the format of the retrieved data. Forexample, append to the?format=jsonrequest URL to get data in JSON format.

See also: Examples of data retrieved viathe REST service

localize______________________

culture code__________________________

If added, the system resolves all localizatio inside the returned data.n expressions

Without this parameter, requests alwaysreturn localization expressions inunresolved format. Supported by both pageand object retrieval requests.

Specify the target language by entering thecorresponding into theculture codeparameter's value. You can find theavailable culture codes in the Localizationapplication on the tab.Cultures

For example, append to the?localize=fr-frrequest URL to resolve all localizationexpressions into their French value (or thevalue in the default if theUI cultureexpression is not defined in French).

hash hash string Allows you to the requestauthenticatewithout requiring an authentication headeror Forms authentication.

See to learnAuthenticating REST requestshow to generate the hash value.

Pages

classnames page type code name ( )all Limits which the requestpage typesreturns. Specified as a list of page typecode names separated by semicolons.

For example, to retrieve only pacms.articleges, append to?classnames=cms.articlethe request URL.

coupleddata true/false Determines if the request retrieves datastored in the fields of specific page types(coupled data).

To load pages without coupled data,append to the request?coupleddata=falseURL.

combinewithdefaultculture true/false Indicates if the request loads the defaultlanguage versions of pages if they do notexist in the specified culture.

To load the default language versions ofpages, append ?combinewithdefaultculture

to the request URL.=true

selectonlypublished true/false Determines if the request loads only pagesthat are published on the live site.

To also retrieve unpublished pages ,append to the?selectonlypublished=falserequest URL.

version published/last Determines if the request returns the pageversions that are published on the live siteor the latest version that is being edited inthe application (when using Pages Workflo

).w

To load the latest page versions, append ?v to the request URL.ersion=last

Multiple pages or objects

https://docs.kentico.com/display/K82/Working+with+resource+stringshttps://docs.kentico.com/display/K82/Working+with+resource+stringshttps://docs.kentico.com/display/K82/Page+typeshttps://docs.kentico.com/display/K82/Configuring+workflowshttps://docs.kentico.com/display/K82/Configuring+workflows

where SQL code ( )empty SQL WHERE condition for filtering theloaded data. The parameter only allows thefollowing types of SQL syntax:

column names, values and basicoperators: =, !=, >, <AND & OR operators, parenthesescolumn BETWEEN AND value valuecolumn LIKE valuecolumn IN (values)column IS NULLNOT keyword for the aboveexpressions (NOT BETWEEN, NOTLIKE, NOT IN, IS NOT NULL)

Other expressions and SQL functions arenot supported.

Example: ~/rest/cms.user?Where=UserIsEditor=1

orderby SQL code ( )empty SQL ORDER BY clause for modifying theorder of the items in the data. Theparameter allows the following values:

one or more column names (separatedby commas)the ASC and DESC keywords

Other SQL expressions and functions arenot supported.

Append to use?orderby=##default##alphabetical order based on the objectdisplay name.

columns column names ( )all columns Limits which data columns of the object orpage are loaded.

For example, to load only the anUserNamed columns when retrieving users,UserIDappend to?columns=UserName,UserIDthe request URL.

If you add the parameter, the columns binar parameter is ignored (you can choosey

whether to include binary columns byenumerating the corresponding columns).

topn integer ( )all records SQL TOP N clause for filtering the loadeddata.

For example, to load only the first 10records, append to the request?topn=10URL.

Multiple objects

offset integer ( )first record Sets the number of the first record that therequest returns (according to the order ofthe data). Allows you to implement pagingof the data.

For example, to load data starting from thethird item in the dataset, append t?offset=2o the request URL.

maxrecords integer ( )all records Limits the maximum number of retrievedrecords. You can use the paramaxrecordsmeter in combination with the parameoffsetter to retrieve a specific range of records.

For example, to load items 11–20 from thedata, append t?offset=10&maxrecords=10o the request URL.

Objects

objectdata true/false Indicates whether the request retrieves thedata fields of objects.

To load only the metadata of an object,append t?objectdata=false&metadata=trueo the request URL.

metadata true/false Determines if the request retrieves themetadata of objects (type, list of properties /columns).

To load the metadata, append ?metadata=t to the request URL.rue

binary true/false Indicates whether the request retrievesbinary data (e.g. the data of files uploadedinto form fields). Binary data is retrieved in

format.Base64

To include the binary data in the response,append to the request URL.?binary=true

children true/false Indicates whether the result includes childobjects.

To load child objects, append ?children=tru to the request URL.e

maxrelativelevel integer ( )all levels If the parameter is true, thischildrenparameters sets the maximum depth of theexported object tree structure.

For example, to load all child objects downto the second level of the object tree,append ?children=true&maxrelativelevel=2to the request URL.

bindings true/false Determines if the retrieved data includesbindings to child objects and sites.Requests only return bindings if the objectd

parameter is true.ata

To load object data with its bindings,append to the request URL.?bindings=true

otherbindings true/false Determines if the retrieved data includesbindings to other objects (M:Nrelationships). Requests only returnbindings if the parameter is true.objectdata

To load object data with bindings to otherobjects, append to the?otherbindings=truerequest URL.

metafiles true/false Determines if the retrieved data includesmetafiles attached to the object

To load metafiles, append t?metafiles=trueo the request URL.

relationships true/false Determines if the retrieved data includesobject relationships.

To load relationships, append ?relationship to the request URL.s=true

categories true/false Determines if the retrieved data includesthe object's category structure (if the objectis stored in a hierarchical categorystructure).

To load the category structure, append ?cat to the request URL.egories=true

translations true/false Indicates whether the result includes atranslation table of foreign keys.

To load the translation table, append ?trans to the request URL.lations=true

hierarchy true/false If true, the response data is exported in ahierarchical structure (if false, the children –bindings – parent structure is flat).

To export the data in a hierarchicalstructure, append to the?hierarchy=truerequest URL.

Examples of data retrieved via the REST serviceThis page shows examples of data (all objects) obtained from the REST service in various formats.cms.country

XML

All objects retrieved in format.cms.country XML

The data was obtained using the following URL: ~/rest/cms.country

JSON

The code below is an extract from data of the objects retrieved in format.cms.country JSON

The data was obtained using the following URL: ~/rest/cms.country?format=json

http://en.wikipedia.org/wiki/XMLhttp://en.wikipedia.org/wiki/JSON

{"cms_countries":[{"cms_country":[{"CountryDisplayName":"Afghanistan","CountryID":272,"CountryLastModified":"\/Date(1299419802000)\/","CountryName":"Afghanistan","CountryGUID":"12d61676-7541-4a4e-88f6-f02098b637fe"},{"CountryDisplayName":"Albania","CountryID":273,"CountryLastModified":"\/Date(1202723603000)\/","CountryName":"Albania","CountryGUID":"af056090-4477-4826-ad41-7ce8e8d45d3a"},{"CountryDisplayName":"Algeria","CountryID":274,"CountryLastModified":"\/Date(1205397300000)\/","CountryName":"Algeria","CountryGUID":"59f8718f-ff33-4376-bb18-c0d5b0d96786"},{"CountryDisplayName":"American Samoa","CountryID":275,"CountryLastModified":"\/Date(1205397300000)\/","CountryName":"AmericanSamoa","CountryGUID":"8a89a7b3-11ee-4cef-9770-22a88bc5e5d6"},{"CountryDisplayName":"Andorra","CountryID":276,"CountryLastModified":"\/Date(1205397300000)\/","CountryName":"Andorra","CountryGUID":"cbba23bb-43d5-4840-a797-a9e27f6018f4"},{"CountryDisplayName":"Angola","CountryID":277,"CountryLastModified":"\/Date(1314631085000)\/","CountryName":"Angola","CountryGUID":"503673e4-fc0e-40a3-9ff9-521f67680d3f"},{"CountryDisplayName":"Anguilla","CountryID":278,"CountryLastModified":"\/Date(1205397300000)\/","CountryName":"Anguilla","CountryGUID":"fe1c087d-6157-4f94-9745-39a49f981bfa"} ... ]},{"TotalRecords":[{"TotalRecords":"246"}]}]}

RSS 2.0

All objects retrieved in format.cms.country RSS 2.0

The data was obtained using the following URL: ~/rest/cms.country?format=rss20

http://en.wikipedia.org/wiki/RSS

Atom 1.0

All objects retrieved in format.cms.country Atom 1.0

The data was obtained using the following URL: ~/rest/cms.country?format=atom10

ODATA service documentsThe Kentico REST service supports by providing service documents in a standard format for ODATA services. The serviceODATAdocuments provide information about the types of data available via the REST service and about the URLs under which the data can beaccessed.

The service documents are available under the following URLs:

~/rest - exposes the service document. The document contains a list of all available primary object types (without child and bindingobject types) and the URLs under which the objects can be accessed.

http://en.wikipedia.org/wiki/Atom_%28standard%29http://www.odata.org/home

~/rest//site - lists all sites on which the specified object type is available and provides the REST URLs under whichthe object data can be retrieved for individual sites.

Manipulating data using RESTThe REST service allows you to manipulate the data of pages and objects on Kentico instances.

Send requests using the , or to the appropriate URL. See the following documentation pages for details:POST PUT DELETE HTTP method

Managing pages using RESTManaging objects using REST

General data manipulation parameters

When managing pages or objects via REST, you can append the following query string parameters to the request URL:

Parameter Value (default bold) Description

format xml/json Sets the format of the data submitted inPOST/PUT requests. For example, append

to the request URL to submit?format=jsondata in JSON format.

hash hash string___________________

Allows you to the requestauthenticatewithout requiring an authentication headeror Forms authentication.

See to learnAuthenticating REST requestshow to generate the hash value.

Setting fields to empty values

If you need to set a page or object field to an empty value using a REST request, use the following expression instead of an actual value:

Data validation

When inserting or updating data via the REST service, Kentico does not perform any validation. You need to ensure validation onthe side of the application sending the REST requests to prevent unwanted behavior.

http://en.wikipedia.org/wiki/HTTP#Request_methods

1.

2. 3.

##null## (for data in XML format)null (for data in JSON format)

The null expression is particularly useful for non-string fields (typically fields storing foreign key IDs), where an empty string value would notproduce the desired results.

For example, the following request updates the page of the sample Corporate Site and ensures that it does not have a user specifiedHomein the field:Created by

HTTP method: PUTURL: ~/rest/content/site/corporatesite/en-us/document/HomeData (XML format):

##null##

Uploading attachment files

When uploading files via the REST service, use the following format for the binary data:

base 64 encoding in requests using the XML data formatbyte array values in requests using the JSON data format (you can get the appropriate byte array by serializing your data via the Sy

method)stem.Web.Script.Serialization.JavaScriptSerializer.Serialize

Carefully consider the data type of the target field. Most page and object fields in Kentico do not store binary data directly, but instead containthe GUID of the corresponding attachment object. To find information about the requirements for your scenario, for ansend a GET requestexisting object of the given type and check the resulting data.

For example, use the following steps to create a new page, including an image file as an attachment:CMS.File

Send a request to create the attachment file itself ( object type, base64 encoding for the file binary in the cms.attachment Attachme field):ntBinary

HTTP method: POSTURL: ~/rest/cms.attachment/currentsiteData (XML format):

NewAttachmentFile.png .png 3180 image/x-png 183 47 15

Store the value from the data of the response to the POST request that created the attachment.AttachmentGuidCreate the CMS.File page (set the field to the GUID of the new attachment object):FileAttachment

HTTP method: POSTURL: ~/rest/content/currentsite/en-us/document/ImagesData (XML format):

Note: To upload binary data using requests in the JSON format, you need to apply or newer.hotfix 8.1.1

http://msdn.microsoft.com/en-us/library/bb292287%28v=vs.110%29.aspxhttp://msdn.microsoft.com/en-us/library/bb292287%28v=vs.110%29.aspxhttp://devnet.kentico.com/download/hotfixes

3.

1685 .png .png NewAttachmentFile 96d6dfc9-4f3a-4a30-95af-4d7cc5a36f9a

Managing pages using RESTThe REST service allows you to manipulate the data of pages on Kentico websites. Send requests using the , orPOST PUT DELETE HTTP

to the appropriate URL — append the described below to the of your REST service.method resource paths base URL

The base URL of the Kentico REST service is . For example, if your site is running at use /rest ,http://localhost/Kenticoas the base URL of the service. http://localhost/Kentico/rest

Creating pages

HTTP method: POST

Resource format:

/content/currentsite//document/ - creates a new page in the given culture for the site running on the domainin the base URL./content/site///document/ - creates a new page in the given culture on the specified site.

Use the to identify the under which you want to create the new page.alias path parent page

Set the name and other fields of the new page in the data of the POST request. Both and formats are supported for the data.XML JSON

Examples

Creates a page (CMS.MenuItem type) under the page New service Services

XML JSON

To learn more about working with pages, see .Managing pages using REST

Important:

When creating new pages, always set the field. To find the value for a page type, NodeClassID NodeClassID get a page using the REST service and check the data or view the column in the databaseof the given type ClassID CMS_Class

table.The request data must contain values for for the given .all fields that are set as required page typeThe service automatically sets the system fields of the new page (such as the ID and timestamp fields).Creating multiple pages in a single request is not supported. You need to send a separate POST request for each page.

Creating language versions of pages

You can use POST requests to create new of existing pages:language versions

Use the culture code in the resource path to set the desired language.Identify the page using the .alias pathSpecify the of the existing page in the request data. Do NOT manually set a for the new languageNodeID DocumentIDversion.Set any other required data for the page language version.

http://en.wikipedia.org/wiki/HTTP#Request_methodshttp://en.wikipedia.org/wiki/HTTP#Request_methodshttps://docs.kentico.com/display/K82/Setting+page+aliaseshttp://en.wikipedia.org/wiki/XMLhttp://en.wikipedia.org/wiki/JSONhttps://docs.kentico.com/display/K82/Page+typeshttps://docs.kentico.com/display/K82/Editing+the+content+of+multilingual+websiteshttps://docs.kentico.com/display/K82/Setting+page+aliases

URL: ~/rest/content/currentsite/en-us/document/Services

Data:

4114 Newservice 23438

URL: ~/rest/content/currentsite/en-us/document/Services?format=json

Data:

{"NodeClassID":4114,"DocumentName":"New service","DocumentPageTemplateID":23438}

Creates a page (CMS.News type) under the pageNews article News

XML JSON

URL: ~/rest/content/currentsite/en-us/document/News

Data:

4112 Newsarticle 2014-06-05T00:00:00+02:00 Summary Text

URL: ~/rest/content/currentsite/en-us/document/News?format=json

Data:

{"NodeClassID":4112,"NewsTitle":"News article","NewsReleaseDate":"2014-06-05T00:00:00Z","NewsSummary":"Summary","NewsText":"Text"}

Creates a version of the existing page on the sample Corporate siteFrench Services

XML JSON

URL: ~/rest/content/site/CorporateSite/fr-fr/document/Services

Data:

5 FrenchServices

URL: ~/rest/content/site/CorporateSite/fr-fr/document/Services?format=json

Data:

{"NodeID":5,"DocumentName":"French Services"}

Updating existing pages

HTTP method: PUT

Updating page data

Resource format:

/content/currentsite//document/ - updates the data of an existing page on the site running on the domain inthe base URL./content/site///document/ - updates the data of an existing page on the specified site.

Use the to identify the page that you want to update. Updating multiple pages in a single request is not supported. You need toalias path

https://docs.kentico.com/display/K82/Setting+page+aliases

send a separate PUT request for each page.

Update the values of the page's fields using the data of the PUT request. Both and formats are supported for the data.XML JSON

Examples:

Updates the name of the page on the sample Corporate siteServices

XML JSON

URL: ~/rest/content/site/CorporateSite/en-us/document/Services

Data:

ServicesMODIFIED ServicesMODIFIED

URL: ?f~/rest/content/site/CorporateSite/en-us/document/Servicesormat=json

Data:

{"DocumentName":"Services MODIFIED","MenuItemName":"Services MODIFIED"}

Updates the title, release date and summary of a news article on the sample Corporate site

XML JSON

URL: ~/rest/content/site/CorporateSite/en-us/document/News/New-Consulting-Services

Data:

Consultingavailable Consultingavailable 2014-07-04T00:00:00+02:00 Updatedsummary

URL: ~/rest/content/site/CorporateSite/en-us/document/News/New-?format=jsonConsulting-Services

Data:

{"DocumentName":"Consultingavailable","NewsTitle":"Consulting available","NewsReleaseDate":"2014-07-04T00:00:00Z","NewsSummary":"Updated summary"}

Workflow actions

You can also use PUT requests to move pages through the life cycle, or check pages in and out when using .workflow content locking

Resource format:

/content/currentsite/// - performs the given workflow action for the specified page on thesite running on the domain in the base URL./content/site//// - performs the given workflow action for the given page onthe specified site.

Workflow action Description

publish Publishes the page.

Updating page names

Many have a unique field that serves as the source for the page name (instead of the default field).page types DocumentNameWhen updating the names of such page types, always set the new value for both the field and the dedicatedDocumentNamepage type name field to ensure consistency.

http://en.wikipedia.org/wiki/XMLhttp://en.wikipedia.org/wiki/JSONhttps://docs.kentico.com/display/K82/Configuring+workflowshttps://docs.kentico.com/display/K82/Content+lockinghttps://docs.kentico.com/display/K82/Page+types

checkout Performs check-out for the page. The page is checked out underthe user account specified by the REST request's infauthenticationormation.

checkin Performs check-in for the page.

archive Archives the page.

movetonextstep Moves the page to the next workflow step.

movetopreviousstep Moves the page to the previous workflow step.

Use the to identify the page for which you want to perform the workflow action. Do not submit any data when sending workflowalias pathaction requests.

URL example: ~/rest/content/currentsite/en-us/checkout/Home

Deleting pages

HTTP method: DELETE

Resource format:

/content/currentsite//document/ - deletes the given of the page for the site running on thelanguage versiondomain in the base URL./content/site///document/ - deletes the given language version of the page on the specifiedsite.

Use the to identify the page that you want to delete. Deleting multiple pages in a single request is not supported. You need to sendalias patha separate DELETE request for each page.

Page deletion parameters

When deleting pages via REST, you can append the following query string parameters to the request URL:

Parameter Value (default bold) Description

deleteallcultures true/false Indicates if the request also deletes all lang of the specified page.uage versions

To delete all language versions of a page,append to the?deleteallcultures=truerequest URL.

destroyhistory true/false Indicates if the request also deletes thepage's .version history

To delete the version history together withthe page, append to?destroyhistory=truethe request URL.

Managing objects using RESTTo manage objects in Kentico using the REST service, send requests using the POST, PUT or DELETE to the appropriateHTTP methodURL — append the described below to the of your REST service. resource paths base URL

The base URL of the REST service is . For example, if your site is running at use /rest ,http://localhost/Kentico http://locas the base URL of the service. alhost/Kentico/rest

Object resource paths start with an name. To find the value for specific object types, view the of classes in the object type Code name Modu application, or the column of the database table.les ClassName CMS_Class

Creating objects

HTTP method: POST

Resource format:

/ - creates a new object of the specified type.//currentsite - creates a new object of the specified type and assigns it to the website running on the domain in thebase URL.

Important: Do NOT use object requests to create, update or delete the pages of Kentico websites. See Managing pages using for information about working with pages.REST

https://docs.kentico.com/display/K82/Setting+page+aliaseshttps://docs.kentico.com/display/K82/Editing+the+content+of+multilingual+websiteshttps://docs.kentico.com/display/K82/Setting+page+aliaseshttps://docs.kentico.com/display/K82/Editing+the+content+of+multilingual+websiteshttps://docs.kentico.com/display/K82/Editing+the+content+of+multilingual+websiteshttps://docs.kentico.com/display/K82/Configuring+and+using+page+versioninghttp://en.wikipedia.org/wiki/HTTP#Request_methods

//site/ - creates a new object of the specified type and assigns it to the specified website./customtableitem. - creates a new data record inside the specified . custom table/bizformitem.bizform. - creates a new data record inside the specified .form

Set the name and other fields of the new object in the data of the POST request. Both and formats are supported for the data.XML JSON

Examples

Creates a new user with the Editor privilege level and an empty password. Assigns the user to the site running on the domain inthe base URL.

XML JSON

URL: ~/rest/cms.user/currentsite

Data:

Editor Contenteditor editor@localhost.local true true

URL: ~/rest/cms.user/currentsite?format=json

Data:

{"UserName":"Editor","FullName":"Content editor","Email":"editor@localhost.local","UserEnabled":true,"UserIsEditor":true}

Creates a new object with a child statecountry

XML JSON

URL: ~/rest/cms.country

Data:

Newcountry NewCountry Newstate NewState NS

URL: ~/rest/cms.country?format=json

Data:

{"CountryDisplayName":"New country","CountryName":"NewCountry","CMS.State": [{ "StateDisplayName":"New state", "StateName":"NewState", "StateCode":"NS" }]}

Creates a for the page of the sample Corporate sitepage alias Home

XML JSON

Important:

The service automatically sets the system fields of the new object (such as the ID and timestamp fields).Creating multiple objects of the same type in a single request is not supported.You can create child or binding objects along with the primary object. When using the XML format for the data of suchrequests, enclose the data into the element to ensure valid syntax with a single root element.

https://docs.kentico.com/display/K82/Custom+tableshttps://docs.kentico.com/display/K82/Formshttp://en.wikipedia.org/wiki/XMLhttp://en.wikipedia.org/wiki/JSONhttps://docs.kentico.com/display/K82/Setting+page+aliases

URL: ~/rest/cms.documentalias/site/corporatesite

Data:

4 /HomeAlias

URL: ~/rest/ ?format=jsoncms.documentalias/site/corporatesite

Data:

{"AliasNodeID":4,"AliasURLPath":"/HomeAlias"}

Adds a new data record into the custom tableSample table

XML JSON

URL: ~/rest/customtableitem.customtable.sampletable

Data:

Record added viaREST

URL: ?format=jso~/rest/customtableitem.customtable.sampletablen

Data:

{"ItemText":"Record added viaREST"}

Updating existing objects

HTTP method: PUT

Resource format:

// - updates the object with the specified identifier (ID or GUID value). // - updates the object with the specified code name. For object types with site bindings, always updatesthe object assigned to the site running on the domain in the base URL.//site// - updates the object with the specified code name on the specified website.//global/ - updates the global object with the specified code name./customtableitem./ - updates the data record with the specified identifier (ID or GUIDvalue) inside the given . custom table/bizformitem.bizform./ - updates the data record with the specified identifier (ID or GUIDvalue) inside the given .form

Update the values of the object's fields using the data of the PUT request. Both and formats are supported for the data. UpdatingXML JSONmultiple objects in a single request is not supported.

Examples

Updates the email address of the useradministrator

XML JSON

URL: ~/rest/cms.user/administrator

Data:

newAddress@localhost.local

URL: ~/rest/cms.user/administrator?format=json

Data:

{"Email":"newAddress@localhost.local"}

Updates a data record of the sample formContact us

XML JSON

https://docs.kentico.com/display/K82/Custom+tableshttps://docs.kentico.com/display/K82/Formshttp://en.wikipedia.org/wiki/XMLhttp://en.wikipedia.org/wiki/JSON

URL: ~/rest/bizformitem.bizform.contactus/1

Data:

newMail@localhost.local Updatedmessage

URL: ?format=json~/rest/bizformitem.bizform.contactus/1

Data:

{ "Email":"newMail@localhost.local", "Message":"Updated message"}

Deleting objects

HTTP method: DELETE

Resource format:

// - deletes the object with the specified identifier (ID or GUID value).// - deletes the object with the specified code name. For object types with site bindings, always deletesthe object assigned to the site running on the domain in the base URL.//site// - deletes the object with the specified code name from the specified website.//global/ - deletes the global object with the specified code name./customtableitem./ - deletes the data record with the specified identifier (ID or GUIDvalue) from the given .custom table/bizformitem.bizform./ - deletes the data record the specified identifier (ID or GUID value)from the given .form

URL examples:

~/rest/cms.user/53~/rest/cms.country/usa~/rest/cms.country/e431b7e6-9e6c-409d-a1d9-748cbf51b5d6 ~/rest/cms.emailtemplate/site/corporatesite/Blog.NotificationToModerators~/rest/customtableitem.customtable.SampleTable/5

Deleting multiple objects in a single request is not supported. You need to send a separate DELETE request for each object.

Sending REST requests from codeBy sending requests to the , you can from the system or .Kentico REST service get data manipulate pages and objects

The following example demonstrates how to send REST requests using server-side code. The sample code is incomplete — you need toperform the following according to your requirements:

integrate the request sending into your custom logic or applicationsupply the required values (HTTP method, request URL and data)process the response dataensure exception handling

https://docs.kentico.com/display/K82/Custom+tableshttps://docs.kentico.com/display/K82/Forms

using System;using System.Web;using System.Net;using System.IO;using System.Text;

...

string httpMethod; // "GET", "POST", "PUT" or "DELETE"string requestUrl; // The URL of the REST request (base URL + resource path)string requestData; // Data for POST or PUT requests

string responseDescription; // Stores the description of the response statusstring responseData; // Stores data retrieved by the request

// Creates the REST requestHttpWebRequest request = (HttpWebRequest)WebRequest.Create(requestUrl);

// Sets the HTTP method of the requestrequest.Method = httpMethod;

// Authorizes the request using Basic authenticationrequest.Headers.Add("Authorization: Basic YWRtaW5pc3RyYXRvcjo=");

// Submits data for POST or PUT requestsif (request.Method == "POST" || request.Method == "PUT"){ request.ContentType = "text/xml";

Byte[] bytes = Encoding.GetEncoding("utf-8").GetBytes(requestData); request.ContentLength = bytes.Length;

using (Stream writeStream = request.GetRequestStream()) { writeStream.Write(bytes, 0, bytes.Length); }}

// Gets the REST responseHttpWebResponse response = (HttpWebResponse)request.GetResponse();

// Stores the description of the response statusresponseDescription = (Int32)response.StatusCode + " - " +response.StatusDescription;

// Gets the response datausing (Stream responseStream = response.GetResponseStream()){ if (responseStream != null) using (StreamReader reader = new StreamReader(responseStream)) { responseData = HttpUtility.HtmlEncode(reader.ReadToEnd()); }}

...

C# example

Using the integration busThe integration bus allows developers to connect Kentico with third party systems, such as CRMs or ERPs. The purpose of the integration isto synchronize objects and pages (in both directions). The data exchange is ensured by . Each connector is a standard .NETconnectorsclass that needs to be implemented by a developer.

Information

Connecting Kentico with third party systems:

Integration bus overviewThe integration bus synchronizes objects and pages with third party systems. It provides a safer and more reliable way than other solutions,because the synchronization tasks can be ordered in a queue and recovered if they fail. You can realize the synchronization in bothdirections:

Outgoing tasks – perform synchronization from Kentico to external applications.Incoming tasks – perform synchronization from external systems to Kentico.

Outgoing tasks - From Kentico to external applications

Outgoing synchronization tasks are based on .subscriptions

Subscriptions

Subscriptions keep track of operations performed in Kentico, such as creating, updating or deleting objects and pages. Developers need toprepare subscriptions for operations that should be synchronized to external systems. When an operation that has a subscription occurs, thesystem passes the request to a connector, which processes the synchronization in one of two modes (depends on the subscription settings):

Asynchronously – the synchronization task is placed into a queue, where it waits until the task's processing is started by a scheduledtask or by a user manually.Synchronously – the synchronization task is passed directly to the connector.

Integration bus overview - learn about the options the integration bus offers.

Managing integration tasks - see how to manage the synchronization tasks used by the integration bus.

Example - Integration connector - inspect a sample integration connector.

Reference - Integration bus data types - refer to this page whenever you need more information about the classes, interfaces andenumerations related to the integration bus.

Integration bus database model - a reference page about the integration bus data model.

1. 2. 3. 4.

Enable the integration bus featuresCreate integration connectorsImplement outgoing synchronizationImplement incoming synchronization

Data types for subscriptions

Subscriptions use one of three data types to specify which data is transferred:

Simple - this type synchronizes the content of objects.SimpleSnapshot - this type synchronizes whole objects and preserves foreign key bindings. This applies only when the 3rd partysystem has an architecture and database design similar to Kentico.Snapshot - synchronizes multiple objects at once. For example a main object with its children, such as polls together with pollanswers. Not supported for pages.

For details, refer to the enumeration.TaskDataTypeEnum

Asynchronous processing

With asynchronous processing of tasks, the data of the changed object or page is first stored in the database (the task is logged in the taskqueue). If the external system is not available, the tasks wait ordered in the queue until they can be reliably processed.

The of asynchronous processing: advantages

Synchronization data is not lost even if the processing of tasks fails.Asynchronous processing is highly scalable, all timeconsuming operations are performed one by one.Allows translation of column values using the method.TranslateColumnsToExternal()

The of asynchronous processing: disadvantages

No context is available during the object/page processing.

Otherwise, asynchronous processing does not have any major disadvantages, and can be used for most scenarios.

To ensure maximum performance, the system postpones the logging and processing of tasks until the event.EndRequest

https://docs.kentico.com/display/K82/Reference+-+Integration+bus+data+types#Reference-Integrationbusdatatypes-TaskDataTypeEnumhttp://msdn.microsoft.com/en-us/library/system.web.httpapplication.endrequest.aspx

When the processing thread starts, the connector begins by fetching the first task in the queue (FIFO principle). Fetched tasks aretransformed to strongly typed objects and passed to the methods implemented in the connector class. In some cases, additional methods arecalled, for example when performing translation of foreign keys. When the task is processed, the result value (of type IntegrationProcessRes

) is returned to notify the connector. Depending on the result, the connector decides what to do next.ultEnum

Note: Processing doesn’t start on when the object or page has been changed in an asynchronous thread (forEndRequestexample when importing new sites with the option enabled).Log integration tasks

https://docs.kentico.com/display/K82/Reference+-+Integration+bus+data+types#Reference-Integrationbusdatatypes-IntegrationProcessResultEnumhttps://docs.kentico.com/display/K82/Reference+-+Integration+bus+data+types#Reference-Integrationbusdatatypes-IntegrationProcessResultEnum

Synchronous processing

When using synchronous processing, the changed object is passed directly to the connector for further processing.

The of synchronous processing include:advantages

You can manipulate objects within the context of Kentico — you can access properties like or of the currentlyParent Childrenprocessed object, and the data are fetched from the database just in time.With pages, you can access properties like , and .Tags Categories Attachments

The of synchronous processing include:disadvantages

The system does not store the synchronization data in the database — if an error occurs and the connector fails to process therequest, the data are lost.Synchronous processing of large or numerous tasks may slow down the application.No method.TransalteConlumnsToExternal()

It is recommended to use synchronous processing only if you need to leverage the advantages.

Note: The is already implemented. You only need to prepare the parts of the code shown in theBaseIntegrationConnectorinherited connector class ( in the figure above).CustomIntegrationConnector

Processing of synchronous tasks starts immediately after an object or page matching a subscription is changed. Unlike asynchronousprocessing, where the logging and processing is postponed until the application reaches , synchronous processing sends theEndRequestdata instantly to the subscribed connectors.

Incoming tasks - From external applications to Kentico

The inbound direction allows you to transfer changes from external applications to Kentico by sending data to the Integration bus. Thesystem stores the data in a queue, later takes them from the queue, and processes them on a regular basis or on your request. Processingof incoming tasks is .always asynchronous

Your task as a developer is to implement methods that help the system log the correct data into the queue. You need to convert the externalobject to a corresponding internal object or page, and supply translation information if you want to preserve foreign key bindings:

http://msdn.microsoft.com/en-us/library/system.web.httpapplication.endrequest.aspx

There are two ways to implement the synchronization connectors:

External connectorInternal connector

External connector

The connector is placed within the 3rd party system and references Kentico DLLs. The Kentico database is accessible from the externalsystem. The advantage is that even if the Kentico instance is not accessible for some reason, the synchronization data (integration tasks) arelogged to the queue and can be reliably processed later without loss of data.

Internal connector

The connector is located within the Kentico instance. The communication is ensured by a service (web or WCF). The advantage is that thereis no need to reference Kentico DLLs. On the other hand, you have to put extra effort into the implementation of the communication service.

Enabling the integration busTo enable the , open the application in the Kentico administration interface and adjust the settings in the Integration bus Settings Integration

category.-> Integration bus

Setting Description

Enable system integration bus Allows logging and processing of incoming and outgoingintegration tasks.

Integration tasks represent individual synchronization operationsfor objects or pages (create, update, delete etc.). Thesynchronization process consists of two steps:

Logging - creation of integration tasks for actions that requiresynchronization.Processing - execution of the integration tasks.

You can enable or disable logging/processing of incoming/outgoingtasks separately through the other settings in the category.

Enable logging of incoming tasks Indicates if the integration bus logs integration tasks received fromexternal systems. To log tasks, the Enable system integration

setting must also be enabled.bus

Enable processing of incoming tasks Check to allow processing of integration tasks incoming fromexternal systems. To process tasks, the Enable system

setting must also be enabled.integration bus

Enable logging of outgoing tasks Indicates if the integration bus logs changes made to pages andobjects in Kentico as outgoing integration tasks. To log tasks, the E

setting must also be enabled.nable system integration bus

Enable processing of outgoing tasks Check to allow processing of outgoing integration tasks. Toprocess tasks, the setting mustEnable system integration busalso be enabled.

All sites in the system share the same settings for the integration bus. You need to select the option in the selector to(global) Siteconfigure the settings.

1. 2. 3. 4.

5.

6.

Creating integration connectorsYou can add integration connector classes into your application in two ways:

In the App_Code directoryIn a separate project or assembly

Creating connectors in the App_Code folder

Open your Kentico web project in Visual Studio.Create a new class in the folder (or if you installed Kentico as a web application project).App_Code Old_App_CodeSet the class to inherit from BaseIntegrationConnector.Override the method and set the property within this method.Init() ConnectorName

The value of the property must match the code name of the connector object registered in theConnectorNameadministration interface.

using CMS.Synchronization;using CMS.SynchronizationEngine;

public class CMSIntegrationConnector : BaseIntegrationConnector{ /// /// Initializes the connector name. /// public override void Init() { // Initializes the connector name (must match the code name of theconnector object in the system) // GetType().Name uses the name of the class as the ConnectorName ConnectorName = GetType().Name; }}

Ensure that the system loads the appropriate class when working with the connector using the assemblyRegisterCustomClassattribute. See for more information.Loading custom classes from App_Code

using CMS;

[assembly: RegisterCustomClass("CMSIntegrationConnector",typeof(CMSIntegrationConnector))]

On web application projects, build the solution.

https://docs.kentico.com/display/K82/Loading+custom+classes+from+App_Code

1. 2.

3. a. b. c.

4. 5. 6.

1. 2. 3. 4.

5.

With the connector class prepared, you now need to:

Implement and/or synchronizationoutgoing incomingRegister the connector in the system

You can find an example of a basic connector class on the page.Example - Integration connector

Creating connectors in a separate project or assembly

Open your Kentico web project in Visual Studio (using the or file).WebSite.sln WebApp.slnAdd a new project to the solution (name it e.g. ).Class Library CustomIntegrationConnector

This ensures that the connector has its own DLL assembly.Add references to the project:

Right-click the project and select Add reference...Click Browse...Add at least the following references from the project's directory:Lib

CMS.SynchronizationCMS.SynchronizationEngineCMS.DocumentEngineCMS.HelpersCMS.DataEngineCMS.SiteProviderCMS.WorkflowEngineCMS.Base

Edit and rename the default class in the project and set the class to inherit from BaseIntegrationConnector.Override the method and set the property within this method.Init() ConnectorNameBuild the solution.

With the connector class prepared, you now need to:

Implement and/or synchronizationoutgoing incomingRegister the connector in the system

Registering connectors in the system

Once the connector's class is ready, you need to register the connector as an object in the system:

In the Kentico administration interface, open the application.Integration busSelect the tab.ConnectorsClick .New connectorFill in the , and and select the check box.Display name Assembly name Class Enabled

Property Description

Display name The name of the connector displayed in the user interface.

Code name Sets a unique identifier for the connector. Must match thevalue of the property declared in theConnectorNameconnector's class.

Provider class_____________

Specifies the class where the connector class is implemented:

Assembly name - the assembly (project) containing theconnector class. Select for connectors(custom classes)implemented in the App_Code (or Old_App_Code) folder.Class - the exact class (including any namespaces) thatdefines the functionality of the connector. For App_Codeclasses, the value must match the first parameter of the R

attribute that loads the class.egisterCustomClass

Enabled Indicates if the connector logs and processes integration tasks.Logging and processing of tasks must also be in enabled Setti

.ngs -> Integration -> Integration bus

Click .Save

The system displays a warning icon ( ) next to connectors that are not registered correctly. The most common causes of problems are:

The value of the property in the connector class's method does not match the .ConnectorName Init Code nameIncorrect assembly or class name.App_Code classes are not loaded correctly. See for more information.Loading custom classes from App_Code

Note: When you add, edit or delete a connector, the system re-initializes all defined connectors.

https://docs.kentico.com/display/K82/Loading+custom+classes+from+App_Code

1.

2.

3.

Implementing outgoing synchronizationTo synchronize data from Kentico to external applications, you need to decide:

which and you want to synchronizeobjects pages which you want to usedata typewhether you want to use or processing of integration taskssynchronous asynchronous whether you want to handle of foreign key bindingstranslations

Use this information to implement the outgoing synchronization in your :connector class

Prepare subscriptions for the Kentico objects that you want to synchronize:Use predefined subscription methods - allows you to easily subscribe to objects or pagesORBuild subscription objects - allows you to select exactly which objects are synchronized

Implement the method that converts objects or pages to the objects used by the external application.

(Optional) Implement :translation of foreign key bindingsGetExternalObjectID method - if the synchronized objects or pages have bindings to objects inheriting from BaseInfoGetExternalDocumentID method - if the synchronized objects or pages have bindings to pages ( )TreeNode

Creating subscriptions

Subscriptions keep track of actions that occur in Kentico, such as creating, updating or deleting objects and pages. Use subscriptions todetermine the scope of the changes that the connector synchronizes.

You need to implement subscriptions inside the method of your :Init() connector class

using CMS.SynchronizationEngine;using CMS.Synchronization;using CMS.DataEngine;

public class CMSIntegrationConnector : BaseIntegrationConnector{ public override void Init() { // Initializes the connector name ConnectorName = GetType().Name;

// Register your subscriptions here }}

Using predefined subscription methods

You can subscribe to pages or objects by calling the following methods:

SubscribeToAllDocumentsSubscribeToDocumentsSubscribeToAllObjectsSubscribeToObjects

See for information about the method parameters.Reference - Integration bus data types

Examples:

// Subscribes to all types of changes made to user objectsSubscribeToObjects(TaskProcessTypeEnum.AsyncSnapshot, UserInfo.OBJECT_TYPE);

You can if you need to define custom options for the subscription scope.create your own subscription class

https://docs.kentico.com/display/K82/Reference+-+Integration+bus+data+types#Reference-Integrationbusdatatypes-TaskDataTypeEnumhttps://docs.kentico.com/display/K82/Integration+bus+overview#Integrationbusoverview-Synchronousprocessinghttps://docs.kentico.com/display/K82/Integration+bus+overview#Integrationbusoverview-Asynchronousprocessing

1. 2.

// Subscribes to all types of changes made to all pages on all sitesSubscribeToAllDocuments(TaskProcessTypeEnum.AsyncSimpleSnapshot, TaskTypeEnum.All);

Building subscription objects

You can select exactly which objects are synchronized using subscription objects:

Create a new object of a subscription class.Call the method for the object.SubscribeTo

Subscription classes inherit from , and you can use the following predefined options:AbstractIntegrationSubscription

BaseIntegrationSubscriptionObjectIntegrationSubscriptionDocumentIntegrationSubscription

The subscription classes provide the following :filtering options

BaseIntegrationSubscription

ConnectorName - string; assigns the subscription to a connector. Use the property to enter the name of the currentConnectorNameconnector.TaskProcessType - enumeration; specifies the synchronization mode and data type. See for details.TaskProcessTypeEnumTaskType - enumeration; determines the type of the synchronized action (create, update, delete, etc.). See forTaskTypeEnumdetails.SiteName - string; determines the code name of the site where the objects or pages belong. You can use AbstractIntegrationSubscri

to subscribe only to global objects.ption.GLOBAL_OBJECTS

ObjectIntegrationSubscription

ObjectType - string; determines the type (class) of the synchronized object. You can either use the object type code name directly(for example ) or system constants ( ).cms.user UserInfo.OBJECT_TYPEObjectCodeName - string; determines the code name of one specific object, for example: administrator

DocumentIntegrationSubscription

DocumentNodeAliasPath - string; determines the alias path of the synchronized pages, for example: /Products/%DocumentCultureCode - string; determines the culture of the synchronized pages, for example: en-USDocumentClassName - string; determines the of the synchronized pages, for example: page type CMS.MenuItem

If you do not want to limit the synchronization scope through one of the properties, set the given value to in the subscription object'snullconstructor. For the enumeration, set the value.TaskType All

Examples:

Wildcard character %

You can use the percent character (%) as a wildcard representing any number of characters in the string parameter values.

For example, if you specify the as "en-%", the subscription covers all English cultures: , , etc.DocumentCultureCode en-US en-GB

https://docs.kentico.com/display/K82/Reference+-+Integration+bus+data+types#Reference-Integrationbusdatatypes-TaskProcessTypeEnumhttps://docs.kentico.com/display/K82/Reference+-+Integration+bus+data+types#Reference-Integrationbusdatatypes-TaskTypeEnumhttps://docs.kentico.com/display/K82/Page+types

1. 2. 3.

// Subscription that synchronizes the creation of object types starting with'poll.poll' - polls and poll answersObjectIntegrationSubscription objSub = newObjectIntegrationSubscription(ConnectorName, TaskProcessTypeEnum.AsyncSnapshot,TaskTypeEnum.CreateObject, "PersonalSite", "poll.poll%", null);Subsc