Media service XML

18 min

The Optimizely Service API supports bulk importing of media data such as images into Optimizely Commerce.

Media XML file and elements

Media file

For imports using the media service, you can upload an XML file with unc paths or http paths to the media. You also can embed images in a zip file with the media.xml file.

You can generate the XML file by copying a "template" MediaImport_v1.xsd file here:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:simpleType name="EmptyElement">
    <xs:restriction base="xs:token">
      <xs:maxLength value="0"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="GuidElement">
    <xs:restriction base="xs:token">
      <xs:pattern value="\{[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}\}|\([a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}\)|[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:element name="MediaImport">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="ContentFolderUri" type="xs:string" minOccurs="0" maxOccurs="1"/>
        <xs:element name="ProviderName" type="xs:string" minOccurs="0" maxOccurs="1"/>
        <xs:element name="MediaType" type="MediaType" minOccurs="0" maxOccurs="unbounded"/>
        <xs:element name="MediaGroup" type="MediaGroup" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
      <xs:attribute name="totalCount" type="xs:int" default="0"/>
    </xs:complexType>
  </xs:element>

  <xs:complexType name="MediaType">
    <xs:sequence>
      <xs:element name="ContentType" type="xs:string"/>
      <xs:element name="ContentFolderUri" type="xs:string" minOccurs="0"/>
      <xs:element name="ContentProperty" minOccurs="0" maxOccurs="unbounded">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="Name" type="xs:token"/>
            <xs:element name="Type">
              <xs:simpleType>
                <xs:restriction base="xs:token">
                  <xs:enumeration value="Bool"/>
                  <xs:enumeration value="Int"/>
                  <xs:enumeration value="Long"/>
                  <xs:enumeration value="Guid"/>
                  <xs:enumeration value="String"/>
                </xs:restriction>
              </xs:simpleType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="name" type="xs:string" use="required"/>
  </xs:complexType>

  <xs:complexType name="MediaGroup">
    <xs:sequence>
      <xs:element name="Media" type="Media" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
    <xs:attribute name="mediaTypeName" type="xs:string" use="required"/>
    <xs:attribute name="count" type="xs:int" default="0"/>
  </xs:complexType>

  <xs:complexType name="Media">
    <xs:all>
      <xs:element name="IntegrationId" type="xs:string"/>
      <xs:element name="Name" type="xs:string"/>
      <xs:element name="BlobContent" type="BlobContent"/>
      <xs:element name="ContentFolderUri" type="xs:string" minOccurs="0"/>
      <xs:element name="FileExtension" type="xs:string" minOccurs="0"/>
      <xs:element name="Properties" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="Value" type="PropertyValue" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="CatalogEntries" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="Association" type="CatalogMapping" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="CatalogNodes" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="Association" type="CatalogMapping" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:all>
    <xs:attribute name="delete" type="xs:string" use="optional"/>
  </xs:complexType>

  <xs:complexType name="BlobContent">
    <xs:choice>
      <xs:element name="FileInArchive" type="xs:string"/>
      <xs:element name="BlobUri" type="xs:string"/>
      <xs:element name="ContentUri" type="xs:string"/>
      <xs:element name="ExternalUri" type="xs:string"/>
      <xs:element name="Unchanged" type="EmptyElement"/>
      <xs:element name="None" type="EmptyElement"/>
    </xs:choice>
  </xs:complexType>

  <xs:complexType name="PropertyValue">
    <xs:sequence>
      <xs:element name="Name" type="xs:string"/>
      <xs:choice>
        <xs:element name="Bool" type="xs:boolean"/>
        <xs:element name="Int" type="xs:int"/>
        <xs:element name="Long" type="xs:long"/>
        <xs:element name="Guid" type="GuidElement"/>
        <xs:element name="String" type="xs:string"/>
      </xs:choice>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="CatalogMapping">
    <xs:all>
      <xs:element name="Code" type="xs:string"/>
      <xs:element name="GroupName" type="xs:string" minOccurs="0"/>
      <xs:element name="SortOrder" type="xs:int" minOccurs="0"/>
    </xs:all>
    <xs:attribute name="delete" type="xs:string" use="optional"/>
  </xs:complexType>
