Working with Documents

This topic provides the following document-related code examples:

Other document-related tasks that are described elsewhere in this guide include:

Creating a Document

This example creates a document. The properties MimeType, DocumentTitle, and StorageArea are set, but this is not required.

Java Example

// Create a document instance
Document doc = Factory.Document.createInstance(os, ClassNames.DOCUMENT);

// Set document properties
doc.getProperties().putValue("DocumentTitle", "New Document via Java API");
doc.set_MimeType("text/plain");

StorageArea sa = Factory.StorageArea.getInstance(os, new Id("{DE42374D-B04B-4F47-A62E-CAC9AC9A5719}") );
doc.set_StorageArea(sa);

doc.save(RefreshMode.NO_REFRESH );

// Check in the document
doc.checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION);
doc.save(RefreshMode.NO_REFRESH);

// File the document
Folder folder = Factory.Folder.getInstance(os, ClassNames.FOLDER,
        new Id("{42A3FC29-D635-4C37-8C86-84BAC73FFA3F}") );
ReferentialContainmentRelationship rcr = folder.file(doc,
        AutoUniqueName.AUTO_UNIQUE, "New Document via Java API",
        DefineSecurityParentage.DO_NOT_DEFINE_SECURITY_PARENTAGE);
rcr.save(RefreshMode.NO_REFRESH);

C# Example

// Create a document instance
IDocument doc = Factory.Document.CreateInstance(os, ClassNames.DOCUMENT);

// Set document properties
doc.Properties["DocumentTitle"] = "New Document via .NET API";
doc.MimeType = "text/plain";

IStorageArea sa = Factory.StorageArea.GetInstance(os, new Id("{DE42374D-B04B-4F47-A62E-CAC9AC9A5719}"));
doc.StorageArea = sa;

doc.Save(RefreshMode.NO_REFRESH);

// Check in the document
doc.Checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION);
doc.Save(RefreshMode.NO_REFRESH);

// File the document in a folder
IFolder folder = Factory.Folder.GetInstance(os, ClassNames.FOLDER,
        new Id("{42A3FC29-D635-4C37-8C86-84BAC73FFA3F}"));
IReferentialContainmentRelationship rcr = folder.File(doc,
        AutoUniqueName.AUTO_UNIQUE, "New Document via .NET API",
        DefineSecurityParentage.DO_NOT_DEFINE_SECURITY_PARENTAGE);
rcr.Save(RefreshMode.NO_REFRESH);

Taking Federated Ownership

This example shows how to retrieve a document and take federated ownership.

Java Example

Document doc = Factory.Document.getInstance(os, ClassNames.DOCUMENT, new Id("{F4DD983C-B845-4255-AC7A-257202B557EC}") );
doc.takeFederatedOwnership();
doc.save(RefreshMode.NO_REFRESH);

C# Example

IDocument doc = Factory.Document.GetInstance(os, ClassNames.DOCUMENT, new Id("{9E285404-1A8F-4828-AC2E-00ADD9BB3CB5}"));
doc.TakeFederatedOwnership();
doc.Save(RefreshMode.NO_REFRESH);

Retrieving a Document (getInstance)

This example retrieves a document using the getInstance method and returns some properties. Note that the getInstance method does not populate the property cache. If you want to work with properties, you need to call the fetchProperties method.

Java Example

// Get document and populate property cache
PropertyFilter pf = new PropertyFilter();
pf.addIncludeProperty(new FilterElement(null, null, null, "DocumentTitle", null) );
pf.addIncludeProperty(new FilterElement(null, null, null, PropertyNames.MIME_TYPE, null) );
Document doc = Factory.Document.getInstance(os, ClassNames.DOCUMENT, new Id("{F4DD983C-B845-4255-AC7A-257202B557EC}") );

// Fetch selected properties from the server
doc.fetchProperties(pf);

// Return document properties
com.filenet.api.property.Properties props = doc.getProperties();

