Represents a single version of a document stored in an object store. In addition to being versionable, a Document object can be subclassed and can carry content, which is stored in one or more content elements. Each content element represents content data, which can either be local to an object store (represented by a ContentTransfer object) or external to an object store and therefore outside the control of the Content Engine server (represented by a ContentReference object). In addition, a Document object can be associated with a document lifecycle policy. A document lifecycle policy defines a set of valid lifecycle states for a document, controls the transition of those states, and specifies the actions to be taken when a document's lifecycle state changes.


The following tables list the members exposed by IDocument.

Public Properties

  Name Description
Public property ChildDocuments A DocumentSet collection object that contains the child Document objects bound to this parent document. The collection contains only those child documents for which the user has read access. For each ComponentRelationship object that references this document as the parent component document, the collection contains the version of the child component document that is bound to this parent document. The same child document can be in the collection more than once.

For information on the ordering of the collection, see the ComponentSortOrder property.

Public property ChildRelationships A ComponentRelationshipSet collection object that contains the ComponentRelationship objects referencing this document as the parent component document.

For information on the ordering of the collection, see the ComponentSortOrder property.

Public property ClassificationStatus Specifies a DocClassificationStatus constant that indicates the auto-classification status for this document. The ClassificationStatus property is used to provide client applications a means of discovering whether a particular

document is subject to auto-classification, and if so, whether or not the operation was successful. This property can hold one of the following values:

  • CLASSIFICATION_COMPLETE: Indicates that document auto-classification has completed successfully.
  • CLASSIFICATION_FAILED: Indicates that document auto-classification has failed.
  • CLASSIFICATION_PENDING: Indicates that a request for document auto-classification is pending. This value is set automatically by the server when you check in a document and set the Checkin method's autoClassify parameter to AUTO_CLASSIFY.
  • NOT_CLASSIFIED: Indicates that document auto-classification has not been requested. This value is set automatically by the server when you check in a document and set the Checkin method's autoClassify parameter to DO_NOT_AUTO_CLASSIFY.

Public property CompoundDocumentState The setting that determines whether a document can be a parent component in a compound document. The CompoundDocumentState enumeration has constants defined for the compound document state settings.

Valid settings are:

  • COMPOUND_DOCUMENT: Designates the document as the parent component in a compound document. Initially, this parent document has no child components. A document must be designated as a compound document to become a parent component for a ComponentRelationship object.
  • STANDARD_DOCUMENT(default setting - 4.0.x release): Designates the document as a standard document. This setting prevents the document from being a parent component within a compound document. A document cannot be designated as a standard document when referenced as a parent component by a ComponentRelationship object.
  • null (default setting - 3.5.x upgraded to 4.0.x): Designates the document as a standard document. By default, pre-existing documents in an object store upgraded to 4.0.x return a null value instead of STANDARD_DOCUMENT. Note that, although a null value can be returned, you cannot set this property to null.
Public property ContentElements Specifies a ContentElementList object containing the list of content elements associated with this document or annotation. Each content element represents content data, which can either be local to an object store and stored in a file store or database (represented by a ContentTransfer object) or external to an object store and therefore outside the control of the Content Engine server (represented by a ContentReference object).
Public property ContentElementsPresent Specifies a StringList object containing the MIME type of each content element
Public property ContentRetentionDate Specifies the date until which this checked-in document must be retained, as determined by the content storage subsystem. This document can be deleted only after this date has passed.
Public property ContentSize Specifies the size in bytes of the content data associated with this document, annotation, or ContentTransfer object. Note that if the document or annotation has more than one content element, then the size is the sum of all of the content elements.
Public property CurrentState Specifies the name of the current lifecycle state of this document as defined by its document lifecycle policy. Each document lifecycle policy defines a set of states through which a StateName property of the DocumentState object representing the document can transition into during its lifecycle. This property is equal to the value of the current lifecycle state of this document.
Public property DateContentLastAccessed Specifies the date and time when the content data (represented by a ContentTransfer object) associated with this document or annotation was last accessed. The Content Engine stores dates and times using Coordinated Universal Time (UTC). The recording granularity of the date and time returned by this property is determined by the setting of the object store's ContentAccessRecordingLevel property. The content data associated with a document or annotation object is considered to be accessed when one of the following events occur:
  • An object's Refresh method is called with the property filter set to refresh PropertyContent properties (FilteredPropertyType.CONTENT_DATA).
  • An object's AccessContentStream method is called to retrieve content data in an input stream.
