Programmer's Guide:
Using Files

Files, also referred to in the user interface as attachments, are one of the most commonly used eRoom objects. Files are principal items in the SAAPI object model, and have some special features that other items lack. For instance, only File objects support version tracking. Version tracking allows you to automatically maintain a copy of each version of a File as it goes through multiple rounds of editing. The file manipulation and version tracking functionality for File objects are exposed through the IERUFile and IERUVersion interfaces of the File object, and the IERUVersionPage and IERUContainer interfaces of the Version Page object.

SAAPI stores the name and extension of a File together, rather than in different properties. The name is stored in the Name property of IERUItem, while the extension is stored in the Extension property of IERUFile. The value of the Extension property includes the . (period) character.

Adding a File to a Room

To add a File to a Room, use the CreateFile method in the IERUContainer interface of any container object. This method takes a path to an existing file on disk, and allows you to specify a new name for the File in eRoom. If you pass an empty string for the new name, the existing name will be used.

Dim NewFile as IERUItem
Set NewFile = MyFolder.CreateFile("C:\My Documents\Expense Report.xls", "")

Retrieving and Replacing Files

To extract a file from a Room, use the Get method in IERUFile. Specify either the path to an existing directory or the full path (including filename) you would like the extracted file to have. If a directory name is supplied, SAAPI will try to create a file in that directory with the same name and extension that the File object has in eRoom. If there is already a file on disk with the full path SAAPI tries to use, the method alters the name slightly to avoid overwriting the existing file. If a full path is specified, SAAPI stores the file in the specified location, overwriting any existing file with that name. In all cases, the full path of where the file was stored is returned by the Get method so that you can be sure where it went.

Dim StoredPath as String
StoredPath = MyFile.Get("C:\MyDocuments")

To update a file already in a Room, execute the Replace method of IERUFile.

MyFile.Replace("C:\MyDocuments\Birthdays.doc")

Note that the eRoom site file system user must have rights to files that are being added to eRoom.

Version Tracking

Files that have version tracking enabled implement the IERUVersion interface. You can always get the IERUVersion interface for a File, but its properties and methods will return errors if version tracking is not enabled. In addition, Files with version tracking enabled have an associated object called a Version Page, through which you can enumerate and access the older versions of the File. Old versions of Files are also File objects, and also implement the IERUVersion interface, but you can only enable or disable version tracking on the most current version of a File. Likewise, you can only access a Version Page through the most current version of a File.

Turning version tracking on and off

To enable or disable version tracking on a File, use the TrackVersions property in IERUFile.

MyFile.TrackVersions = TRUE

Accessing the Version Page

To get to the Version Page object associated with a versioned File, get the VersionPage property in IERUFile.

Dim VP as IERUVersionPage
Set VP = MyFile.VersionPage

Accessing the current version and old versions

If you need to get the current version of the File for a Version Page object, access the CurrentVersion property of IERUVersionPage. Note that if you got to the Version Page via a File object, this property returns the same File object, so it is primarily useful if you accessed the Version Page via a different mechanism, such as GetItem. To iterate through the old versions of a File, get the Version Page object and use the Items property of its IERUContainer interface. The current version of the File is not included in the returned collection. Whenever you are working with a File object and you are not sure if it is the current version, you can check the IsCurrentVersion property of IERUVersion to find out.

Version names and numbers

Each version of a File has a version name and number, which are accessible through the VersionName and VersionNumber properties of IERUVersion. When you call the Edit or Replace methods of IERUFile on a versioned File, the newly-created version has its version name set to the File name by default, and the version number is incremented by one. You can change these values by setting the VersionName and VersionNumber properties.

Version notes

You can create, enumerate, modify, and delete version notes on a Version Page by accessing its embedded topic. See Working with Discussion Pages, Topic Pages, and Topics for more information.  

Accessing files in the eRoom file system

For information on accessing files in the eRoom file system, see the Accessing files section of the Upgrade Notes topic.