// Iterate the set and print property values
Iterator iter = props.iterator();
System.out.println("Property" +"\t" + "Value");
System.out.println("------------------------");
while (iter.hasNext() )
{
    Property prop = (Property)iter.next();
    if (prop.getPropertyName().equals("DocumentTitle") )
      System.out.println(prop.getPropertyName() + "\t" + prop.getStringValue() );
    else if (prop.getPropertyName().equals(PropertyNames.MIME_TYPE,) )
      System.out.println(prop.getPropertyName() + "\t" + prop.getStringValue() );
}

C# Example

// Get document and populate property cache
PropertyFilter pf = new PropertyFilter();
pf.AddIncludeProperty(new FilterElement(null, null, null, "DocumentTitle", null));
pf.AddIncludeProperty(new FilterElement(null, null, null, PropertyNames.MIME_TYPE, null));
IDocument doc = Factory.Document.GetInstance(os, ClassNames.DOCUMENT, new Id("{9E285404-1A8F-4828-AC2E-00ADD9BB3CB5}") );

// Fetch selected properties from the server
doc.FetchProperties(pf);

// Return document properties
IProperties props = doc.Properties;

// Iterate the set and print property values
System.Collections.IEnumerator propsIter = props.GetEnumerator();
System.Console.WriteLine("Property" +"\t" + "Value");
System.Console.WriteLine("------------------------");
while (propsIter.MoveNext())
{
    IProperty prop = (IProperty)propsIter.Current;
    if (prop.GetPropertyName().Equals("DocumentTitle") )
        System.Console.WriteLine(prop.GetPropertyName() + "\t" + prop.GetStringValue() );
    else if (prop.GetPropertyName().Equals(PropertyNames.MIME_TYPE) )
        System.Console.WriteLine(prop.GetPropertyName() + "\t" + prop.GetStringValue() ); 
}

Retrieving a Document (fetchInstance)

This example retrieves a document using the fetchInstance method and returns some properties. Note that the fetchInstance method populates the property cache with the specified properties.

Java Example

// Get document and populate property cache
PropertyFilter pf = new PropertyFilter();    
pf.addIncludeProperty(new FilterElement(null, null, null, "DocumentTitle", null) );
pf.addIncludeProperty(new FilterElement(null, null, null, PropertyNames.MIME_TYPE, null) );
Document doc = Factory.Document.fetchInstance(os, new Id("{F4DD983C-B845-4255-AC7A-257202B557EC}"),pf );

// Return document properties
com.filenet.api.property.Properties props = doc.getProperties();

// Iterate the set and print property values 
Iterator iter = props.iterator();
System.out.println("Property" +"\t" + "Value");
System.out.println("------------------------");
while (iter.hasNext() )
{
    Property prop = (Property)iter.next();
    if (prop.getPropertyName().equals("DocumentTitle") )
        System.out.println(prop.getPropertyName() + "\t" + prop.getStringValue() );
    else if (prop.getPropertyName().equals(PropertyNames.MIME_TYPE) )
        System.out.println(prop.getPropertyName() + "\t" + prop.getStringValue() );
}

C# Example

//  Get document and populate property cache
PropertyFilter pf = new PropertyFilter();
pf.AddIncludeProperty(new FilterElement(null, null, null, "DocumentTitle", null));
pf.AddIncludeProperty(new FilterElement(null, null, null, PropertyNames.MIME_TYPE, null));
IDocument doc = Factory.Document.FetchInstance(os, new Id("{9E285404-1A8F-4828-AC2E-00ADD9BB3CB5}"), pf);

// Return document properties
IProperties props = doc.Properties;

// Iterate the set and print property values
System.Collections.IEnumerator propsIter = props.GetEnumerator();
System.Console.WriteLine("Property" +"\t" + "Value");
System.Console.WriteLine("------------------------");
while (propsIter.MoveNext())
{
    IProperty prop = (IProperty)propsIter.Current;
    if (prop.GetPropertyName().Equals("DocumentTitle") )
        System.Console.WriteLine(prop.GetPropertyName() + "\t" + prop.GetStringValue() );
    else if (prop.GetPropertyName().Equals(PropertyNames.MIME_TYPE) )
        System.Console.WriteLine(prop.GetPropertyName() + "\t" + prop.GetStringValue() );
}

Deleting a Document

