Including a custom xConnect model

Version: 10.1

This topic explains how you include a custom xConnect model when you build Sitecore Docker images for a Sitecore Experience Platform (XP) implementation. Additionally, this guide assumes you have some knowledge of Sitecore xConnect, the xConnect model, and how customizations are made.

Clone the Docker Examples repository

If you have not already done so, clone the Docker Examples repository to a location on your machine. This topic uses the custom-images folder from the repository.

Example preparation

The custom-images example requires some preparation before it can be run. If you have not already done so, either follow the preparation steps or run the included init.ps1 script to perform these preparation steps automatically:

Open a PowerShell administrator prompt, navigate to the custom-images folder, and run the following command, replacing the -LicenseXmlPath with the location of your Sitecore license file:
RequestResponse
```
.\init.ps1 -LicenseXmlPath C:\License\license.xml
```

Understand xConnect model deployment

xConnect custom model development requires several build artifacts, and you must make sure that each of these artifacts are included in specific images within the Sitecore Experience Platform container environment.

Build artifacts defined

Based on the documentation for creating and deploying custom xConnect models, there are the following (hypothetical) build artifacts:

CustomModel.dll
CustomModel, 1.0.json
sc.CustomModel.xml (step 2 in the documentation Deploy the model to the Marketing Automation Engine section)
Sitecore.XConnect.Client.config patch (step 2 in the documentation Deploy the model to core roles section)

Sitecore images that requite artifacts

The following table lists Sitecore images for both XP0 (Single) and XP1 (Scaled) topologies. You can see which images require the xConnect build artifacts and where you must included them. If an image is not listed here, it does not require any artifacts.

You include these artifacts in your Sitecore runtime Dockerfile for each image role.

Sitecore image / role	XP0	XP1	CustomModel.dll	CustomModel, 1.0.json	sc.CustomModel.xml	Sitecore.XConnect.Client.config patch
cd		x	`root`\bin			x
cm	x	x	`root`\bin			x
xconnect	x		`root`\bin	`root`\App_Data\Models	`root`\App_Data\Config\Sitecore\MarketingAutomation
xdbsearchworker	x	x		`root`\App_Data\Models
xdbautomationworker	x	x	`root`		`root`\App_Data\Config\Sitecore\MarketingAutomation
cortexprocessingworker	x	x	`root`	`root`\App_Data\Models
prc		x	`root`\bin			x
xdbcollection		x	`root`\bin	`root`\App_Data\Models
xdbsearch		x	`root`\bin	`root`\App_Data\Models
xdbautomation		x	`root`\bin	`root`\App_Data\Models	`root`\App_Data\Config\Sitecore\MarketingAutomation

Note the root path varies for each image: C:\service for the worker roles, C:\inetpub\wwwroot for all others.

The Docker Examples xConnect projects

The Docker Examples repository has multiple projects that demonstrate custom xConnect models. Navigate to the custom-images folder and open the solution DockerExamples.sln in Visual Studio. The solution includes these projects:

DockerExamples.XConnect.Model: Contains a custom xConnect model and facet (CustomModel.dll in the table above).
DockerExamples.XConnect : Facilitates the build and publish of xConnect artifacts and also includes the required xConnect config files DockerExamples.XConnect.Model.DemoModel, 1.0.json (CustomModel, 1.0.json in the previous table), and sc.DockerExamples.DemoModel.xml (sc.CustomModel.xml in the previous table).
DockerExamples.Website: Facilitates the build and publish of website/platform artifacts, and also includes the required xConnect config file DockerExamples.XConnect.config (Sitecore.XConnect.Client.config patch in the previous table).

App.XConnect.ModelBuilder: A console app you use to generate the required xConnect model JSON file.
App.XConnect.Demo: A console app that adds a test contact with the custom model and facet.

In a Helix solution, the DockerExamples.XConnect and DockerExamples.Website projects are most often broken down into separate Environment modules and one or more project/feature modules. They are combined here for the sake of simplicity.

Configuring in solution build

To see how the solution is configured in the Docker Examples:

Open theDockerfile in the custom-images folder. It shows that the xConnect project (DockerExamples.XConnect.csproj) is built separately from the website/platform build (DockerExamples.Website.csproj), with the output at C:\out\xconnect:
RequestResponse
```
RUN msbuild .\src\DockerExamples.XConnect\DockerExamples.XConnect.csproj /p:Configuration=Release /p:DeployOnBuild=True /p:DeployDefaultTarget=WebPublish /p:WebPublishMethod=FileSystem /p:PublishUrl=C:\out\xconnect
```
Copy in from the builder stage to the final image with the following structure:
- \artifacts\xconnect:
RequestResponse
```
COPY --from=builder C:\out\xconnect .\xconnect\
```

Alternative: Generate xConnect model JSON files dynamically

Instead of generating the model JSON manually (for example, by using App.XConnect.ModelBuilder) and including it in the solution (\src\DockerExamples.XConnect\App_Data\Models\DockerExamples.XConnect.Model.DemoModel, 1.0.json), you can do this as part of the Dockerfile instructions. The drawback of this is that you cannot publish your xConnect model into a running container because this requires an image build.

The App.XConnect.ModelBuilder example accepts an argument for the output path. Within the builder stage, you can build the App.XConnect.ModelBuilder, and then use it to generate xConnect model JSON files:

RequestResponse

RUN msbuild .\src\App.XConnect.ModelBuilder\App.XConnect.ModelBuilder.csproj /p:Configuration=Release /p:OutDir=C:\build
RUN .\App.XConnect.ModelBuilder C:\out\xconnect\models

You must then adjust your final artifact instructions to copy these in:

RequestResponse

COPY --from=builder C:\out\xconnect .\xconnect\
COPY --from=builder C:\out\xconnect\models .\xconnect\App_Data\Models\

Add artifacts to Sitecore runtime images

The following example shows the configuration for a Sitecore Experience Platform - Single (XP0) topology.

Note

Consider setting up the Sitecore runtime images for services within Sitecore Experience Platform - Scaled (XP1) if you plan on deploying to that topology in an upstream environment. The Docker Examples repository has example Sitecore runtime Dockerfiles for these services as well (xdbcollection, xdbsearch, and so on).

To see this example:

Open the Sitecore runtime Dockerfile for the xconnect service (for example, C:\sitecore\docker-examples\custom-images\docker\build\xconnect\Dockerfile).
Because this uses an IIS image, C:\inetpub\wwwroot is set to the working directory, and then the xConnect build files from the solution build image are copied in:
RequestResponse
```
WORKDIR C:\inetpub\wwwroot
COPY --from=solution \artifacts\xconnect\ .\
```
Open the Sitecore runtime Dockerfile for the xdbsearchworker service. The xConnect worker roles are .NET Core, and therefore a different working directory of C:\service is used:
RequestResponse
```
WORKDIR C:\service
```
If you look at the previous table, you can see the worker roles are more selective about which artifacts are included. The xdbsearchworker image only requires the model JSON file:
RequestResponse
```
COPY --from=solution \artifacts\xconnect\App_Data\Models\ .\App_Data\Models\
```
However, the xdbautomationworker requires the model assembly and the XML file:
RequestResponse
```
COPY --from=solution \artifacts\xconnect\bin\ .\
COPY --from=solution \artifacts\xconnect\App_Data\Config\Sitecore\MarketingAutomation\ .\App_Data\Config\Sitecore\MarketingAutomation\
```
While the cortexprocessingworker requires the model assembly and the JSON file:
RequestResponse
```
COPY --from=solution \artifacts\xconnect\bin\ .\
COPY --from=solution \artifacts\xconnect\App_Data\Models\ .\App_Data\Models\
```

Run Docker Examples

To run the Docker Examples:

Open a PowerShell prompt, go to the custom-images folder, and run Docker Examples with the Docker Compose up command:
RequestResponse
```
docker-compose up -d
```
When the instance is up and running, go back to Visual Studio and run the App.XConnect.Demo console application. This adds a test contact that uses the custom model (DemoModel) and facet (DemoFacet).

You can verify the contact was added with the custom facet by connecting to SQL Server and retrieving records from [Sitecore.Xdb.Collection.Shard0/1].[xdb_collection].[ContactFacets]:
Stop and remove the containers with the down command:
RequestResponse
```
docker-compose down
```

Do you have some feedback for us?

If you have suggestions for improving this article,