Hide menu Last updated: Oct 20 2016
Area: Episerver Service API Applies to versions: 1 and higher

Media service

EPiServer.ServiceApi allows for bulk importing of media data into Episerver. See Setting up EPiServer.ServiceApi and Overview of EPiServer.ServiceApi for information about installing and configuring the service API.

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.

Media bulk import methods

Media bulk import with file

episerverapi/commerce/import/assets
See the following Media XML to generate the XML needed for the method.

Media bulk import with file upload identifier

episerverapi/commerce/import/assets/{uploadId:guid}
See the following Media XML to generate the xml needed for the method. For this method to work, you need to a valid upload identifier of a catalog.zip file previously uploaded using the chunked upload methods

Media XML

The following examples show how to work with the XML schema. Download the XSD for the media.xml here.

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.

Example:

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.

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

The 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
    • Int
    • Long
    • Guid
    • String

Example:

The 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.
  • The mediaTypeName attribute must have a value that matches exactly one MediaType element. Multiple MediaGroup elements may be defined that reference the same MediaType.
  • Each Media element describes an asset of that type.

Example:

The Media element

  • The Media element describes a single asset. Each Media element must contain IntegrationId, Name, and Blob elements; and may contain optional ContentFolderUri, FileExtension, MimeType, Properties, CatalogEntries, and CatalogNodes elements. 
  • To delete a media, in the media element, place an attribute delete= true.
  • The IntegrationId element specifies a unique, stable identifier that the integrated system may use to reference this asset in the future.
  • The BlobContent element references binary content, and is documented below.
  • The ContentFolderUri element can override the value of ContentFolderUri in the root element or ContentFolderUri in the associated AssetType element.
  • The FileExtension is passed to the blob factory if specified and a blob is created.
  • The MimeType overrides the detected mime type, if specified.
  • The Properties element can contain additional properties to set on the content type instance. The Property elements contained in Properties are documented below.
  • The CatalogEntries and CatalogNodes elements may contain entry and node codes to associate the asset with.

Example:

The BlobContent element

The BlobContent element describes the binary content to use for the asset, and is a choice between multiple values. The optional validate attribute can be set to true to cause an error if the strategy fails (otherwise, failures are reported as warnings, and the import continues).

  • 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.

If validate is false or not set and there is a failure, the blob is unchanged on existing assets and not set on new assets.

The 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
  • Int
  • Long
  • Guid
  • String

Asset examples

Existing assets, catalog mapping only:

Import asset content from archive, no catalog mapping:

Delete asset content:

Media import with http image:

Comments