This example deletes a document. Deleting a document deletes, in addition to the document object itself, any associated internal content, annotations, and possibly other dependent objects. Delete operations entirely fail or succeed. For example, not having the requisite permissions to delete any of the document's versions or dependent objects (for example, an annotation) causes the entire delete operation to fail. You can prevent document deletions in the following ways: security permissions, restrictions imposed by compound document relationships, and via the storage area AllowsDelete and RetentionPeriod properties.

Java Example

Document doc = Factory.Document.getInstance(os, ClassNames.DOCUMENT, new Id("{A26C3EF4-7C02-4D01-84CD-D3D7F1D5DA19}") );
doc.delete();
doc.save(RefreshMode.NO_REFRESH);

C# Example

IDocument doc = Factory.Document.GetInstance(os, ClassNames.DOCUMENT, new Id("{6B3E6E63-23B1-4D29-8E91-8632E30F10C5}"));
doc.Delete();
doc.Save(RefreshMode.NO_REFRESH);

Updating Document Properties

This example retrieves the DocumentTitle property, changes its value, and refreshes the property cache.

Java Example

// Get document and populate property cache
PropertyFilter pf = new PropertyFilter();
pf.addIncludeProperty(new FilterElement(null, null, null, "DocumentTitle", null));
Document doc = Factory.Document.fetchInstance(os, new Id("{F4DD983C-B845-4255-AC7A-257202B557EC}"),pf );

// Return document properties
com.filenet.api.property.Properties props = doc.getProperties();

// Change property value
props.putValue(PropertyNames.DocumentTitle, "Document with Updated Title via Java API");

// Save and update property cache
doc.save(RefreshMode.REFRESH );

C# Example

// Get document and populate property cache
PropertyFilter pf = new PropertyFilter();
pf.AddIncludeProperty(new FilterElement(null, null, null, "DocumentTitle", null));
IDocument doc = Factory.Document.FetchInstance(os, new Id("{9E285404-1A8F-4828-AC2E-00ADD9BB3CB5}"), pf);

// Return document properties
IProperties props = doc.Properties;

// Change property value
doc.Properties[PropertyNames.DocumentTitle] = "Document with Updated Title via .NET API";

// Save and update property cache
doc.Save(RefreshMode.REFRESH);

Setting a Document's Content

This example sets a document's content.

Java Example

// Get document
Document doc=Factory.Document.getInstance(os, ClassNames.DOCUMENT, new Id("{8FD91CF0-E991-426D-9BCB-B63F0E30E604}") );

// Check out the Document object and save it
doc.checkout(com.filenet.api.constants.ReservationType.EXCLUSIVE, null, doc.getClassName(), doc.getProperties());
doc.save(RefreshMode.REFRESH);

// Get the Reservation object from the Document object
Document reservation = (Document) doc.get_Reservation();

// Specify internal and external files to be added as content.
File internalFile = new File("C:\\docs\mydoc.txt");
String externalFile = "ftp://ftp.mycompany.com/docs/relnotes.txt";

// Add content to the Reservation object
try {
    // First, add a ContentTransfer object.
    ContentTransfer ctObject = Factory.ContentTransfer.createInstance();
    FileInputStream fileIS = new FileInputStream(internalFile.getAbsolutePath());
    ContentElementList contentList = Factory.ContentTransfer.createList();
    ctObject.setCaptureSource(fileIS);
    // Add ContentTransfer object to list
    contentList.add(ctObject);

    // Second, add a ContentReference object.
    ContentReference crObject = Factory.ContentReference.createInstance(os);
    crObject.set_ContentLocation(externalFile);
    crObject.set_ContentType("text/plain"); // must be set for ContentReference
    // Add ContentReference object to list
    contentList.add(crObject);

    reservation.set_ContentElements(contentList);
    reservation.save(RefreshMode.REFRESH);
    }
catch (Exception e)
{
    System.out.println(e.getMessage() );
}

// Check in Reservation object as major version
reservation.checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION);
reservation.save(RefreshMode.REFRESH);

C# Example

// Get document
IDocument doc=Factory.Document.GetInstance(os, ClassNames.DOCUMENT, new Id("{9E285404-1A8F-4828-AC2E-00ADD9BB3CB5}") );