Each of these events will update the date of the DateContentLastAccessed property. Note that even if the content data is larger than the user-specified chunk size and multiple trips to the database or cache are required, the DateContentLastAccessed property will be set only to the date and time that the content data was first accessed. Applications that access content data frequently will cause continual updates of the DateContentLastAccessed property by the server, which can result in degraded performance. Therefore, it is recommended that you set the ContentAccessRecordingLevel property to control the frequency that the DateContentLastAccessed property is updated.
Public property DependentDocuments Specifies a DocumentSet collection object that contains all of the publication documents to which this document is the owner document.
Public property DestinationDocuments Specifies documents that are publications of this document. This property is a reflective property of the SourceDocument property.
Public property DocumentLifecyclePolicy Specifies the DocumentLifecyclePolicy object that represents the lifecycle policy that has been applied to this document. A document lifecycle policy defines a set of valid lifecycle states for a document, controls the transition of those states, and specifies the actions to be taken when a document's lifecycle state changes.
Public property IndexationId The object ID (GUID) of the Verity collection used. This will be null for objects that were full text indexed prior to the 4.0 release.

This property must be set if the property is to be CBR enabled (the PropertyDefinitionString.IsCBREnabled property).

Public property IsInExceptionState Specifies whether the lifecycle state of this document is in an exception state (true) or not (false). As long as a document is in an exception state, its lifecycle state can neither be promoted nor demoted. To clear a document from an exception state, you must call its ChangeState method and set the LifecycleChangeFlags parameter to CLEAR_EXCEPTION.
Public property MimeType Specifies the Multipurpose Internet Mail Extensions (MIME) format string of the content data carried by this document, annotation, or document classification action.

For Document objects, you can set the MimeType property for a specific document version while it is a reservation object (at creation time and on subsequent check-outs). However, every time you check in a document, its MimeType property value reverts to its system-assigned value unless you explicitly set it again.

For Annotation objects, you can set this property at any time.

For DocumentClassificationAction objects, the MimeType property specifies the type of content that a document must hold in order to allow it to be auto-classified; you can set this property at any time.

Each content element that is attached to a document or annotation has its own MIME type, which is specified by its ContentType property. If you do not set the MimeType property for a document or annotation, it is automatically set by the Content Engine according to the value of each content element's ContentType property and according to the following logic:

  • If the object contains one or more ContentTransfer objects that all have the same value for their ContentType property, MimeType is set to the value of the ContentType property.
  • If the object contains a single ContentReference object, MimeType is set to "application/x-filenet-external".
  • If the object contains multiple ContentReference objects (but no ContentTransfer objects), MimeType is set to "multipart/x-filenet-external".
  • Otherwise, MimeType is set to "multipart/mixed".

MIME is a communications protocol that allows for the transmission of data in many forms, such as audio, binary, or video. A MIME format string consists of a content type, a content subtype, and an optional parameter in the format: "MIME::content type/subtype[;parameter]". For example: "MIME::text/html". MIME defines the following content types:

  • text: Represent textual information in a number of character sets. A charset parameter may be used (for example, "MIME::text/plain;charset=us-ascii"). Some subtypes: plain, html, richtext.
  • image: Represents still images. Some subtypes: jpeg, gif.
  • audio: Represents audio or voice data. Some subtypes: wav, au.
  • video: Represents video data or moving-image data. Some subtypes: mpeg, mp4.
  • message: Encapsulates an entire formatted message. Some subtypes: rfc822, partial, external-body.
  • multipart: Combines several body parts of potentially different types and subtypes. Some subtypes: mixed, alternative, parallel, digest.
  • application: Represents application data (such as executables) or binary data.

The following MIME types are specific to FileNet:

  • application/x-filenet-declarerecordtemplate: Record template.
  • application/x-filenet-documentassembly: Document assembly.
  • application/x-filenet-external: An object that contains a single ContentReference content element.
  • application/x-filenet-external-is: External Image Services document.
  • application/x-filenet-publishtemplate: Publish template.
  • application/x-filenet-scenariodefinition: Scenario definition document.
  • application/x-filenet-search: Stored search.
  • application/x-filenet-searchtemplate: Search template.
  • application/x-filenet-workflowdefinition: Workflow definition document.
  • multipart/x-filenet-external: An object that contains multiple ContentReference content elements only.
