Item Provider

The Item Provider is used for importing and exporting items – not item types (structure), but items (content). It works best when coupled with XML provider.

As a destination provider (import) you can:

  • Import items as pages or paragraphs
  • Import items to a named item list
  • Update page/paragraph items associations

The intended usage scenario is importing for example news story items to an item list or news page.

If you want to import completely new items (for example from one solution to another), you must first copy the Item types definitions (xml files located in Files/System/Items) from the source solution to the destination solution, and after that restart the destination web site to populate it with the new item types. After this, you will be able to map to the correct item types.

As a source provider (export), the Item Provider exports existing item data and the item usages in pages, paragraphs, web-sites, etc.

When used as a source provider to export item data, the Item Provider does not have any settings.

It exports all items properties with values and items usages in pages, paragraphs, web-sites in the columns:

  • RelevantPageID
  • RelevantParagraphID
  • RelevantAreaID.

When used as a destination provider (i.e. to import data into Dynamicweb) you have access to more extensive customization options (Figure 3.1).

Figure 3.1 When used as a destination provide, you have the above options available to you

Your options are:

  • The Import items as setting lets you select how the imported items will appear after import. The options are Page and Paragraph. If an item already exists, it will not be created again, but will be updated with the data from the import.
  • The New items root page allows you to specify a destination page for imported items. This setting simply saves a Page ID to the job XM.
  • The New items item list setting lets you add the imported items to a named item list. Items which are not of the same item type as the selected list will be ignored during import.

The checkbox options also tweak the provider behavior:

  • If Remove missing items after import is checked, the activity deletes existing items which are not present in the import. The scope is limited to a particular page, if a page has been selected under New items root page.
  • If Delete page, paragraph associated with missing items is selected pages, paragraphs, and websites associated with items not present in the import is deleted as well. Has no effect if not combined with Remove missing items after import.
  • Unpublish imported item pages: Imported page items are set to unpublished

The Item Provider lets you access the tables that are associated with your item types. They can be found in the database with names starting with “ItemType_” string. The columns are the item properties.

Also note these special columns for creating new items during an import:

  • DestinationPageID – Can contain a page id for the appropriate destination page with which the imported item will be associated at the import. Can also contain the page title string, but this is not recommended. Overrides the root page selected in the settings.
  • ParagraphPlaceholder – Can contain a paragraph placeholder name. When you import paragraph items this is the placeholder under which the items will be placed. The values could be main, footer, or left – this depends entirely on the placeholder names in your layout files

If you are updating existing items, you must supply either a page ID, a paragraph ID, or an AreaID (website ID) using the following columns:

  • RelevantPageID – the page id to associate the imported item with
  • RelevantParagraphID – the paragraph id to associate the imported item with
  • RelevantAreaID – the website/area id to associate the imported item with

Why you ask? Because item-based pages & paragraphs are actually regular pages & paragraphs with two properties (Paragraph.ItemType and Paragraph.ItemID) assigned – so if you are updating a set of item-based paragraphs, for instance, the IDs of the paragraphs must be supplied during the import to create the correct relationship between the item and the paragraph it is attached to.

To help you get a sense of how to work with the item provider, we have compiled a few notes on common scenarios.

Imported items are matched with existing items by the “Key Column” values.

For example, you have a mapping for the column “Id” which is a Primary Key/Key Column by default.

In this case, the specific type items will be matched on this column value comparison, and if the imported and existing items are matched the existing item properties values will be updated with the imported values. If the existing item/items are not found by PK column value from the import - new item/items will be created/imported.

You can select any column to serve as the PK column. 

You can import items not related to anything.

This can occur if you have not selected any "New items root page" ,"New items item list", and don't map to the "DestinationPageID", or the columns “RelevantPageID”, “RelevantParagraphID”, and “RelevantAreaID”.

In that case, the item properties are only inserted or updated in the appropriate “ItemType_{some type}” database tables.

You can associate the item with Page by selecting "New items root page" option, or by having a mapping to the DestinationPageID or RelevantPageID columns.

If you are importing items to a destination page that has multiple language versions, the items will be imported for all language versions.

You can associate the item with Paragraph or Website by having the mapping to the RelevantParagraphID or RelevantAreaID columns.

When importing items with destination [Id] column in the mapping: 

  • If the [id] column is empty - <column columnName="Id"></column> - the item will be created with an autogenerated id.
  • If the [id] column has a value, but the value is not already in the database, the item will be created with that values as the id
  • If the [id] column has a value and the value is in the database, the item will be updated with the data from the import

If you want to import items with fields that are “Item Lists” fields or “Referenced Item Lists” fields with comma separated values, you need to select a Primary Key Column in the table mapping that will be used for items association. If the item is found by the Key Column value - its Item Id goes to item list field value.

For example consider the import xml with "List1" item with fields of type “Items List of "MainItem" item type:

<table tableName="List1"> <item table="List1"> <column columnName="Id"><![CDATA[1]]></column> <column columnName="ListOfMainItem"><![CDATA[mainItem1,mainItem2]]></column> </item>

And also in the import you have the mapping and data for the "MainItem" with Key Column selected to "MainItemField1":

<table tableName="MainItem"> <item table="MainItem"> <column columnName="MainItemField1"><![CDATA[mainItem1]]></column> <column columnName="Address"><![CDATA[]]></column> ........... </item> <item table="MainItem"> <column columnName="MainItemField1"><![CDATA[mainItem2]]></column> <column columnName="Address"><![CDATA[]]></column> ........... </item> </table>

After the import the imported "List1" item will have in the "ListOfMainItem" field the comma separated values of the item ids from the recently two inserted "MainItems" matched by Key Column value "MainItemField1"