Represents an annotation that can be applied to a document, folder, or custom object. An Annotation object allows you to link additional information to a containable object. You can modify and delete annotations independently of their annotated object. However, you cannot create versions of an annotation separately from the object with which it is associated. Document annotations are uniquely associated with a single document version; they are not versioned or carried forward when their document version is updated and a new version created. By design, an annotation is deleted whenever its associated parent object is deleted. Although an annotation receives its default security from both the annotation's class and parent object, you can apply security to an annotation that is different from the security applied to its parent.

To create a new Annotation object and associate it with a document, use the document object's CreateAnnotation method. To create a new Annotation object and associate it with a folder or custom object, first use the Factory.Annotation.CreateInstance() method to create a new Annotation object, then set its AnnotatedObject property to reference the object to which you want it associated. An annotation's content data can be specified via its ContentElements collection.


The following tables list the members exposed by IAnnotation.

Public Properties

 NameDescription
Public propertyActiveMarkingsThe list of ActiveMarking objects currently applied to a given object. Each ActiveMarking object represents a marking that is in a MarkingSet associated with a property on the object.
Public propertyAnnotatedContentElementSpecifies the index of the document content element to which this annotation applies. This property is intended only as a means by which an application can match an annotation with a document content element. The server does not keep track of this property value nor does it enforce it for referential integrity.

Because the positional index of a given content element within a document's ContentElementList collection is subject to change, it is recommended that you populate this property with the value of the content element's ElementSequenceNumber property rather than its positional index. The value of the ElementSequenceNumber property is server-generated and provides a unique and unchanging number for a given content element. Because the number of content elements of a document is variable, if you choose to use a positional index it is up to your application to ensure that it accurately reflects the correct index of the content element to which the annotation applies. For example, if the AnnotatedContentElement property specifies the positional index of the third content element of a document with five content elements, and the second content element is then removed, the property will consequently reference the wrong content element.

Public propertyAnnotatedObjectSpecifies an IndependentObject object of type Document, Folder, or CustomObject to which this annotation has been applied.
Public propertyAuditedEventsAn EventSet collection of the Event objects containing the audited events that have occurred for the object.
Public propertyContentElementsSpecifies 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 propertyContentElementsPresentSpecifies a StringList object containing the MIME type of each content element
Public propertyContentSizeSpecifies 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 propertyCreatorIndicates the name of the user assigned as the creator of the object.

Settability of this property is read-only for most users. For users who have been granted privileged write access (AccessRight.PRIVILEGED_WRITE), this property is settable only on create. After initial object creation, this property is read-only for all users.

Public propertyDateContentLastAccessedSpecifies 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 propertyDateCreatedIndicates the date and time the object was created. The Content Engine stores dates and times using Coordinated Universal Time (UTC).

Settability of this property is read-only for most users. For users who have been granted privileged write access (AccessRight.PRIVILEGED_WRITE), this property is settable only on create. After initial object creation, this property is read-only for all users.

Public propertyDateLastModifiedIndicates the date and time the object was last modified. The Content Engine stores dates and times using Coordinated Universal Time (UTC).

Settability of this property is read-only for most users. For users who have been granted privileged write access (AccessRight.PRIVILEGED_WRITE), this property is read/write. (The read/write access for those users can only change if a change is made to the ACL on the object store that controls who has privileged write access to objects in that object store).

Public propertyDescriptiveTextUser-readable text that describes an object.

The text is not locale-specific to the retrieving user except for the following classes:

  • ClassDescription
  • PropertyDescription*
  • ClassDefinition
  • PropertyTemplate*
  • PropertyDefinition*
Public propertyIdA representation of the Globally Unique Identifier (GUID), a unique 128-bit number, that is assigned to this Content Engine object when the object is created. When converted to a string, the Id property is typically depicted as 32 hexadecimal characters enclosed by brackets in the following format: {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}. For example, {3F2504E0-4F89-11D3-9A0C-0305E82C3301}.

For IUser and IGroup classes, the Id property takes the value of the Security Identifier (SID) rather than the 128-bit GUID. The string representation of the SID is in this example format: S-1-5-21-1559522492-2815155736-3711640725-55269. When Active Directory is used as the directory service for IBM FileNet P8, IUser.Id and IGroup.Id always return the current SID for the principal, even if this user or group has only historical SIDs populating the Active Directory server.

For a given property representation, the Id property has the following characteristics:

  • PropertyDescription.Id is equal to PropertyTemplate.Id, which is equal to PropertyDefinition.PrimaryId.
  • PropertyDefinition.Id is not equal to PropertyDefinition.PrimaryId.
  • PropertyDefinition.Id is not equal to PropertyDescription.Id.

For a newly created document object, you can override the Id property of its associated VersionSeries object before you save or check in the document for the first time.

Public propertyIndexationIdThe 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 propertyLastModifierIndicates the name of the user who last modified the object.

Settability of this property is read-only for most users. For users who have been granted privileged write access (AccessRight.PRIVILEGED_WRITE), this property is read/write. (The read/write access for those users could only change if a change is made to the ACL on the object store that controls who has privileged write access to objects in that object store).

Public propertyMimeTypeSpecifies 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 propertyNameThe name for this object.

For most classes, this property is read-only and returns the value of the designated name property for the object, or its ID if there is no name property. If ClassDescription.NamePropertyIndex has a value, this property contains the value of the designated name property. If there is no designated name property value, and the object has an Id property, this property contains the string value of the Id property. If neither of these conditions is satisfied, this property contains an empty string.

For a ComponentRelationship object, this property is read/write and specifies the name of the object.

Public propertyOwnerManages the security owner assigned to the object.
Public propertyPermissionsManages the discretionary permissions assigned to the object.
Public propertyStorageAreaSpecifies the storage area for a content-carrying object.
Public propertyStorageLocationSpecifies 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 propertyStoragePolicySpecifies 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.

Top

Public Methods

 NameDescription
Public methodAccessContentStreamObtains 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 methodChangeClassChanges the class of a Content Engine object. The new class must already exist and both it and the original class must be subclasses of the same base class. The ChangeClass method does not modify the security for an object, even if the object's current security is derived from the default security for its source class. For the object's user-defined properties, the following rules apply:
  • Any user-defined properties that exist in the new class but not in the original class are set to the default value defined by the new class (or to null if there is no default defined).
  • Any user-defined properties that exist in both the original and the new class that are writable and have the same value (including null) as the default value defined in the original class will be set to the default value defined by the new class. However, any user-defined property that has had its value modified from the default value will retain that modified value in the new class.
  • Any user-defined properties whose definitions exist in the original class but not in the new class will no longer exist on the object when its class is changed.

When the class of a document object is changed, the default document lifecycle policy of the new class will only be applied to the document object's DocumentLifecyclePolicy property if both of the following scenarios occur:

  • The document has no current lifecycle policy.
  • The document is either a reservation object, or is the current version object and is not reserved.

Public methodMoveContentMoves the content data of an object to a new storage area.
Top

See Also