</xs:schema>

See also the Optimizely Service API on GitHub, for complete code samples.

The following examples show how to work with the XML schema.

MediaImport element

The XML should start with the MediaImport element which holds all of the key elements, as shown in the following example. Each element inside MediaImport is optional.

The root element is named MediaImport, and contains an optional ContentFolderUri element, zero or more MediaType elements, and zero or more MediaGroup elements (in that order).

The ContentFolderUri specifies the root content folder by URI. You can omit it, in which case SiteDefinition.Current.GlobalAssetsRoot is used.

The ProviderName specifies the name of provider when creating integration content Ids. You can use this provider name with the Identity Controller to get a list of content.

Each MediaType element describes a content type for assets. For example, if a customer has both video and image assets that map to different content types, then they need an AssetType element for video and an AssetType element for images.

Each MediaGroup element contains assets associated with a single MediaType element. Multiple MediaGroup elements may exist so that multiple asset types can be operated on in a single import.

<MediaImport>
  <ContentFolderUri>.......</ContentFolderUri>
  <ProviderName>.......</ProviderName>
  <MediaType>.......</MediaType>
  <MediaGroup>.......</MediaGroup>
</MediaImport>

ContentFolderUri element

This element holds the default path where media is stored if it is not set at the MediaType of Media Elements. If you omit it, the assets are stored in the global asset root.

<ContentFolderUri>MyPath/To/SomeFolder</ContentFolderUri>

MediaType element

The ContentType element describes a type of media. Each MediaType element must have a name attribute, a ContentType element, and may have an optional ContentFolderUri element and zero or more ContentProperty elements.

The name attribute is used to associate MediaGroup elements with MediaType elements, and has no meaning outside the scope of this file.

The ContentType element contains a string that is used to load a content type at import time. This string is passed to Type.GetType(string) and must result in a valid type that is assignable to the extended MediaData class for media.

If specified, the ContentFolderUri overrides any ContentFolderUri value in the root element for assets of this type.

Each ContentProperty element specifies a property that is expected to be present on the target content type, by name and type. When the MediaType element is processed, the content type is loaded. The import document only needs to specify properties that are set in Media element. Only the specified types are allowed.

Bool

Long

Guid

String

...
  <MediaType name="pdf">
    <ContentFolderUri>MyType/Path</Name>
    <ContentType>Customer.Website.ContentTypes.PdfData, Customer.Website</ContentType>
    <ContentProperty>
      <Name>Author</Name>
      <Type>String</Type>
    </ContentProperty>
    <ContentProperty>
      <Name>CopyrightYear</Name>
      <Type>Int</Type>
    </ContentProperty>
  </MediaType>
...

MediaGroup element

The MediaGroup element is a container for media of the same type. Each MediaGroup element must have an mediaTypeName element, and may have zero or more Media elements.

mediaTypeName – This attribute must have a value that matches exactly one MediaType element. Multiple MediaGroup elements may be defined that reference the same MediaType.

Media – Each element describes an asset of that type.

...
  <MediaGroup mediaTypeName="pdf">
    <Media>...</Media>
    <Media>...</Media>
    <Media delete="true">...</Media>
  </MediaGroup>
...

Media element

The Media element describes a single asset. Each Media element must contain IntegrationId, Name, and BlobContent elements; and may contain optional ContentFolderUri, FileExtension, MimeType, Properties, CatalogEntries, and CatalogNodes elements.

To delete media in the media element place an attribute delete= true.

IntegrationId – Specifies a unique, stable identifier that the integrated system may use to reference this asset in the future.

Name

BlobContent – References binary content, and is documented below.

ContentFolderUri – Can override the value of ContentFolderUri in the root element or ContentFolderUri in the associated AssetType element.

FileExtension – Passed to the BLOB factory if specified and a blob is created.

MimeType – Overrides the detected mime type, if specified.

Properties – Can contain additional properties to set on the content type instance. The Property elements contained in Properties are documented below.

CatalogEntries – May contain entry and node codes to associate the asset with.

CatalogNodes – May contain entry and node codes to associate the asset with.