// Check out the Document object and save it
doc.Checkout(ReservationType.EXCLUSIVE, null, doc.GetClassName(), doc.Properties);
doc.Save(RefreshMode.REFRESH);

// Get the Reservation object from the Document object
IDocument reservation = (IDocument) doc.Reservation;

// Specify internal and external files to be added as content.
Stream internalFile = File.OpenRead(@"C:\\BootstrapConfigUtility.bat");
String externalFile = "file://C:\\BootstrapConfigUtility.bat";

// Add content to the Reservation object
try {
    // First, add a ContentTransfer object.
    IContentTransfer ctObject = Factory.ContentTransfer.CreateInstance();
    IContentElementList contentList = Factory.ContentTransfer.CreateList();
    ctObject.SetCaptureSource(internalFile);
    // Add ContentTransfer object to list
    contentList.Add(ctObject);

    // Second, add a ContentReference object.
    IContentReference crObject = Factory.ContentReference.CreateInstance(os);
    crObject.ContentLocation = externalFile;
    crObject.ContentType = "text/plain";// must be set for ContentReference
    // Add ContentReference object to list
    contentList.Add(crObject);

    reservation.ContentElements = contentList;
    reservation.Save(RefreshMode.REFRESH);
}
catch (Exception e)
{
    System.Console.WriteLine(e.Message);
}

// Check in Reservation object as major version
reservation.Checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION);
reservation.Save(RefreshMode.REFRESH);

Retrieving a Document's Content

This example displays information about a document's content and prints the content. First, it prints document properties about its content: the number of content elements in the document, and the document's size, which is the total of all of the content elements. Second, it gets the document's content element list. For each content element, it prints some property values and then the content itself.

Java Example

// Get document and populate property cache
PropertyFilter pf = new PropertyFilter();
pf.addIncludeProperty(new FilterElement(null, null, null, PropertyNames.CONTENT_SIZE, null) );
pf.addIncludeProperty(new FilterElement(null, null, null, PropertyNames.CONTENT_ELEMENTS, null) );
Document doc=Factory.Document.fetchInstance(os, "{9FEC3C69-57B2-4E29-872A-0EE452881555}", pf );

// Print information about content elements
System.out.println("No. of document content elements: " + doc.get_ContentElements().size() + "\n" +
 "Total size of content: " + doc.get_ContentSize() + "\n");

// Get content elements and iterate list
ContentElementList docContentList = doc.get_ContentElements();
Iterator iter = docContentList.iterator();
while (iter.hasNext() )
{
    ContentTransfer ct = (ContentTransfer) iter.next();

    // Print element sequence number and content type of the element
    System.out.println("\nElement Sequence number: " + ct.get_ElementSequenceNumber().intValue() + "\n" +
     "Content type: " + ct.get_ContentType() + "\n");

    // Get and print the content of the element
    int docLen = ct.get_ContentSize().intValue();
    byte[] buf = new byte[docLen];
    InputStream stream = ct.accessContentStream();
    try
    {
        stream.read(buf, 0, docLen);
        String readStr = new String(buf);
        System.out.println("Content:\n " + readStr);
    }
    catch(IOException ioe)
    {
        ioe.printStackTrace();
    }
}

C# Example

// Get document and populate property cache
PropertyFilter pf = new PropertyFilter();
pf.AddIncludeProperty(new FilterElement(null, null, null, PropertyNames.CONTENT_SIZE, null));
pf.AddIncludeProperty(new FilterElement(null, null, null, PropertyNames.CONTENT_ELEMENTS, null));
IDocument doc = Factory.Document.FetchInstance(os, "{9FEC3C69-57B2-4E29-872A-0EE452881555}", pf);

// Print information about content elements
System.Console.WriteLine("No. of document content elements: " + doc.ContentElements.Count + "\n" +
 "Total size of content: " + doc.ContentSize + "\n");

