Navigation and service panel


Create Media Item along with language version through Sitecore Item Web API

By Zahid Nawaz on 25. September 2014, No comments

In this blog post I will explain how to create a media item along with different language versions through the Sitecore Item Web API. Out-of-the-box Item Web API does not provide feature to create other language versions of existing media item. To achieve this goal one need to write his own custom pipeline processor. In this blog post I have explained which processor do you need to override and what should you care about while overriding?

Recently I was working on a project where I needed to provide an interface through which one can create content in sitecore. Instead of creating any custom web service I decide to use the Sitecore Item Web API. Since Sitecore CMS version 7.1, the Item Web API comes out-of-the-box with Sitecore. In my project I am using Sitecore 7.2 (rev. 140314) with Item Web API version 1.2.

In Item Web API is work still in progress, therefore I must have to face some limitations. One of them was how to create a language version of a media item. You can create a new item in the Sitecore Media Library through HTTP POST. By default the Item Web API creates a media item based on an "unversioned" template for media items. Also the Item Web API does not offer an interface to update media items. Therefore I need to write my custom Pipeline Processor which lets me create media items with the "versioned" template and also provides the possibility to update existing media item versions or create new item language versions. For this purpose I have to overwrite the existing processor Sitecore.ItemWebApi.Pipelines.Request.ResolveAction in the request pipeline resolver where requests will be resolved according to the HTTP methods used (POST, PUT, GET or DELETE).

My CustomResolveAction processor inherits from the ResolveAction processor. In my implementation I have overridden the Process method with POST and PUT action methods. When a media item is created for the first time, a HTTP POST action will be executed. I extended the request parameters with a boolean property “Version” as a flag to indicate whether to create a media item with a "Versioned" or "Unversioned" item template.

My HTTP POST request:

http://[my-domain]/-/item/v1/sitecore/media library/POC?Name=myimage1&alt=my first image test&sc_database=master&Version=true&sc_lang=de

Please note, when you upload a media item, you must add the Content-Type=multipart/form-data into request HTTP Header.

The details about the request parameters:

  • Name: Media Item Name
  • alt: Image Alternate (HTML Image Alt) Text
  • version: True: versioned media item template will be implemented. False: Unversioned media item template will be implemented.
  • sc_database: Content Data base is always master
  • sc_lang: Language Version of media item (e.g. en, de, fr...)

Custom code looks like following.

bool versioned = args.Context.HttpContext.Request.Params["Version"].ToLower() == "true");

Set user decision about selection of media item template to MediaCreatorOptions.

var options = new MediaCreatorOptions
                        AlternateText = args.Context.HttpContext.Request.Params["alt"],
                        Database = args.Context.Database,
                        Destination = destination,
                        Versioned = versioned

The following line of code will create a media item based on the posted media file (image).

Item fromStream = MediaManager.Creator.CreateFromStream(httpPostedFile.InputStream, fileFullName, options);

This is how to create a media item with a specific media item template implementation. Now I have created a media item, which is only available in one language version. To create another language versions of this media item, I need to implement a HTTP PUT action in my CustomResolveAction. This is my HTTP PUT request:

http://[my-domain]/-/item/v1/sitecore/media library/POC?sc_itemid={26EF9FA0-22D9-4C49-9C1E-C1076D85FFF7}&alt=alt_txt_en&version=true &sc_database=master&sc_lang=en

As you can see only one request parameter has changed. Instead of name I now use the sc_itemid. sc_itemid contains the id of media item for which I want a different language version. When I execute this PUT request, Sitecore will try to find the item with the corresponding item id in the given language. If an item exists with this id but does not have the specific language version, a new empty language version for that media item will be created. To attach the submitted image we need to add the uploaded stream into the current item. The following code will do our desired magic:

MediaItem mediaItem = args.Context.Item;
var img = System.Drawing.Image.FromStream(httpPostedFile.InputStream);

mediaItem.Alt = args.Context.HttpContext.Request.Params["alt"];
mediaItem.InnerItem["Width"] = img.Width.ToString();
mediaItem.InnerItem["Height"] = img.Height.ToString();
mediaItem.Size = inputStream.Length;

Media media = MediaManager.GetMedia(mediaItem);


In the above code example, I first create a MediaItem object out of the current context item which has been loaded through sc_itemid. In the second line I have created an image object out of the inputstream. I need this object to extract the image properties like height or width etc. In the next line these properties will be added to the mediaItem. After setting all mandatory image properties, I convert mediaItem into a Media object. The Media class offers a method SetStream where I can set the uploaded image stream data. After execution of this code our desired language version of the image has been created and stored in the Sitecore media library.

Now I have a CustomResolveAction pipeline processor which exactly does what I need for my requirements. To make all this work I have replaced the default ResolveAction through my custom pipeline processor CustomResolveAction in Sitecore.ItemWebApi.config file.


You can give it a try and download the complete source of CustomResolveAction class.

No comments

Add your comment

Your email address will not be published. Required fields are marked *