Asynchronous Import

Release 1.3 - ...

The CMS Import Framework has been enhanced and now includes a class (SixImportExport.AsyncImport) which makes it possible to execute an asynchronous import for the specified xml file. The import takes place on a separate worker thread without blocking the cms manager.

And to make this new feature even more accessible, the built-in cmsWebservice have been adjusted as well and does now include a method to call this async import feature.

This article describes which options are available and how to call this new feature.

Calling the cmsWebservice

Let's just start with showing an example of how easy it is to call this new feature, using the se:webservice macro.

Smartsite SXML	Copy Code
<se:webservice url="{env.cmsserveraddress}"> <se:parameters> <se:parameter name="soapaction">http://smartsite.nl/cmsWebservice/action/cmsWebservice.ImportXmlAsync</se:parameter> <se:parameter name="username">username</se:parameter> <se:parameter name="password">password</se:parameter> <se:parameter name="literalmethodnode"> <i:ImportXmlAsync xmlns:i="http://smartsite.nl/cmsWebservice/message/"> <fileName>../system/import/test_import.xml</fileName> <parent>2</parent> <importSettings> <importmode>3</importmode> <contentstatus>0</contentstatus> <deletesourcefiles>False</deletesourcefiles> </importSettings> </i:ImportXmlAsync> </se:parameter> </se:parameters> </se:webservice>

Smartsite SXML

Copy Code

<se:webservice url="{env.cmsserveraddress}">
 <se:parameters>
  <se:parameter name="soapaction">http://smartsite.nl/cmsWebservice/action/cmsWebservice.ImportXmlAsync</se:parameter>
  <se:parameter name="username">username</se:parameter>
  <se:parameter name="password">password</se:parameter>
  <se:parameter name="literalmethodnode">
   <i:ImportXmlAsync xmlns:i="http://smartsite.nl/cmsWebservice/message/">
    <fileName>../system/import/test_import.xml</fileName>
    <parent>2</parent>
    <importSettings>
     <importmode>3</importmode>
     <contentstatus>0</contentstatus>
     <deletesourcefiles>False</deletesourcefiles>
    </importSettings>
   </i:ImportXmlAsync>
  </se:parameter>
 </se:parameters>
</se:webservice>

The url parameter should point to the cms manager address of the site. The other urls within the example (soapaction parameter and the namespace declaration within the literalmethodnode parameter) are fixed and shouldn't be adjusted.

Use the username and password parameters to specify an account which does have access to the cms manager. The literalmethodnode contains the settings which will be used for executing the asynchronous import. Most of these settings (within the importSettings child-element) will be passed on to the Importer Framework, and below you'll find a list of supported settings.

As you may have noticed, you need to specify a fileName within the settings, so you first need to implement a way of getting the file on the server (this is discussed in ...).

Furthermore, you need to specify a parent. New items will be created as a child-item of this parent. You can either specify an itemnumber as parent or the code of the item.

Notice that the literalmethodnode is case-sensitive and that the example shown above uses the only valid casing.

importSettings element

The importSettings element within the literalmethodnode will be passed on to the Importer Framework, so any option supported by the Importer Framework can be used/set within this element. The table below lists the most important options (in random order). Notice that the settings included within the importSettings element are not case-sensitive, so you can safely type them out using all lower-case if you prefer.

