Deploy a custom model

Current version: 9.0

This topic describes how to serialize and deploy custom model to xConnect. Model deployment is a manual process that involves copying a JSON representation of a model to all instances of xConnect.

Serialize the model to JSON

To serialize the model to JSON:

Create a console application to serialize the xConnect model.

Serialize the model to JSON as shown - the following example uses Sitecore’s default collection model.

RequestResponse

using Sitecore.XConnect.Serialization;

namespace Documentation
{
    public class DeployModel
    {
        public void Serialize()
        {
            // File name will be Sitecore.XConnect.Collection.Model, 9.0.json
            var json = XdbModelWriter.Serialize(Sitecore.XConnect.Collection.Model.CollectionModel.Model);
        }
    }
}

Important

Do not change the file name. The file name must match the name declared in the model class.

Deploy the model to xConnect and Marketing Automation Operations

To deploy the custom model to the xConnect and Marketing Automation Operations roles:

Copy the model JSON file to the following path on all instances of xConnect Collection Search and xConnect Collection roles:

C:\<Path to xConnect>\root\App_Data\Models
Copy the model JSON file to the following path on in the xConnect Search Indexer.

C:\<Path to indexer>\root\App_data\Models

Note

By default, the xConnect Search Indexer is located under C:\<Path to xConnect>\App_data\jobs\continuous\IndexWorker.
In Sitecore 9.0 Update 2 and later, you must copy the model JSON file to the following path on all instances of the Marketing Automation Operations role. The model is required in order to process live events:

C:\<Path to marketing automation operations>\root\App_Data\Models

Note

Step 3 is not necessary if your Marketing Automation Operations role is combined with xConnect Collection Search or xConnect Collection.

Deploy the model to the Marketing Automation Engine

Complete the following steps in order to work with custom model data in the context of custom activity types. This functionality is available in 9.0 Update-1 onwards.

To deploy the model to the Marketing Automation Engine:

Copy the model DLL to the root of every instance of the Marketing Automation Engine.

Note

The Marketing Automation Engine does not need a JSON representation of the model. By default, the Marketing Automation Engine is located under C:\<Path to xConnect>\App_data\jobs\continuous\AutomationEngine.

In C:\<Path to xConnect>\App_data\jobs\continuous\AutomationEngine\AppData\config\sitecore, create a configuration file named sc.Sample.CustomModel.xml. The file name must start with sc and end with .xml. Paste the following model configuration and make the following changes:

Change the TypeName to the fully qualified name of your model.
Optionally, rename the CustomModel1 node.

RequestResponse

<Settings>
    <Sitecore>
        <XConnect>
            <Services>
                <XConnect.Client.Configuration>
                    <Options>
                        <Models>
                            <CustomModel1>
                                <TypeName>Sitecore.Xdb.MarketingAutomation.Stub.Model.StubModel, Sitecore.Xdb.MarketingAutomation.Stub</TypeName>
                            </CustomModel1>
                        </Models>
                    </Options>
                </XConnect.Client.Configuration>
            </Services>
        </XConnect>
    </Sitecore>
</Settings>

It is assumed your model exposes a static property named Model which returns the XdbModel for your model. If your custom model exposes the model from a different static property, include the name of the property in a PropertyName element inside the CustomModel element:

RequestResponse

<Settings>
    <Sitecore>
        <XConnect>
            <Services>
                <XConnect.Client.Configuration>
                    <Options>
                        <Models>
                            <CustomModel1>
                                <TypeName>Sitecore.Xdb.MarketingAutomation.Stub.Model.StubModel, Sitecore.Xdb.MarketingAutomation.Stub</TypeName>
                                                                    <PropertyName>TheModel</PropertyName>
                            </CustomModel1>
                        </Models>
                    </Options>
                </XConnect.Client.Configuration>
            </Services>
        </XConnect>
    </Sitecore>
</Settings>

Deploy the model to core roles

Finally, you must deploy your custom model to all core Sitecore instances. This includes the following roles:

Content Delivery
Content Management
xDB Processing

On each core Sitecore instance:

Copy the model DLL into the bin directory of your core Sitecore instance.

Patch your own model class into \App_Config\Sitecore\XConnect.Client.Configuration\Sitecore.XConnect.Client.config as shown:

RequestResponse

<?xml version="1.0" encoding="utf-8" ?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
<sitecore>
    <xconnect>
    <runtime type="Sitecore.XConnect.Client.Configuration.RuntimeModelConfiguration,Sitecore.XConnect.Client.Configuration">
        <schemas hint="list:AddModelConfiguration">
            <!-- value of 'name' property must be unique -->
            <schema name="documentationmodel" type="Sitecore.XConnect.Client.Configuration.StaticModelConfiguration,Sitecore.XConnect.Client.Configuration" patch:after="schema[@name='collectionmodel']">
                <param desc="modeltype">Documentation.Model.CollectionModel, Documentation.Model</param>
            </schema>
        </schemas>
    </runtime>
    </xconnect>
</sitecore>
</configuration>

In your code, reference the model DLL.
Use the xConnect Client API to trigger your event or populate your contact facet.

Note

You can also use the model outside of a Sitecore context.

Do you have some feedback for us?

If you have suggestions for improving this article,