Public property OwnerDocument For a published document, contains a reference to the Document object representing the owner document associated with the published document. If this document is a publication and there is a cascade delete relationship with the source, then this property will specify the publication source document (the OwnerDocument and PublicationSource properties will reference the same document).
Public property ParentDocuments A DocumentSet collection object that contains the parent Document objects bound to this child document. The collection contains only those parent documents for which the user has read access. For each ComponentRelationship object that references this document as the child component document, the collection contains the parent component document. The same parent document can be in the collection more than once.
Public property ParentRelationships A ComponentRelationshipSet collection object that contains the ComponentRelationship objects referencing this document as the child component document. The collection contains only those parent relationship objects for which the user has read access.
Public property PublicationInfo Specifies the parameters (formatted as XML) that were used to publish a document. The parameters, which are used to republish the document, include the original output folder ID, style template ID, publish template ID, and publish template version series ID. For example:
 Copy Code
             <publicationinfo>
               <styletemplateid>{14917CF3-4D5F-499D-BA38-8E010199745E}</styletemplateid>
               <publishtemplateid>{4D696690-EEBB-4341-9FE7-A8F715BAE96D}</publishtemplateid>
               <pubtemplversionseriesid>{459A0D5A-5B44-4AD1-B15C-91D7B773B3DD}</pubtemplverseriesid>
               <outputfolderid>{4EF26F2E-61D8-47FD-8201-EE81C3AA75FA}</outputfolderid>
             </publicationinfo>
             

If the document is not a publication, the property is empty.

Public property PublishingSubsidiaryFolder Specifies a folder which contains the subsidiary documents of an HTML publication (for example, image, audio, and style sheet files).
Public property ReleasedVersion Specifies a document version that represents the latest released version associated with this document or version series. A released version is a major version that has a VersionStatus property value of RELEASED. Note that only one document version at a time in a given version series can be in the released state.
Public property SecurityParent Obsolete. Specifies the object from which a given object inherits security. The value of this property is a ReferentialContainmentRelationship (or DynamicReferentialContainmentRelationship) that represents the object from which security is inherited.

An object can inherit its permissions from its security parent. For example, a Document object can inherit the permissions of the Folder in which it is filed. A Folder object always inherits its permissions from its parent folder. An object's security parent is reflected in the value of its SecurityParent property. You can explicitly set the security parent of an object at the time it is filed into a folder by specifing the defineSecurityParentage parameter of the Folder.File method.

Public property SourceDocument Specifies the source document for a published document.
Public property StorageArea Specifies the storage area for a content-carrying object.
Public property StorageLocation Specifies the storage location for an object's content. This property is deprecated in FileNet P8 4.0 and is only set in upgraded object stores. It has been replaced by the StorageArea property.
Public property StoragePolicy Specifies the document's storage policy, which identifies the set of available storage areas that are considered equivalent based on common, user-specified criteria. Assigning a storage policy to a document is the recommended method of selecting a storage area. The alternative is to directly assign the storage area (specify the StorageArea property).

When a document is created, the order of precedence for setting the storage on the Document instance is (from highest to lowest):

  • instance value for the StorageArea property
  • class default for the StorageArea property
  • instance value for the StoragePolicy property
  • class default for the StoragePolicy property

The default ClassDefinition for a document sets the StorageArea to "Database Storage Area" and the StoragePolicy to "All Storage Areas". Therefore, if you create a new Document instance of the default Document ClassDefinition with only the StoragePolicy property set, the document will use the class default for the StorageArea property (Database Storage Area).

To avoid this situation, you must set the instance value for the document's StorageArea property to null. Because the instance value for StorageArea is set, but has no value, the StoragePolicy property will be evaluated and used.

In general, storage policies should be used to allow administrators to properly administer their storage systems. They can assign multiple storage areas to be load balanced, and also assign standby storage areas to be used if any of the current storage areas become full.

Public property WorkflowSubscriptions The IInstanceWorkflowSubscriptionSet object containing the IInstanceWorkflowSubscription objects whose target is this object.
Top

Public Methods

  Name Description
Public method AccessContentStream Obtains read access, via an input stream, to the content data of a ContentTransfer content element associated with this document or annotation. If content data is not present in the object’s property cache, it will be fetched from the server. The Content Engine will not automatically close the stream after access has finished; unless you want the stream to remain open, your application should close the stream after it has finished reading the content data. An error occurs if the element parameter specifies an invalid index, no content elements exist on this document or annotation, or the content element is not a ContentTransfer object.
Public method ApplySecurityTemplate Applies a security policy template to the given object. The specified value for the applyStateId parameter must match the value of the ApplyStateID property of one of the templates in the security policy for the object. For a versioning security template, the apply state ID can be one of the following:
  • VersionStatusId.IN_PROCESS
  • VersionStatusId.RELEASED
  • VersionStatusId.RESERVATION
  • VersionStatusId.SUPERSEDED