// Get content elements and iterate list
IContentElementList docContentList = doc.ContentElements;
System.Collections.IEnumerator iter = docContentList.GetEnumerator();
while (iter.MoveNext())
{
    IContentTransfer ct = (IContentTransfer)iter.Current;

    // Print element sequence number and content type of the element
    System.Console.WriteLine("\nElement Sequence number: " + ct.ElementSequenceNumber.Value + "\n" +
     "Content type: " + ct.ContentType + "\n");

    // Get and print the content of the element
    int docLen = (int)ct.ContentSize;
    byte[] buf = new byte[docLen];
    Stream stream = ct.AccessContentStream();
    BufferedStream bis = new BufferedStream(stream);
    StringBuilder sb = new StringBuilder();
    bis.Read(buf, 0, docLen);
    try
    {
        System.Text.ASCIIEncoding enc = new System.Text.ASCIIEncoding();
        sb.Append(enc.GetString(buf), 0, docLen);
        String readStr=sb.ToString();
        System.Console.WriteLine("Content:\n " + readStr);
        bis.Close();
    }
    catch(IOException ioe)
    {
        System.Console.WriteLine(ioe.Message);
    }
}

Assigning a Storage Area

A storage area is only settable when a document is created. See Creating a Document.

Assigning a Storage Policy

This example assigns a storage policy to a document.

Java Example

// Get document and populate property cache
PropertyFilter pf = new PropertyFilter();
pf.addIncludeProperty(new FilterElement(null, null, null, PropertyNames.STORAGE_POLICY, null));
Document doc=Factory.Document.fetchInstance(os, "{33074B6E-FD19-4C0D-96FC-D809633D35BE}", pf );

// Print name of current storage policy
System.out.println("Current storage policy: " + doc.get_StoragePolicy().get_DisplayName() );

// Set new storage policy and print name
StoragePolicy sp = Factory.StoragePolicy.getInstance(os, new Id("{BA065E85-7D01-48E3-9266-4EFDC8D8FAE3}") );
doc.set_StoragePolicy(sp);
doc.save(RefreshMode.REFRESH);
System.out.println("New storage policy: " + doc.get_StoragePolicy().get_DisplayName() );

C# Example

// Get document and populate property cache
PropertyFilter pf = new PropertyFilter();
pf.AddIncludeProperty(new FilterElement(null, null, null, PropertyNames.STORAGE_POLICY, null));
IDocument doc=Factory.Document.FetchInstance(os, "{61BA91F0-6639-4A12-A784-CD274AADF9AA}", pf );

// Print name of current storage policy
System.Console.WriteLine("Current storage policy: " + doc.StoragePolicy.DisplayName);

// Set new storage policy and print name
IStoragePolicy sp = Factory.StoragePolicy.GetInstance(os, new Id("{BA065E85-7D01-48E3-9266-4EFDC8D8FAE3}") );
doc.StoragePolicy = sp;
doc.Save(RefreshMode.REFRESH);
System.Console.WriteLine("New storage policy: " + doc.StoragePolicy.DisplayName);

Moving a Document's Content

This example moves a document's content to a different storage area. In this case, the content is moved to a database storage area.

Java Example

// Get the storage area where you want to move the document content
DatabaseStorageArea dsa = Factory.DatabaseStorageArea.fetchInstance(os, new Id("{3C6CEE68-D8CC-44A5-AEE7-CADE9752AA75}"), null );

// Get the Document object whose content you want to move
Document doc = Factory.Document.getInstance(os, ClassNames.DOCUMENT, new Id("{33074B6E-FD19-4C0D-96FC-D809633D35BE}") );

// Move the content and save the Document object
doc.moveContent(dsa);
doc.save(RefreshMode.REFRESH);

C# Example

// Get the storage area where you want to move the document content
IDatabaseStorageArea dsa = Factory.DatabaseStorageArea.FetchInstance(os, new Id("{3C6CEE68-D8CC-44A5-AEE7-CADE9752AA75}"), null);

// Get the Document object whose content you want to move
IDocument doc = Factory.Document.GetInstance(os, ClassNames.DOCUMENT, new Id("{61BA91F0-6639-4A12-A784-CD274AADF9AA}"));

// Move the content and save the Document object
doc.MoveContent(dsa);
doc.Save(RefreshMode.REFRESH);

Customizing a Document Class

