---
title: Implementing incoming synchronization
related:
  - https://docs.kentico.com/13/integrating-3rd-party-systems/using-the-integration-bus/integration-bus-overview.md
  - https://docs.kentico.com/13/integrating-3rd-party-systems/using-the-integration-bus/reference-integration-bus-data-types.md
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

To synchronize data from external applications to Xperience, you need to decide:

- which **objects** and **pages** you want to synchronize
- which [data type](https://docs.kentico.com/13/integrating-3rd-party-systems/using-the-integration-bus/reference-integration-bus-data-types.md#taskdatatypeenum) you want to use

Based on this information, choose which methods to implement in your [connector class](https://docs.kentico.com/13/integrating-3rd-party-systems/using-the-integration-bus/creating-integration-connectors.md). Proceed according to the following list:

1. Call the [Implementing incoming synchronization](#logging-incoming-tasks) method to log incoming tasks into the integration task queue. Either call the method in your custom communication service or directly in the code of your external application.
2. Implement the [Implementing incoming synchronization](#prepareinternalobject-method) method in your connector class. The method handles transformations of objects and pages from the external application to Xperience.
3. Implement one or both of these methods:
   - [Implementing incoming synchronization](#getinternalobjectparams-method) – implement this method if you plan to synchronize objects or pages which have foreign keys **referencing objects**.
   - [Implementing incoming synchronization](#getinternaldocumentparams-method) – implement this method if you plan to synchronize objects or pages which have foreign keys **referencing pages**.
4. (Optional) Call the [Implementing incoming synchronization](#requesting-the-processing-of-logged-tasks)method to remotely trigger processing of logged incoming tasks.

> **Note:** **Using incoming synchronization for files**
>
> If you use incoming synchronization tasks to create or update files in the Xperience administration application's file system, these files will not automatically be available in the live site application (unless you use a shared file system). You need to manually ensure that such files are synchronized across the file systems of both applications.

## Logging incoming tasks

The **ProcessExternalTask** method logs object or page tasks into the integration task queue. The system then takes the tasks out of the queue and processes them later. The method is available in the _IntegrationHelper_ class.

The location where you need to call the method depends on the approach that you use to communicate between Xperience and the external application:

- **Xperience API** – if your external application has references to your connector class and the Xperience DLLs (i.e. has the _Kentico.Xperience.Libraries_ NuGet package installed), call the _ProcessExternalTask_ method directly in your application's code.
- **Custom service** – if you use a custom service (Web API, WCF, etc.) to communicate, call the _ProcessExternalTask_ method from the code of the service in the Xperience application.

```csharp title="Example"

using CMS.Synchronization;

...

object externalObject;

IntegrationHelper.ProcessExternalTask("CustomConnector", externalObject, IntegrationProcessTypeEnum.Default, TaskTypeEnum.CreateObject, TaskDataTypeEnum.Simple, "SiteCodeName");

```

The method has the following parameters:

- **connectorName** – the code name of the connector which should process the tasks.
- **obj** – the external object which should be processed. If you have managed to prepare _ICMSObject_ earlier, you can pass it as well.
- **result** – this value indicates how the system behaves when fetching the tasks from the database and how it reacts when an error occurs.
- **taskType** – by providing this value, you say whether the provided object or page should be created, updated, deleted, etc.
- **dataType** – indicates, whether the provided object contains child objects. The value also indicates whether the methods for collecting translation information will be called.
- **siteName** – if the processed object belongs to a site, provide a code name of this site.

You can find detailed descriptions of particular enumerations used in the parameters in [Enumerations](https://docs.kentico.com/13/integrating-3rd-party-systems/using-the-integration-bus/reference-integration-bus-data-types.md#enumerations).

Use a reference to the **CMS.Synchronization** namespace and call this method anywhere in the code of your external application.

![The sequence of method calls for each incoming synchronization](https://docs.kentico.com/docsassets/13/implementing-incoming-synchronization/image2013-9-10+2.png "The sequence of method calls for each incoming synchronization")

## Implementing the incoming synchronization

### PrepareInternalObject method

Implement the _PrepareInternalObject_ method in your connector class. This method transforms objects from the external application into the corresponding objects or pages in Xperience. The method must return a valid _TreeNode_ page or object inheriting from _BaseInfo_ (UserInfo, RoleInfo, ForumPostInfo etc.).

```csharp

public override ICMSObject PrepareInternalObject(object obj, TaskTypeEnum taskType, TaskDataTypeEnum dataType, string siteName)
{
    ...
    return UserInfo;
}

```

![Calling of the PrepareInternalObject method](https://docs.kentico.com/docsassets/13/implementing-incoming-synchronization/image2013-9-10+1.png "Calling of the PrepareInternalObject method")

### GetInternalObjectParams method

Implement the _GetInternalObjectParams_ method if you need to synchronize objects that have foreign key bindings with other objects in Xperience. Based on the _id_ and _objectType_ parameters, you should be able to find the corresponding object in the external application, and then set the method's _out_ parameters. At the very least you need to supply the object's code name (_codeName_ parameter). The _siteName_, _parentId_ and _groupId_ parameters allow you to specify the object with more precision. The system then finds the related object in the Xperience database according to the _out_ parameters, and translates the foreign key values.

```csharp

public override void GetInternalObjectParams(int id, string objectType, out string codeName, out string siteName, ref int parentId, ref int groupId)

```

### GetInternalDocumentParams method

Implement the _GetInternalDocumentParams_ method if you need to synchronize objects that have foreign key bindings to pages in Xperience. Based on the _id_ and _className_ parameters, you should be able to find the corresponding page in the external application, and then specify the page's _nodeGuid_, _cultureCode_ and _siteName_ through the method's _out_ parameters.  All of the parameters are mandatory. The system then finds the related page in the Xperience database, and translates the foreign key values.

```csharp

public override void GetInternalDocumentParams(int id, string className, out Guid nodeGuid, out string cultureCode, out string siteName)

```

## Requesting the processing of logged tasks

The _BaseIntegrationConnector_ offers two overloads of the _RequestTasksProcessing_ method:

```csharp

HttpStatusCode RequestTasksProcessing(string serverUrl)
HttpStatusCode RequestTasksProcessing(string serverUrl, string connectorName)

```

Call this method in your connector class. When this method is called, the application makes a HTTP request to the _\~/CMSPages/IntegrationNotify.aspx_ page, which starts the processing of incoming tasks logged in the Xperience project. Each connector will be processed in its own thread.

As a parameter of this method, specify a URL leading to the root of the Xperience application (e.g. _http://www.example.com/Xperience_). The second overload allows you to also specify the connector whose tasks will be processed. If you do not supply the parameter, all connectors will be processed.