Deployment

Deployment is the process of moving data from one environment to another, e.g. from a staging website to production website.

The Deployment tool in Dynamicweb provides some basic functionality that makes it easier to transfer data from one installation to another, and removes some of the time consuming manual work that is usually required when doing so.

Deployment provides a one-way data transfer where data is pushed from source to destination. It is not meant to be a merge tool, so it is not possible to push and pull changes between two installations at the same time.

We provide a set of basic configurations for deploying data to the following areas of DW:

  • Content
  • Ecommerce
  • Users

On a technical level, the Deployment tool uses a series of providers to move data – files, records in the database, configuration setting, content, etc. – from the source to the destination. It is fairly trivial to use these providers to extend the default data configuration – or create your own from scratch.

It is highly recommended that both installations (source and destination) run on the same assembly versions. Any differences in assembly versions might lead to errors or unexpected results.

The Deployment tool is a “dumb” tool, which means that you have to make sure you do some of the operations in the correct order to avoid errors and odd behavior.

The generally recommended order of operations when deploying is:

  1. Copy the templates folder to your files folder before transferring any content dependent on templates
  2. Item types must be transferred BEFORE other types of content (websites, pages, paragraphs, items)
  3. If deploying to Ecommerce you must:
    1. Transfer EcomLanguages before anything else
    2. Transfer the rest of the internationalization settings (Currencies, Countries, VAT groups, etc.)
    3. Transfer the rest of the Ecommerce data

Bear in mind, that not everything can be deployed yet – please consult the provider descriptions below for details.

Before data can be transferred at least one destination should be configured. Destinations can be configured by going to Settings > Developer > Deployment.

A destination must have a name, a URL that points to a Dynamicweb installation and administrator credentials for the remote Dynamicweb installation (Figure 3.1).

Figure 3.1 Creating a Destination

You can verify the URL and credentials by using the “Test connection” button which will try to communicate with the destination and authenticate using basic authentication.

Destination settings are stored as files in the folder /Files/System/Deployment/Destinations.

Once a destination has been configured, you can deploy data from the source to the destination using either the default data configurations or a custom data configuration:

  • Go to Settings > Developer > Deployment
  • Select one of the data configurations, e.g. Content
  • Select a Target and the data you want to deploy (Figure 4.1)
  • Click compare selected to compare the data – or transfer selected to transfer the data immediately
Figure 4.1 Selecting data to deploy

The comparison view (Figure 4.2) provides you with an overview of the differences between the source and the destination. In this case, where I compare item types, we can see that 9 of the item types are identical, 1 is present on both solutions but with some differences, and 1 is present only on the source.

For data which exists on both solutions but with differences, you can click the Details button to get an idea of that the differences are – in this case a creation date, a last updated date, etc. – but the details naturally depend on the type data being compared.

Figure 4.2 Comparing data

After comparing, simply select the data you want to transfer and click Transfer selected – the data will be transferred and you will be presented with a log, hopefully with a positive outcome (Figure 4.3). Old logs can be accessed from Settings > Developer > Deployment > Deployment logs.

On a technical level, the data selected is retrieved from the source, then serialized as a package file before being transferred to the destination, where it is deserialized and the data is restored.

Figure 4.3 The deployment log

A set of default data configurations are supplied by us, and can handle some of the more common tasks when deploying. They are described below, with all their current quirks and limitations.

They are:

  • The Content configuration
  • The Ecommerce configuration
  • The Users configuration

They must be placed in the /Files/System/Deployment/DataGroups folder.

The default data configurations supplied by us are not automatically available – download them here.

The content configuration is capable of moving the following data:

  • Item types
  • Areas (aka. websites)
  • Pages
  • Paragraphs

All internal links are updated as appropriate.

The following limitations apply:

  • Draft & Workflow information is not deployed
  • Language layers are deployed as regular websites – don’t select them when transferring areas/websites unless this is what you want
  • Permissions, split tests & personalization settings are not deployed

Please note, that the deployment tool is a dumb tool – if you don’t transfer everything, you must manually select the appropriate pages & paragraphs belonging to a particular website or page.

You must also make sure you have the correct templates on the destination before transferring data, and you should always deploy your item types before deploying content built on them.

The Ecommerce configuration is capable of deploying Ecommerce-related settings & configuration:

  • Internationalization settings (Countries, Currencies, Languages, and VAT Groups)
  • Order discounts &  Sales discounts
  • Payment methods
  • Shipping methods
  • Tax providers
  • Shops
  • Manufacturer records
  • Order settings
    • Address validation & validation groups
    • Order contexts
    • Order fields & order line fields
    • Order flows & Quote flows
    • Stock states
    • Track & Trace schemas
  • Product catalog settings
    • Product Categories
    • Product fields & product group fields
    • Publication Periods
    • Relation Groups
    • Stock locations
    • Variant groups & variant options
    • Product Units

In short, everything which can be said to be a configuration – and not data. To move data (e.g. orders, products, and product groups) from one solution to another, you must use the Integration Framework.

Since Deployment is a “dumb” tool, you must deploy your data in the correct order to ensure that there are not critical dependency issues.

To avoid dependency errors:

  • Deploy Ecommerce Languages before anything else
  • Deploy the rest of the Internationalization settings (Currencies, Countries & VAT Groups)
  • Deploy everything else

The Users configuration makes it possible to deploy the following data:

  • The AccessUser schema
  • Custom fields

Custom address fields cannot be deployed.

To move users from one solution to another you must use the Integration Framework.

A data configuration is basically an XML file which contain an implementation of one or more data item providers – configurable add-ins with read/write access to a subset of data in the system.

