Web API Controller Requirements for Automated Tasks

Keep the following requirements in mind when creating the Web API controller:

• The task application must be an ASP.NET WEB API 2 application.
• The WEB API 2 application must output build binaries to the bin folder.
• The name of output assembly of the WEB API 2 project must start with IGXCMSPlugin_ (e.g.,IGXCMSPlugin_StandardAT.dll).
• The plug-in application must reside in a folder under [path-to-cms-site-instance]\App_Data\xml\custom\automated, but you can name this new folder anything you want.
• The plug-in application project must have a reference to the Managed Extensibility Framework (MEF) in the Global Assembly Cache (GAC):. The MEF reference is System.ComponentModel.Composition.
• 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.dll, Ingeniux.CMS.Models.dll, and Raven.Client.Lightweight.dll.
• 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.
  [Export(typeof(CMSWebAPIControllerBase))]
      [ExportMetadata("controller", "StandardOperationsController")]
      [PartCreationPolicy(System.ComponentModel.Composition.CreationPolicy.NonShared)]
      public class StandardOperationsController : AutomatedTaskWebAPIController
      { ... 
      }
            

CMSWebAPIController Class

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 back-end database.
• The _CurrentUser field is used to open sessions.
• The _InitializationException field indicated if initialization of the controller have failed or not. If it is not null, the initialization failed.
• The _XmlFolderLocation field is location of xml folder.
• The _L10NProvider field is for retrieving localized strings for specific UI language.

Use OpenReadSession and OpenWriteSession to open session to retrieve and manipulate objects. Objects only reside in each session. These objects are disposed when the session closes.

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 ways to retrieve configuration for the controller and creates a response object for the controller.

Reading Configurations

The system stores task-specific configurations in the web.config file at the root of the web API application ([path-to-cms-site-instance]\App_Data\xml\Custom\automated\Standard_Operations). You could create strongly-typed configuration elements, but the <appSettings> node will suffice.

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

<appSettings>
    ...
    <add key="DoEmptyRecycleBin" value="true" />
    <add key="DoPublish" value="true" />
    <add key="PublishTargets" value="Production" />
</appSettings>

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, use a DataContract object that can be serialized. Always use the following line to create a response object instance:

AutoTaskResponse resp = CreateAutoTaskResponse();

This automatically tracks any initialization errors.

Of course, it isn't recommended to continue your logic if the initialization error occurred. Therefore, always use the following line after creating a response object:

if (_InitializationException != null) return resp;