For an application security template, the apply state ID is defined by your application.
Public method ChangeState Changes the current lifecycle state of this document. Note that you cannot change the state of a document that is a reservation object. Valid lifecycle states are defined by the collection of DocumentState objects belonging to this document's associated DocumentLifecyclePolicy object. You can change a document's current lifecycle state to another predefined state, place a document into the exception state, or remove a document from the exception state by specifying a LifecycleChangeFlags constant in the LifecycleChangeFlags parameter as follows:
  • PROMOTE: Promotes the document's current lifecycle state to the next state in its document lifecycle policy and sets the document's CurrentState property to the name of the next state. Throws an error if the document is in the exception state, in the first state of its lifecycle, or does not allow demotion.
  • DEMOTE: Demotes the document's current lifecycle state to the previous state in its document lifecycle policy and sets the document's CurrentState property to the name of the previous state, unless the CanBeDemoted property of the document’s current state (DocumentState object) is set to false. Throws an error if the document is in the exception state or in the first state of its lifecycle.
  • SET_EXCEPTION: Places the document into the exception state and sets its IsInExceptionState property to true. Throws an error if the document's IsInExceptionState property is already set to true.
  • CLEAR_EXCEPTION: Removes the document from the exception state and sets its IsInExceptionState property to false. Throws an error if the document's IsInExceptionState property is already set to false.
  • RESET: Resets the lifecycle state to the initial state in its document lifecycle policy and sets the document's CurrentState property to the name of the initial state. Throws an error if the document is in the exception state.
Public method Checkin Checks in this document reservation object by saving it as a new document version. You must have the appropriate access rights to check in a document (MAJOR_VERSION to check it in a major version or MINOR_VERSION to check it in a minor version). A major version is either the current released document version (if it is the latest major version) or a former released version that was superseded. A minor version is either the in-process document version (if it is the latest minor version) or a former in-process version that was superseded. In addition, if the reservation object is an exclusive reservation (its ReservationType property is set to EXCLUSIVE), you must be the reservation owner (the reservation owner's name is the value of the reservation object's Creator property) or have the WRITE_OWNER access right. An error will occur if this method is called by a document that is not a reservation object.

Before you can check in a document that has content, you must set the content for the document by adding to its ContentElements collection one or more ContentTransfer objects if the content is stored in a Content Engine object store, or one or more ContentReference objects if the content is stored externally. If you do not want the Content Engine to assign a MIME type to the checked-in document, you must explicitly set the value of the document's MimeType property before calling the Checkin method. After a successful check-in, the reservation object becomes the new current version of the document (its IsCurrentVersion property is set to true). During a minor version check-in, the new minor document version is marked as in-process (its VersionStatus property is set to IN_PROCESS) and the previous in-process minor document version (if it exists) is marked as superseded (its VersionStatus property is set to SUPERSEDED). During a major version check-in, the new major document version is marked as released (its VersionStatus property is set to RELEASED) and the previous released major document version and in-process minor document version (if they exist) are marked as superseded.

The checkinType parameter specifies whether to check in a document as a minor or a major version; set it to MINOR_VERSION to check in a minor version, or MAJOR_VERSION to check in a major version. The autoClassify parameter specifies whether the document should have automatic document classification enabled. (This feature is not supported for publish templates.) If set to AUTO_CLASSIFY, and if a classifier exists for the document's content type, the document will automatically be assigned the proper document class and its properties will be populated based on the document content (and, in the case of XML document classification, mapping rules from user-defined scripts). The Content Engine's classification service uses a document's MIME type to determine if there is a classifier capable of parsing the document. If you set the autoClassify parameter to AUTO_CLASSIFY, the check-in operation changes the value of the document's ClassificationStatus property to CLASSIFICATION_PENDING; if you set it to DO_NOT_AUTO_CLASSIFY, the property is set to NOT_CLASSIFIED.

Public method GetPublicationStatus Returns a PublicationStatus enumeration value, which identifies the document's publication status (dependent, independent, or not a publication). A PublicationStatus object.
Public method IsLocked Queries this object's lock state. This helper method examines the object's lock-related properties and determines the object's lock state. An alternative approach is to call the LockObject method and handle any exception thrown if the method fails.

