This section provides several examples for creating and working with publishing-related objects and using some of the publishing-related methods on a Document
object.
This example creates a new publish template and persists it to a Content Engine object store by calling the createInstance
method on the Document
class. The content you set for the PublishTemplate
object must be a valid publish template XML file (for example, a publish template authored via the Publishing Designer application), and any GUIDs specified in the file must reference a valid object on the current object store. (The GUIDs that are referenced in the XML file include the output folder, document class, style template, and event action.)
In the example, the new publish template belongs to the PublishTemplate
class and inherits its properties and permissions from this class. If the PublishTemplate
class is subclassed at the Content Engine level, you might want the publish template to belong to a subclass. For an example that shows how to obtain a reference to a subclass to pass to the createInstance
method, see Retrieving a ClassDescription Object.
None of the PublishTemplate
class's properties require setting on creation. However, you might want to check whether any of the class's custom properties require setting before you create the object. For an example of this, see "Using Property Filters" in Working with Properties. You can optionally set permissions for the new object when you create it. For a code example, see Setting Permissions.
// Create a publish template object PublishTemplate pt = Factory.PublishTemplate.createInstance(objectStore); // Set document title for the publish template pt.getProperties().putValue("DocumentTitle", "My New Publish Template"); // Is there a cascade delete dependency between source document and publication? boolean isSourceDependency = true; // isSourceDependency is a boolean variable that represents whether the user wants // to delete the publication automatically, when the source is deleted. It is whichever value // (true or false) the user chooses. String VALUE_ISSOURCEDEPENDENCY = isSourceDependency? "true" : "false"; // Publish template content String PT_CONTENT = "<?xml version=\"1.0\" ?>" + "<publishtemplatecontent>" + "<version>2.0.1</version>" + "<newinstructions>" + "<issourcedependent>" + VALUE_ISSOURCEDEPENDENCY + "<issourcedependent>" + "<outputfoldername>/" + "<applyproperties>" + "<from>source</from> " + //apply properties from source document "</applyproperties>" + "<applysecurity>" + "<from>default</from>" + // apply security from class definition "</applysecurity>" + "</newinstructions>" + "<republishinstructions>" + "<versionablerepublishtype>versionandkeep</versionablerepublishtype>" + "<nonversionablerepublishtype>addandkeep</nonversionablerepublishtype>" + "<applypropertiesfrom>destination</applypropertiesfrom>" + "<applysecurityfrom>destination</applysecurityfrom>" + "</republishinstructions>" + "<publishtemplatecontent>"; String[] PT_DATA = {"myNewPublishTemplate.xml", "application/x-filenet-publishtemplate", PT_CONTENT}; // Create content elements ContentElementList cel = Factory.ContentElement.createList(); ContentTransfer ctNew = Factory.ContentTransfer.createInstance(); ByteArrayInputStream is = new ByteArrayInputStream(PT_CONTENT.getBytes()); ctNew.setCaptureSource(is); ctNew.set_RetrievalName(PT_DATA [0]); ctNew.set_ContentType(PT_DATA [1]); cel.add(ctNew); pt.set_ContentElements(cel); // Check in publish template as major version pt.checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION); pt.save(RefreshMode.REFRESH);
// Create a publish template object IPublishTemplate pt = Factory.PublishTemplate.CreateInstance(objectStore); // Set document title for the publish template pt.Properties.GetProperty("DocumentTitle").SetObjectValue("My New Publish Template"); // Is there a cascade delete dependency between source document and publication? bool isSourceDependency = true; // isSourceDependency is a boolean variable that represents whether the user wants // to delete the publication automatically when the source is deleted. It is whichever value // (true or false) the user chooses. string VALUE_ISSOURCEDEPENDENCY = isSourceDependency ? "true" : "false"; // Publish template content string PT_CONTENT = "<?xml version=\"1.0\" ?>" + "<publishtemplatecontent>" + "<version>2.0.1</version>" + "<newinstructions>" + "<issourcedependent>" + VALUE_ISSOURCEDEPENDENCY + "<issourcedependent>" + "<outputfoldername>/" + "<applyproperties>" + "<from>source</from> " + //apply properties from source document "</applyproperties>" + "<applysecurity>" + "<from>default</from>" + // apply security from class definition "</applysecurity>" + "</newinstructions>" + "<republishinstructions>" + "<versionablerepublishtype>versionandkeep</versionablerepublishtype>" + "<nonversionablerepublishtype>addandkeep</nonversionablerepublishtype>" + "<applypropertiesfrom>destination</applypropertiesfrom>" + "<applysecurityfrom>destination</applysecurityfrom>" + "</republishinstructions>" + "<publishtemplatecontent>"; string[] PT_DATA = {"myNewPublishTemplate.xml", "application/x-filenet-publishtemplate", PT_CONTENT}; // Create content elements IContentElementList cel = Factory.ContentElement.CreateList(); IContentTransfer ctNew = Factory.ContentTransfer.CreateInstance(); System.IO.MemoryStream iS = new System.IO.MemoryStream(PT_CONTENT.Length); ctNew.SetCaptureSource(iS); ctNew.RetrievalName = PT_DATA[0]; ctNew.ContentType = PT_DATA[1]; cel.Add(ctNew); pt.ContentElements = cel; // Check in publish template as major version pt.Checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION); pt.Save(RefreshMode.REFRESH);
As shown in this example, to retrieve a specific PublishTemplate
object from an object store, call Factory.PublishTemplate.fetchInstance
. To retrieve a PublishTemplates
collection that contains all or some specified subset of the publish templates available in an object store, call SearchScope.fetchObjects
.
// Retrieving a PublishTemplate Object PublishTemplate pt = Factory.PublishTemplate.fetchInstance(objectStore, new Id("{02639B6E-52B9-46EB-A590-0D76164BA2D6}"), null); // Retrieve all publish templates that use a style template to generate PDF publications String sqlStr = "Select pt.Id, pt.DateCreated, pt.StyleTemplate from PublishTemplate AS pt WITH INCLUDESUBCLASSES LEFT OUTER JOIN PublishStyleTemplate AS st WITH INCLUDESUBCLASSES ON pt.StyleTemplate = st.This WHERE (pt.IsCurrentVersion = true) AND (st.OutputFormat = 'application/pdf') ORDER BY pt.DateCreated"; SearchSQL sql = new SearchSQL(sqlStr); SearchScope ss = new com.filenet.api.query.SearchScope(objectStore); EngineCollection ec = ss.fetchObjects(sql, null, null, Boolean.TRUE);
// Retrieving a PublishTemplate Object IPublishTemplate pt = Factory.PublishTemplate.FetchInstance(objectStore, new Id("{02639B6E-52B9-46EB-A590-0D76164BA2D6}"), null); // Retrieve all publish templates that use a style template to generate PDF publications string sqlStr = "Select pt.Id, pt.DateCreated, pt.StyleTemplate from PublishTemplate AS pt WITH INCLUDESUBCLASSES LEFT OUTER JOIN PublishStyleTemplate AS st WITH INCLUDESUBCLASSES ON pt.StyleTemplate = st.This WHERE (pt.IsCurrentVersion = true) AND (st.OutputFormat = 'application/pdf') ORDER BY pt.DateCreated"; SearchSQL sql = new SearchSQL(sqlStr); SearchScope ss = new SearchScope(objectStore); IEngineCollection ec = ss.FetchObjects(sql, null, null, true);
The PublishTemplate
class inherits its properties from the Document
class and adds two properties, Description and PublishStyleTemplate. The PublishStyleTemplate property references the PublishStyleTemplate
object used for source document content transformation, such as publishing to PDF or HTML formats. If the PublishStyleTemplate property value is not set, then no content transformation takes place; the content is simply copied to the destination with the designated properties and security defined in the publish template's content.
These examples create a new instance of a publish style template and store it in a Content Engine object store.
PublishStyleTemplate pst = Factory.PublishStyleTemplate.createInstance(objectStore); pst.set_Title("My New Publish Style Template"); StringList formats = Factory.StringList.createList(); formats.add("text/plain"); formats.add("text/richtext"); formats.add("application/msword"); formats.add("application/vnd.ms-excel"); formats.add("application/vnd.ms-powerpoint"); formats.add("application/vnd.wordperfect"); pst.set_InputFormats(formats); // Description is not a required property, just useful to set pst.set_Description("This is the HTML publish style template."); // ProviderID must use the well-known handler name String HTML_HANDLER = "PublishRequestHTMLHandler"; pst.set_ProviderID(HTML_HANDLER); pst.set_OutputFormat("text/html"); //HTML transformation pst.save(RefreshMode.NO_REFRESH);
IPublishStyleTemplate pst = Factory.PublishStyleTemplate.CreateInstance(objectStore); pst.Title = ("My New Publish Style Template"); IStringList formats = Factory.StringList.CreateList(); formats.Add("text/plain"); formats.Add("text/richtext"); formats.Add("application/msword"); formats.Add("application/vnd.ms-excel"); formats.Add("application/vnd.ms-powerpoint"); formats.Add("application/vnd.wordperfect"); pst.InputFormats = formats; // Description is not a required property, just useful to set pst.Description = ("This is the HTML publish style template."); // ProviderID must use the well-known handler name string HTML_HANDLER = "PublishRequestHTMLHandler"; pst.ProviderID=(HTML_HANDLER); pst.OutputFormat=("text/html"); //HTML transformation pst.Save(RefreshMode.NO_REFRESH);
To retrieve a specific PublishStyleTemplate
object from an object store, you can fetch an instance using the publish style template's ID, as shown in the examples below. You can also call SearchScope.fetchObjects
to retrieve a PublishStyleTemplates
collection that contains the style templates available in an object store. These examples show how to retrieve all of the publish style templates in the object store.
PublishStyleTemplate pst = Factory.PublishStyleTemplate.fetchInstance(objectStore, new Id("{83BE27ED-9688-4522-B78C-01B6A2EB51A6}"), null); String sqlStr = "Select * from PublishStyleTemplate"; SearchSQL sql = new SearchSQL(sqlStr); SearchScope ss = new com.filenet.api.query.SearchScope(objectStore); EngineCollection ec = ss.fetchObjects(sql, null, null, Boolean.TRUE);
IPublishStyleTemplate pst = Factory.PublishStyleTemplate.FetchInstance(objectStore, new Id("{83BE27ED-9688-4522-B78C-01B6A2EB51A6}"), null); string sqlStr = "Select * from PublishStyleTemplate"; SearchSQL sql = new SearchSQL(sqlStr); SearchScope ss = new SearchScope(objectStore); IEngineCollection ec = ss.FetchObjects(sql, null, null, true);
The PublishStyleTemplate
class inherits its properties from the CustomObject
class and adds a number of other properties. The following table summarizes these PublishStyleTemplate
-specific properties. For more information on each of the PublishStyleTemplate
object's properties, see
PublishStyleTemplate Properties.
Property | Settability | Description |
---|---|---|
Description | Read/Write | A string that is the description of the publish style template. |
InputFormats | Read/Write | A collection of strings that specify the input document MIME types for which a publish style template is valid. The format "*/*" indicates a style template applies to any input format. |
OutputFormat | Read/Write | A string that is the MIME type of output documents produced by the transformation engine when using this publish style template (for example, "text/html"). |
PDFMasterPassword | Read only | An encrypted string that represents the master password for a PDF rendition. |
PDFUserPassword | Read only | An encrypted string that represents the user password for a PDF rendition. |
ProviderID | Settable only On Create | A string that is the well-known provider ID supplied when the publish style template was created. The defaults are "PublishRequestPDFHandler" and "PublishRequestHTMLHandler" for PDF and HTML style templates, respectively. |
Title | Read/Write | A string that is the title of the publish style template. |
TransformationOptions | Read/Write | A binary property that contains an engine-specific description of the transformation to be done for this template. Currently used only in the PDF case to pass watermark, security, and other parameters to the transformation engine. The format of the data passed in this field is an XML string with transformation engine specific schema. |
You publish and republish a document by calling the publish
and republish
methods on the Document
object. Both operations return a PublishRequest
object that represents the queued request. You can query the PublishRequest
object's properties to obtain status information about the queued request. However, because the PublishRequest
object is deleted as soon as the publish operation completes, your query might get a "Requested item not found" exception if the operation has completed.
When you publish a document, you create a new publication from a source document. When the publish operation completes, the new publication will be the only version in a new version series, and is unrelated to any other publications derived from the source document. Also, the new publication is a major document version; with one exception, there is never a minor version of a publication. The exception is the case of a temporary reservation object, which is a minor version until it is automatically transformed into a major version when the publish operation is complete. The security applied to the new publication is specified in the publish template as one of the following: default security, source document security, destination folder security, or publish template-specified security.
To publish a document, call the publish
method on the Document
object that represents the source document. The publish
method takes a publish template as input. The publish template you specify, as well as any objects specified in the publish template's content, must reside on the same object store as the source Document
object.
The publish
method also has an optional publishOptions
parameter. You can pass in XML (representing the publish options) that overrides the publication name, output folder, and event action specified in the associated publish template. If the parameter is null
, the values for name, output folder, and event action default to those specified in the associated publish template. A sample of the XML is in the Publish Options XML topic and descriptions of the options are in the following list:
To successfully publish a document, the user must have appropriate access rights (AccessRight.PUBLISH
or AccessLevel.PUBLISH
). Also note that publishing to a document class containing a required binary- or object-valued property is not supported as there is no way to set these property values during publishing.
NOTE You can also publish documents from within a batch operation. For information about batch operations, refer to Batch Concepts.
The following code samples illustrate a publish operation:
// Define the publication name in XML format String publishOpts = new String("<publishoptions><publicationname>My New Title</publicationname><publishoptions>"); // Get a reference to the source document to publish String path = "/someFolder/My Source Document"; Document sourceDoc = Factory.Document.fetchInstance(objectStore, path, null); // Retrieve a collection of publish templates // (In a typical scenario, you might qualify the publish templates query to get the ones that can be applied.) String sqlStr = "Select * from PublishTemplate"; SearchSQL sql = new SearchSQL(sqlStr); SearchScope ss = new com.filenet.api.query.SearchScope(objectStore); EngineCollection ec = ss.fetchObjects(sql, null, null, Boolean.TRUE); Iterator iter = ec.iterator(); if (iter.hasNext()) { PublishTemplate pt = (PublishTemplate) iter.next(); // In this example, we'll use the first publish template. // Submit the publish request and return the PublishRequest object for this publish operation. PublishRequest pubReq = sourceDoc.publish(pt, publishOpts); pubReq.save(RefreshMode.REFRESH); }
// Define the publication name in XML format string publishOpts = ("My New Title"); // Get a reference to the source document to publish string path = "/someFolder/My Source Document"; IDocument sourceDoc = Factory.Document.FetchInstance(objectStore, path, null); // Retrieve a collection of publish templates // (In a typical scenario, you might qualify the publish templates query to get the ones that can be applied.) String sqlStr = "Select * from PublishTemplate"; SearchSQL sql = new SearchSQL(sqlStr); SearchScope ss = new SearchScope(objectStore); IEngineCollection ec = ss.FetchObjects(sql, null, null, true); foreach (IPublishTemplate pt in ec) { // In this example, we'll use the first publish template. // Submit the publish request and return the PublishRequest object for this publish operation. IPublishRequest pubReq = sourceDoc.Publish(pt, publishOpts); pubReq.Save(RefreshMode.REFRESH); }
You can directly create a PublishRequest
object to submit a publish request instead of
using the Document
object's publish method. As an example, you could replace the sourceDoc.publish
call from the examples above with the following code:
PublishRequest pubReq = Factory.PublishRequest.createInstance(objectStore); pubReq.set_InputDocument(sourceDoc); pubReq.set_PublishTemplate(pt); pubReq.setPublishOptions(publishOpts);
IPublishRequest pubReq = Factory.PublishRequest.CreateInstance(objectStore); pubReq.InputDocument = sourceDoc; pubReq.PublishTemplate = pt; pubReq.SetPublishOptions(publishOpts);
The republish function reprocesses an existing publication. The publish template that was previously used to produce the publication is reused. The publish template specifies:
To republish a document, call the republish
method on the Document
object that represents the source document. Input to the republish
method is an existing publication identifier and, just as for the publish
method, you can optionally specify publish options XML to override the publication name, output folder, and event action in the associated publish template. If you specify null
for the publishOptions
parameter, the values for publication name, output folder, and event action default to those specified in the associated publish template. A sample of the XML is in the Publish Options XML topic and descriptions of the options are in the following list:
publishOptions
parameter. See Event Actions for more information.The following code samples illustrate a republish operation:
// Get a reference to the source document to republish String path = "/SomeFolder/My Source Document"; Document sourceDoc = Factory.Document.fetchInstance(objectStore, path, null); // Retrieve a list of current publication documents for the source document DocumentSet pubDocs = sourceDoc.get_DestinationDocuments(); // Cycle through the publication documents // (In a typical scenario, you might check the publications and select one that you want to republish) Iterator iter = pubDocs.iterator(); if (iter.hasNext()) { // Get the next publication document Document pubDoc = (Document)iter.next(); // Define republished document name String publishOpts = new String("<publishoptions><publicationname>Republished Doc</publicationname></publishoptions>"); // Submit the republish request and return the PublishRequest object for this operation PublishRequest pubReq = sourceDoc.republish(pubDoc, publishOpts); pubReq.save(RefreshMode.REFRESH); }
// Get a reference to the source document to republish string path = "/SomeFolder/My Source Document"; IDocument sourceDoc = Factory.Document.FetchInstance(objectStore, path, null); // Retrieve a list of current publication documents for the source document IDocumentSet pubDocs = sourceDoc.DestinationDocuments; // Cycle through the publication documents // (In a typical scenario, you might check the publications and select one that you want to republish) foreach (IDocument pubDoc in pubDocs) { // Define republished document name string publishOpts = (""); // Submit the republish request and return the PublishRequest object for this operation IPublishRequest pubReq = sourceDoc.Republish(pubDoc, publishOpts); pubReq.Save(RefreshMode.REFRESH); } Republished Doc
Similar to the publish operation described above, you can republish by directly creating the PublishRequest
object, as shown below, instead of making the sourceDoc.republish
call:
PublishRequest pubReq = Factory.PublishRequest.createInstance(objectStore); pubReq.set_InputDocument(sourceDoc); pubReq.set_PublicationDocument(publication); pubReq.setPublishOptions(publishOpts);
IPublishRequest pubReq = Factory.PublishRequest.CreateInstance(objectStore); pubReq.InputDocument = sourceDoc; pubReq.PublicationDocument= publication; pubReq.SetPublishOptions(publishOpts);
To retrieve a specific PublishRequest
from an object store, you can fetch an instance using the publish request's ID.
PublishRequest pubReq = Factory.PublishRequest.fetchInstance(objectStore, new Id("{0048AE3D-0AE3-478B-B5BC-2256292EE2AE}"), null);
IPublishRequest pubReq = Factory.PublishRequest.FetchInstance(objectStore, new Id("{0048AE3D-0AE3-478B-B5BC-2256292EE2AE}"), null);
You can retrieve a PublishRequests
collection containing the publish requests available in an object store by calling SearchScope.fetchObjects
. For example, the following code first retrieves all publish requests in an object store and then retrieves publish requests of a specific type.
// Retrieve publish request collections public static void retrieveRequestCollections( ObjectStore objectStore) { // Retrieve all publish requests String sqlStr = "Select * from PublishRequest"; getPublishRequests(objectStore, sqlStr); // Retrieve all publish requests for the PDF handler that are currently in error state sqlStr = "Select pr.Id from PublishRequest AS pr " + "INNER JOIN PublishStyleTemplate AS st ON pr.PublishStyleTemplate = st.This WHERE " + "st.ProviderID = 'PublishRequestPDFHandler' AND pr.PublishingStatus = 3"; getPublishRequests(objectStore, sqlStr); } // Get publish requests public static void getPublishRequests( ObjectStore objectStore, String sqlStr) { // Retrieve publish requests SearchSQL sql = new SearchSQL(sqlStr); SearchScope ss = new com.filenet.api.query.SearchScope(objectStore); EngineCollection ec = ss.fetchObjects(sql, null, null, Boolean.TRUE); // Cycle through publish requests Iterator iter = ec.iterator(); if (iter.hasNext()) { // Get next publish request PublishRequest pubReq = (PublishRequest) iter.next(); // Get source document pubReq.fetchProperties(new String[] {PropertyNames.ID, PropertyNames.INPUT_DOCUMENT}); Document srcDoc = Factory.Document.fetchInstance(objectStore, pubReq.get_Id(), null); // Display the source document title and error description System.out.println("The publish request for " + srcDoc.get_Name() + "has the error: " + pubReq.get_ErrorCode() + " and is caused by " + pubReq.get_ErrorDescription() + "\n"); } }
// Retrieve publish request collections public static void RetrieveRequestCollections( IObjectStore objectStore) { // Retrieve all publish requests string sqlStr = "Select * from PublishRequest"; GetPublishRequests(objectStore, sqlStr); // Retrieve all publish requests for the PDF handler that are currently in error state sqlStr = "Select pr.Id from PublishRequest AS pr INNER JOIN PublishStyleTemplate AS st ON pr.PublishStyleTemplate = st.This WHERE st.ProviderID = 'PublishRequestPDFHandler' AND pr.PublishingStatus = 3"; GetPublishRequests(objectStore, sqlStr); } // Get publish requests public static void GetPublishRequests( IObjectStore objectStore, String sqlStr) { // Retrieve publish requests SearchSQL sql = new SearchSQL(sqlStr); SearchScope ss = new SearchScope(objectStore); IEngineCollection ec = ss.FetchObjects(sql, null, null, true); // Cycle through publish requests foreach (IPublishRequest pubReq in ec) { // Get source document string[] pn = { PropertyNames.ID, PropertyNames.INPUT_DOCUMENT }; pubReq.FetchProperties(pn); IDocument srcDoc = Factory.Document.FetchInstance(objectStore, pubReq.Id, null); // Display the source document title and error description Console.WriteLine("The publish request for " + srcDoc.Name + " has the error: " + pubReq.ErrorCode + " and is caused by " + pubReq.ErrorDescription + "\n"); } }
You can obtain information about a PublishRequest
by querying its
properties. The PublishRequest
class inherits some of its properties from other classes and adds several others. The following table summarizes these PublishRequest
-specific properties. For more information on each of the PublishRequest
object's properties, see PublishRequest Properties.
Property | Settability | Description |
---|---|---|
ErrorCode | Read only | A value that specifies the error state of a publish request. |
ErrorDescription | Read only | A string that describes the cause of a publish request error. |
InputDocument | Read/Write | A string that specifies the document to be used as input to the publishing operation. |
OutputFolder | Read/Write | A string that specifies the folder into which the output of the publishing operation (the publication document) is to be filed. |
PublicationDocument | Read/Write | A string that specifies the document to use if you are republishing an existing document and you have set the option to version the current document. |
PublishingStatus | Read only | A string that specifies the status of a publish request. |
PublishRequestType | Read only | An integer that indicates the type of publish request. |
PublishStyleTemplate | Read only | An object-valued property that contains a reference to the PublishStyleTemplate object associated with this publish request. |
PublishTemplate | Read/Write | An object-valued property that contains a reference to the PublishTemplate object associated with this publish request. (The value is null for a republish operation.) |
StatusDescription | Read only | A string that describes the status of this publish request. |