<Media>
  <IntegrationId>TEST_ENTRY_MEDIA</IntegrationId>
  <Name>TEST_ENTRY_MEDIA</Name>
  <Properties>
    <Value>
      <Name>TestProperty</Name>
      <String>This media item has no blob and no associations.</String>
    </Value>
  </Properties>
  <BlobContent>
    <FileInArchive>Entry.jpg</FileInArchive>
  </BlobContent>
  <CatalogEntries>
    <Association>
      <Code>MEDIAIMPORTJOB_TEST_ENTRY</Code>
      <GroupName>test group</GroupName>
    </Association>
  </CatalogEntries>
  <CatalogNodes>
    <Association>
      <Code>MEDIAIMPORTJOB_TEST_NODE</Code>
      <GroupName>test group</GroupName>
    </Association>
  </CatalogNodes>
</Media>

BlobContent element

The BlobContent element describes the binary content to use for the asset, and is a choice between multiple values.

FileInArchive – The element value is a path and file name in the archive that was imported. This will fail if the import was performed directly on XML and not on an archive, or the specified file is not found in the archive.

BlobUri – The element value looks up an existing BLOB by URI. This will fail if the specified blob is not found.

ContentUri – The element value is used to look up a MediaData content type instance by URI, and use the blob in that content. This will fail if the specified blob is not found.

ExternalUri – An external unc path or http path to an asset in an external location.

Unchanged – The BLOB content is not changed. This will fail if the asset is created by the import operation.

None – The BLOB content is cleared if the asset exists, or not set if the asset is created. None will not fail.

PropertyValue element

Use the PropertyValue element to set a property on the media. The element must have a Name element followed by one of the value elements. The property name and type must match an MediaType/ContentProperty property in the MediaType element associated with the parent MediaGroup element. Only the specified types are allowed.

Bool

Long

Guid

String

Asset examples

Existing assets, catalog mapping only

...
  <Media>
    <IntegrationId>IMG_12387</IntegrationId>
    <Name>...</Name>
    <BlobContent>
      <Unchanged/>
    </BlobContent>
    <CatalogEntries>
        <Association>
            <Code>SKU_12387</Code>
        </Association>
    </CatalogEntries>
  </Media>
...

Delete catalog mapping only

...
  <Media>
    <IntegrationId>IMG_12387</IntegrationId>
    <Name>...</Name>
    <BlobContent>
      <Unchanged/>
    </BlobContent>
    <CatalogEntries>
        <Association delete="true">
            <Code>SKU_12387</Code>
        </Association>
    </CatalogEntries>
  </Media>
...

Import asset content from archive, no catalog mapping

...
  <Media>
    <IntegrationId>b48f59ed6a6d023f60334f6f10ed060e53d804c3</IntegrationId>
    <Name>...</Name>
    <BlobContent>
      <FileInArchive>content/images/b4/8f59ed6a6d023f60334f6f10ed060e53d804c3</FileInArchive>
    </BlobContent>
    <FileExtension>png</FileExtension>
    <MimeType>image/png</MimeType>
  </Media>

Delete asset content

...
  <Media delete="true">
    <IntegrationId>b48f59ed6a6d023f60334f6f10ed060e53d804c3</IntegrationId>
    <Name>...</Name>
    <BlobContent>
      <FileInArchive>content/images/b4/8f59ed6a6d023f60334f6f10ed060e53d804c3</FileInArchive>
    </BlobContent>
    <FileExtension>png</FileExtension>
    <MimeType>image/png</MimeType>
  </Media>

Media import with HTTP image

<MediaImport>
  <ContentFolderUri>default content folder uri</ContentFolderUri>
  <MediaType name="test">
    <ContentType>EPiServer.ServiceApi.Specs.TestData.TestMedia, EPiServer.ServiceApi.Specs</ContentType>
  </MediaType>
  <MediaGroup mediaTypeName="test">
    <Media>
      <IntegrationId>TEST_IMAGE</IntegrationId>
      <Name>Test Media with Binary Content in Archive</Name>
      <BlobContent>
        <ExternalUri>http://mysite.com/Entry.jpg</ExternalUri>
      </BlobContent>
    </Media>
  </MediaGroup>
</MediaImport>