Creating an Automated Tasks Web API Controller

To create a web API controller for automated tasks, the best place to start is in the standard operations project. This article explains how the web API works, and how it interacts with automated tasks controllers.

The CMSWebAPIController class

The Ingeniux CMS plug-in system uses the Managed Extensibility Framework (MEF) to lazy-load types exported in folders under the automated folder, creating a real-time ApiController instance based on the application's URL. The base type the plug-in system expects is CMSWebApiControllerBase.

namespace Ingeniux.CMS
	public class CMSWebAPIControllerBase : ApiController
		protected ContentStore _ContentStore;
		protected IReadonlyUser _CurrentUser;
		protected Exception _InitializationException;
		protected Ingeniux.CMS.L10N.LocalizationProvider _L10nProvider;
		protected string _XmlFolderLocation;
		public bool IsDebug;

		protected IUserSession OpenReadSession();
		protected IUserWriteSession OpenWriteSession();

This class contains important members that are used to retrieve information about the CMS application and user session context.

  • The _ContentStore field is the connection to the backend database.
  • The _CurrentUser field is used to open sessions.
  • The _XmlFolderLocation field is location of xml folder.
  • The _L10NProvider field is for retrieving localized strings for specific UI language.
  • The _InitializationException field indicated if initialization of the controller have failed or not. If it is not null, the initialization failed.

Use OpenReadSession and OpenWriteSession to open session to retrieve and manipulate objects. Objects only reside in each session and are disposed upon session disposal.

The base AutomatedTaskWebAPIController

	public class AutomatedTaskWebAPIController : CMSWebAPIControllerBase
		public AutomatedTaskWebAPIController();

		public Configuration.Configuration Configuration { get; }

		public AutoTaskResponse CreateAutoTaskResponse();

		public string GetAppSetting(string settingName, string defaultValue);
AutomatedTaskWebAPIController is the base class for all automated task script controllers. In addition to the basic CMS environment, it provides the ways to retrieve configuration for the controller and create a response object for the controller.

Reading configurations

Unlike the previous automated task script, the new system stores task-specific configurations in the web.config file at the root of the web API application ([siteName]\App_Data\xml\Custom\automated\Standard_Operations). If you are willing to make strong-typed configuration elements, feel free to do so. Otherwise, the appSettings suffice.

The <appSettings> node holds configuration information for the standard operations controller:

Routing configurations

The routing template for automated task controller is Automated/{controller}/{action}. To fall back to the Index action, the {action} section can be skipped. For example, the routing Automated/StandardOperations defaults to the Index action.

The routing Automated/MyTask/Backup uses the MyTaskController class and the Backup action.

Creating response objects

The automated task framework only recognizes a specific XML format. To produce this format, there is a DataContract serializable object. Always use the following line to create a response object instance:

AutoTaskResponse resp = CreateAutoTaskResponse();

This automatically tracks any initialization errors.

Web API controller requirements for automated tasks

  1. The task application must be a WEB API 2 application.
  2. The plug-in application must reside in a folder under the App_Data/xml/custom/automated folder. The name of the folder doesn't matter.  
  3. The plug-in application project must have the a reference to the Managed Extensibility Framework (MEF) assembly in GAC:System.ComponentModel.Composition.
  4. The plug-in application project must have references to following DLLs from the CMS site's bin folder: Ingeniux.CMS.Common.dll,Ingeniux.CMS.CSAPI.dllIngeniux.CMS.Models.dll, and Raven.Client.Lightweight.dll.
  5. The controller class is derived from AutomatedTaskWebAPIController. It must be exposed to MEF via the Expose attribute. This attribute class is under the System.ComponentModel.Composition namespace.

    The ExportMetaData attribute, which must be used on the controller class, the name must be controller and the value must be the exact name of the controller class.

    	[ExportMetadata("controller", "StandardOperationsController")]
    	public class StandardOperationsController : AutomatedTaskWebAPIController
    	{ ... }
  6. The WEB API application must make sure the output of build binaries are in the bin folder.
  7. The name of output assembly of the WEB API project must start with IGXCMSPlugin_. For example, IGXCMSPlugin_StandardAT.dll.