Working with Publishing Objects

Creating a PublishTemplate 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.

Java™ Example

// 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 specifies 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);

C# Example

// 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 specifies 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); 

Retrieving a PublishTemplate Object

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.

Java Example

// 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);

C# Example

// 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);

Working with PublishTemplate Properties

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.

Creating a PublishStyleTemplate Object

These examples create a new instance of a publish style template and store it in a Content Engine object store.

Java Example

PublishStyleTemplate pst = Factory.PublishStyleTemplate.createInstance(objectStore);
pst.set_Title("My New Publish Style Template");

StringList formats = Factory.StringList.createList();
formats.add("application/msword");
formats.add("application/vnd.ms-excel");
formats.add("application/vnd.ms-powerpoint");
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);

C# Example

IPublishStyleTemplate pst = Factory.PublishStyleTemplate.CreateInstance(objectStore);
pst.Title = ("My New Publish Style Template");

IStringList formats = Factory.StringList.CreateList();
formats.Add("application/msword");
formats.Add("application/vnd.ms-excel");
formats.Add("application/vnd.ms-powerpoint");

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);

Retrieving a PublishStyleTemplate Object

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.

Java Example

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);

C# Example

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);

Working with PublishStyleTemplate Properties

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.

Publishing and Republishing a Document

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.

Publication Using the Document Object

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:

• A name for the new publication, specified in the publicationname element.
• The output folder into which the published document is filed, specified as either the folder name (in the outputfoldername element) or its ID (in the outputfolderid element). No more than one name or ID can be specified. Including the output folder name or ID in the string overrides the output folder specified in the publish template.
• The event action to trigger when the publish operation completes, specified as either the event action name (in the event actionname element) or its ID (in the eventactionid element). No more than one name or ID can be specified. Including the event action name or ID in the string overrides the event action (if any) specified in the publish template. If the publish template specifies an event action and none is desired, include an eventactionname node with no name specified in the publishOptions parameter. See Event Actions for more information.

To successfully publish a document, the user must have the AccessRight.PUBLISH permission. 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.

The following code samples illustrate a publish operation:

Java Example

// 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);
}

C# Example

// 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);
}
  

Publication Using the PublishRequest Object

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:

Java Example

PublishRequest pubReq = Factory.PublishRequest.createInstance(objectStore);
pubReq.set_InputDocument(sourceDoc);
pubReq.set_PublishTemplate(pt);
pubReq.setPublishOptions(publishOpts);

C# Example

IPublishRequest pubReq = Factory.PublishRequest.CreateInstance(objectStore);
pubReq.InputDocument = sourceDoc;
pubReq.PublishTemplate = pt;
pubReq.SetPublishOptions(publishOpts);
 

Republication Using the Document Object

The republish function reprocesses an existing publication. The publish template that was previously used to produce the publication is reused. The publish template specifies:

• Whether to version the existing publication (which results in a new version in the version series of the existing publication) or create a new one (which results in an entirely new publication with its own version series).
• Whether the existing publication version should be deleted or retained.
• One of five options for applying security: use the security of the existing publication that is being republished, or use one of the options previously specified for the publish operation: default security, source document security, destination folder security, or publish template-specified security.

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:

• A name for the republished document, specified in the publicationname element.
• The output folder into which the republished document is filed, specified as either the folder name (in the outputfoldername element) or its ID (in the outputfolderid element). No more than one name or ID can be specified. Including the output folder name or ID in the string overrides the output folder specified in the publish template. The value is ignored if the existing publication is being versioned. The new version will be filed in the same folder as the existing version.
• The event action to trigger when the republish operation completes, specified as either the event action name (in the event actionname element) or its ID (in the eventactionid element). Note that the event action does not need to be the same event action (if any) specified when the document was initially published. No more than one name or ID can be specified. Including the event action name or ID in the string overrides the event action (if any) specified in the publish template. If the publish template specifies an event action and none is desired, include an eventactionname node with no name specified in the publishOptions parameter. See Event Actions for more information.

The following code samples illustrate a republish operation:

Java Example

// 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);
}   

C# Example

// 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 = ("<publishoptions><publicationname>Republished Doc</publicationname></publishoptions>");

   // Submit the republish request and return the PublishRequest object for this operation
   IPublishRequest pubReq = sourceDoc.Republish(pubDoc, publishOpts);
   pubReq.Save(RefreshMode.REFRESH);                
}
 

Republication Using the PublishRequest Object

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:

Java Example

PublishRequest pubReq = Factory.PublishRequest.createInstance(objectStore);

pubReq.set_InputDocument(sourceDoc);
pubReq.set_PublicationDocument(publication);
pubReq.setPublishOptions(publishOpts);  

C# Example

IPublishRequest pubReq = Factory.PublishRequest.CreateInstance(objectStore);

pubReq.InputDocument = sourceDoc;
pubReq.PublicationDocument= publication;
pubReq.SetPublishOptions(publishOpts);

Retrieving a PublishRequest Object

To retrieve a specific PublishRequest from an object store, you can fetch an instance using the publish request's ID.

Java Example

PublishRequest pubReq = Factory.PublishRequest.fetchInstance(objectStore, new Id("{0048AE3D-0AE3-478B-B5BC-2256292EE2AE}"), null); 

C# Example

IPublishRequest pubReq = Factory.PublishRequest.FetchInstance(objectStore, new Id("{0048AE3D-0AE3-478B-B5BC-2256292EE2AE}"), null);

Retrieving a PublishRequest Collection

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.

Java Example

// 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");
    }
}

C# Example

// 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");
    }
}

Working with PublishRequest Properties

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.