Name	Type	Default	Description
ImportMode	Enum	3 (=Create Always)	Specifies the import mode: 1 = Update existing items (match by code), if not found create new item(s). 3 = Always create new item(s). 4 = Only update exising item(s), do not create new item(s) for items within the xml which could not be matched with an existing item. (modes 0 and 2 are deprecated.)
ContentStatus	Integer	1 (=pre-published)	The content status which should be used for added/updated items. Set to '0' if you want the added/updated items to become active.
ImportSecurityInformation	Boolean	False	Set this parameter to True if the xml contains content access security which should be copied.
UpdateNewerOnly	Boolean	False	If this parameter is set to True and an item within the xml is matched with an existing item, this item will only be updated if the moddate of the item is further in the past then the moddate found within the xml.
DeleteSourceFiles	Boolean	True	When set to True, the Importer will delete the imported file from disc when the import is finished.
AssignWorkflow	Boolean	False	When set to True, the Importer will assign a workflow to every added/updated item. This will be the default workflow for each item's contenttype if no WorkflowCode parameter has been specified, otherwise the workflow with the specified WorkflowCode
WorkflowCode	String	-	Code of the workflow to be used for workflow assignment. (Only applicable when AssignWorkflow has been set to True.)
AssignGroupID	Integer	0	The Group ID (=nr) of the group to which the workflow should be assigned. Defaults to the primary group of the active user executing the import. (Only applicable when AssignWorkflow has been set to True.)
AssignUserID	Integer	0	The User ID (=nr) of the user to which the workflow should be assigned. Should be used in conjunction with AssignGroupID. (Only applicable when AssignWorkflow has been set to True.)
MatchingPhysicalFieldName	String	"code"	When using ImportMode 1 or 4, by default the code field is used to match the xml with an existing item. Of course, the xml must contain a code value as well. This parameter can be used to instruct the Importer to use another field for matching existing items. The logical fieldname should be specified.
RaiseErrors	Boolean	False	Normally, when the Importer fails to add an item or update an existing item, it logs and/or gives feedback about this error and continues to process the xml file for other items. If you want the Importer to abort the import process when an error occurs, set this parameter to True.
ExportImportHookProgID	String	-	Prog ID of an object implementing the IExportImportHook interface. This object is then called several times during the import process (onBeforeImport, onBeforeUpdateItem, onBeforeAddItem, onAfterImport) and can be used to adjust the xml and/or the data which will be used to insert/update an item.
ConsumeContentChangeEvents	Boolean	False	When this parameter has been set to True, the Importer will start an synchronous Event Subscriber which will "consume" any ContentChange.Activation events which occur during the import. Then, after the Import finishes, the publication engine is refreshed (using Clear Memory Cache and Clear Disk Cache calls).
DisplayDetailedImportSummary	Boolean	True	Parameter to switch detailed import summary on/off. When switched on, the import summary includes a complete list of created items, updated items, failed items, etc. When your import xml file contains hundreds or thousands of items, you may want to switch off this feature.
ImportParents	Boolean	False	Determines if the parent-value of an existing item should be updated according to the parent information found within the xml.
KeepOriginalDates	Boolean	False	When set to True, AddDate and ModDate as specified within the xml will be used.
DeleteChildren	Boolean	False	Enable this option when every item below the specified parent should be deleted (status of these items will be set to Deleted) prior to executing the import.

The table below lists the Asynchronous Import specific options, which should also be included within the importSettings element when you need/want to use one of these options.

Name	Type	Default	Description
WriteImportJob	Boolean	False	When this option is True and the table ImportJobs does exists and an ImportID has been specified, an record will be added to the ImportJobs table before the import is started.
ImportID	String	-	A string (e.g. a guid) which can be used to identify different import jobs.
ReturnUrl	String (url)	-	When the import is successfully completed (or when it fails), an http request to the specified url will be executed. This request can then be used as signal/acknowledgement that the importer has finished and whether it was successful (status=1 is appended on the querystring) or the import failed (status=-1 on the querystring).
ReturnUrlUsername	String	-	When the ReturnUrl is to a restricted url, use this parameter to specify an username to login.
ReturnUrlPassword	String	-	When the ReturnUrl is to a restricted url, use this parameter to specify a password to login.
ReturnUrlUseWindowsAuthentication (1.4 build 4+)	Boolean	False	When the ReturnUrl is to a site which uses (integrated) Windows Authentication, set this parameter to True.
SmartsiteUsername	String	-	Smartsite account which should be used for adding/updating items. Defaults to the built-in Smartsite system account (Smartsite Middleware). You only need to specify the username.
SkipPostProcessing	Boolean	False	Option with which the post-processing step of the Importer can be skipped. Within this post-processing, the following tasks are performed: fix cross-links; assign workflow, if specified; create import summary.

Changes in 1.4+

The Asynchronous Importer did perform some internal checks on specified parameters (e.g. parent, fileName) before starting a job.
If one of those checks failed, the thread was aborted and only a log message was written to the Smartsite log.

Now, if a check fails a proper error is raised and, when enabled, this error is used as import job result (status=-1 and the error description will be written to the log field of the import job). Also the returnUrl, if specified, will be called when one of these internal checks fails.

Advanced