This example customizes the Email class by adding a new property (eMail signature) to the class. Note that a LocalizedString is required for the name and descriptive text. A getLocalizedString method is used to return a LocalizedString.

Java Example

public void customizeClass()
{
    //  Fetch selected class definition from the server
    ClassDefinition classDef = Factory.ClassDefinition.fetchInstance(os, "Email", null );

    // Create new PropertyTemplate for object property with optional value.
    PropertyTemplateObject newPropTemplate = Factory.PropertyTemplateObject.createInstance(os);
    newPropTemplate.set_Cardinality (Cardinality.SINGLE);
    newPropTemplate.set_IsValueRequired(Boolean.FALSE);

    // Set required properties to localized string
    LocalizedString locStr1 = getLocalizedString("eMail Signature", os.get_LocaleName() );
    // Create LocalizedString collection
    newPropTemplate.set_DisplayNames (Factory.LocalizedString.createList() );
    newPropTemplate.get_DisplayNames().add(locStr1);

    LocalizedString locStr2 = getLocalizedString("Signature of sender",
       os.get_LocaleName() );
    newPropTemplate.set_DescriptiveTexts(Factory.LocalizedString.createList() );
    newPropTemplate.get_DescriptiveTexts().add(locStr2);

    // Save property template to the server
    newPropTemplate.save(RefreshMode.REFRESH);

    // Create property definition from property template
    PropertyDefinitionObject newPropDef = (PropertyDefinitionObject)newPropTemplate.createClassProperty();

    // Set RequiredClass property to Email Items
    newPropDef.set_RequiredClassId(new Id("{BFA64F40-5C45-45B1-B540-B5BA3CA08AAB}") );

    // Get PropertyDefinitions property from the property cache
    PropertyDefinitionList propDefs = classDef.get_PropertyDefinitions();

    // Add new property definition to class definition
    propDefs.add(newPropDef);

    classDef.save(RefreshMode.REFRESH);
}

private LocalizedString getLocalizedString(String text, String locale)
{
    LocalizedString locStr = Factory.LocalizedString.createInstance ();
    locStr.set_LocalizedText(text);
    locStr.set_LocaleName (locale);
    return locStr;
}

C# Example

public void customizeClass()
{
    //  Fetch selected class definition from the server
    IClassDefinition classDef = Factory.ClassDefinition.FetchInstance(os, "Email", null);

    // Create new PropertyTemplate for object property with optional value.
    IPropertyTemplateObject newPropTemplate = Factory.PropertyTemplateObject.CreateInstance(os);
    newPropTemplate.Cardinality = Cardinality.SINGLE;
    newPropTemplate.IsValueRequired = false;

    // Set required properties to localized string
    ILocalizedString locStr1 = getLocalizedString("eMail Signature", os.LocaleName);
    // Create LocalizedString collection
    newPropTemplate.DisplayNames = Factory.LocalizedString.CreateList();
    newPropTemplate.DisplayNames.Add(locStr1);

    ILocalizedString locStr2 = getLocalizedString("Signature of sender", os.LocaleName);
    newPropTemplate.DescriptiveTexts = Factory.LocalizedString.CreateList();
    newPropTemplate.DescriptiveTexts.Add(locStr2);

    // Save property template to the server
    newPropTemplate.Save(RefreshMode.REFRESH);

    // Create property definition from property template
    IPropertyDefinitionObject newPropDef = (IPropertyDefinitionObject)newPropTemplate.CreateClassProperty();

    // Set RequiredClass property to Email Items
    newPropDef.RequiredClassId = new Id("{BFA64F40-5C45-45B1-B540-B5BA3CA08AAB}");

    // Get PropertyDefinitions property from the property cache
    IPropertyDefinitionList propDefs = classDef.PropertyDefinitions;

    // Add new property definition to class definition
    propDefs.Add(newPropDef);

    classDef.Save(RefreshMode.REFRESH);
}

private ILocalizedString getLocalizedString(String text, String locale)
{
    ILocalizedString locStr = Factory.LocalizedString.CreateInstance();
    locStr.LocalizedText = text;
    locStr.LocaleName = locale;
    return locStr;
}