A simple data configuration using the Files data item provider could look like this:

<DataGroup Id="ItemTypes" Name="Item types" Icon="Cube" ParentId=""> <DataItemTypes> <DataItemType Id="ItemTypes" Name="Item types" ProviderTypeName="Dynamicweb.Deployment.DataItemProviders.Files.FilesDataItemProvider"> <ProviderParameters> <Parameter Name="RecursiveSearch" Value="false" /> <Parameter Name="TargetPath" Value="/Files/System/Items" /> </ProviderParameters> </DataItemType> </DataItemTypes> </DataGroup>

In the example above, the Files data item provider is used to move files from the /Files/System/Items folder to the same folder on the destination. It is pretty easy to modify this data configuration to make it moved other files – e.g. the Templates folder:

<DataGroup Id="Templates" Name="Templates" Icon="Cube" ParentId=""> <DataItemTypes> <DataItemType Id="Templates" Name="Templates" ProviderTypeName="Dynamicweb.Deployment.DataItemProviders.Files.FilesDataItemProvider"> <ProviderParameters> <Parameter Name="RecursiveSearch" Value="true" /> <Parameter Name="TargetPath" Value="/Files/Templates" /> </ProviderParameters> </DataItemType> </DataItemTypes> </DataGroup>

As you can see, I’ve simply changed some IDs and names, and modified the two parameters to point to the correct folder and include subfolders.

In case I want to add this Templates-configuration to the Content-configuration, all I have to do is add ParentId=”Content” to the DataGroup node. The Icon="" parameter is optional, and and takes as a value any of the known icon names.

You can use any of the standard data item providers we use to create the custom data configurations – or create and use custom data item providers. Read more about either option below.

A data item provider is a configurable add-in that provides read and write access to a subset of data in the system. Data can be provided by either standard or custom data item providers.

Deployment comes with a set of standard data item providers capable of most simple deployment tasks:

  • The FileDataItemProvider
  • The SettingsDataItemProvider
  • The SqlDataItemProvider
  • The SchemaDataItemProvider
  • The AreaDataItemProvider
  • The PageDataItemProvider
  • The ParagraphDataItemProvider
  • The ContentDataItemProvider

Or you can create a custom data item provider.

The FilesDataItemProvider can be used to transfer files of any type.

Type Name: Dynamicweb.Deployment.DataItemProviders.Files.FilesDataItemProvider

The following parameters are available:

Name

Description

Default value

IncludeHiddenFiles

true | false

false

RecursiveSearch

true | false

false

TargetPath

Relative folder path, e.g. /Files/Documents

/Files

The SettingsDataItemProvider can be used to transfer individual configuration settings.

Type Name: Dynamicweb.Deployment.DataItemProviders.Settings.SettingsDataItemProvider

The following parameters are available:

Name

Description

Default value

KeyPatterns

One or more paths to configuration settings (comma separated)

 

 

The SqlDataItemProvider can be used to transfer database records.

Type Name: Dynamicweb.Deployment.DataItemProviders.Sql.SqlDataItemProvider

The following parameters are available:

Name

Description

Default value

Table

Name of database table, e.g. AccessUser

 

NameColumn

Name of the column that contains a display name. By default the id will be displayed.

 

The SchemaDataItemProvider can be used to transfer schema changes (table columns).

Type Name: Dynamicweb.Deployment.DataItemProviders.Sql.SchemaDataItemProvider

The following parameters are available:

Name

Description

Default value

Table

Name of database table, e.g. AccessUser

 

The AreaDataItemProvider can be used to transfer areas (websites). Attached items are included in the data transfer.

Type Name: Dynamicweb.Deployment.DataItemProviders.Content.AreaDataItemProvider

There are no parameters available for this provider.

Language layers are deployed as regular areas/websites.

The PageDataItemProvider can be used to transfer pages. Attached items are included in the data transfer.

Type Name: Dynamicweb.Deployment.DataItemProviders.Content.PageDataItemProvider

There are no parameters available for this provider.

The ParagraphDataItemProvider can be used to transfer paragraphs. Attached items are included in the data transfer.

Type Name: Dynamicweb.Deployment.DataItemProviders.Content.ParagraphDataItemProvider

There are no parameters available for this provider.

The ContentDataItemProvider can be used to transfer content (areas, pages and paragraphs). Attached items are included in the data transfer.

Type Name: Dynamicweb.Deployment.DataItemProviders.ContentDataItemProvider

This is a work in progress not currently used, and there are no parameters available for this provider. 

If the standard data item providers are not sufficient, you can create custom providers by implementing a class that inherits from Dynamicweb.Deployment.DataItemProvider. Since this is a configurable add-in, it is possible to define custom settings by adding properties with AddInParameter attribute.

The following two methods must be implemented in a custom DataItemProvider:

public override DataItemReader CreateReader() { … } public override DataItemWriter CreateWriter() { … }

The following method must be implemented in a custom DataItemReader:

public override IEnumerable<DataItem> ReadItems(IEnumerable<string> ids) { … }

The following method must be implemented in a custom DataItemWriter:

public override void WriteItems(IEnumerable<DataItem> dataItems) { … }

More information can be found in the API documentation for Dynamicweb.Deployment.DataItemProvider and by consulting Dynamicweb.Deployment.Examples.CustomDataItemProvider.

The following Notifications are available and can be subscribed to:

Dynamicweb.Deployment.Notifications.DeploymentNotification.AfterDeployment Dynamicweb.Deployment.Notifications.DeploymentNotification.BeforeDeployment