Note that this method returns an approximation of the locked state at the time of the call. Once this method executes and returns the value, the object's lock state could be immediately changed by another application's call to the LockObject method or the lock could expire.

Before calling this method, make sure that the object's LockToken, LockTimeout, and DateLastModified properties have relatively fresh values. If any of those properties is missing, they are silently fetched from the server and added to the object's property cache.

The IsLocked method returns False if the LockTimeout property is not set or if the lock has expired. The lock is determined to be expired if the DateLastModified property value plus the number of seconds specified by the LockTimeout property is less than the current system time. (All millisecond components are dropped from the calculation.) If the DateLastModified property is not set, this method returns False because the check against the lock timeout value or the lock token will reflect that the object is not locked. As soon as some action locks the object, the DateLastModified property will be updated and can then be used for the expiration calculation.

Note: Note: To successfully run IsLocked and other cooperative locking methods, system clocks on the IBM FileNet P8 platform engine machines must be synchronized. The calculation performed by the IsLocked() method is done on the client system. If the client and server machine clocks are not synchronized, the result of this calculation might be incorrect.

Public method LockObject Sets a new lock or updates an existing lock on the object. Calling this method has no effect in preventing others from updating a locked object (with the exception that others cannot re-lock the locked object). This lock mechanism is used for custom purposes only and has no bearing on the actual ability to update an object.

To successfully execute this method, the current user must have permission to modify this object's properties. For example, locking a Document object requires AccessLevel.WRITE_DOCUMENT.

If the call succeeds:

  • The object's LockOwner property is populated with the user name specified in the owner parameter. (New lock only.)
  • The value specified by timeoutis applied to the object's LockTimeout property.
  • A LockToken (GUID) is internally created by the server. (New lock only.)

To update an existing lock, the objects needs to be in the locked state and the current user needs to match the user of the lock. Note that the user is the logged in user, not the owner string. If the call succeeds, then only the LockTimeout property is updated with the timeout value. The owner parameter in this case is ignored. (See the UpdateLock() method instead.)

Public method MoveContent Moves the content data of an object to a new storage area.
Public method Publish Publishes this Document object according to the specifications included in the specified publish template as modified by the contents of the publishOptions parameter. This method returns the PublishRequest object that is queued for this request. All publish requests are asynchronous, including copy operations, which do not transform the document. A publish request is always enqueued, and a copy of the PublishRequest object is always returned to the caller.

The publish template you specify, as well as any objects specified in the publish template itself, must reside on the same object store as this Document object. 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 publishOptions parameter is a string containing XML that specifies the publish options for the published document. See Publish Options XML for more information.

After a successful call to publish, call the Save method of the returned PublishRequest object to submit the request to the publish queue.

Public method Republish Republishes the specified published document. The specified published document must have been published with a publish template that still exists and had this Document object as its source document. This method returns the PublishRequest object that is queued for this request. All publish requests are asynchronous, including copy operations, which do not transform the document. A publish request is always enqueued, and a copy of the PublishRequest object is always returned to the caller.

The publishOptions parameter is a string containing XML that specifies the publish options for the republished document. See Publish Options XML for more information.

Public method TakeFederatedOwnership For a document that has been federated by Content Federation Services (CFS), grants exclusive control of this document to the FileNet P8 Content Engine by making the corresponding external document read-only. (Since the external document ceases to change, no changes exist for CFS to propagate from the external repository to the Content Engine, and the Content Engine becomes the sole means for modifying or deleting the document.) For non-federated documents or for documents for which this method has already been called, this method has no effect. An error is generated if this document is a reservation object (VersionStatus property is set to RESERVATION).
Public method Unlock Explicitly removes the lock from this object. Only the user who locked the object may remove the lock. If the current user is not the user of the lock, the current user can still remove the lock provided that user has AccessRight.WRITE_ACL permission on the object. An exception is thrown if the above conditions are not met. Upon successful execution of this method, the values for the object's LockOwner, LockToken, and LockTimeout properties are removed (set to null). If you do not call Unlock to explicitly remove the lock, the lock is implicitly removed when the lock's timeout value expires. If the object is not locked (absence of a LockToken).
Public method UpdateLock Adjusts the timeout period of the lock on this object.

This method updates the object's DateLastModified property to the current time and its LockTimeout property to the timeout value. The net effect of this may extend or shorten the original lock's expiration time. Only the user who locked the object can successfully call this method; for any other user, an exception is thrown. There is no limit to the number of times you can call this method.

Top

See Also