Developing with attachments

Attachment contents

This functionality provides you the flexibility to attach many types of files (for example, .jpg, .pdf, .doc) to features, and it extends the existing functions, which allows you to add various kinds of files using a BLOB field.

The attachment classes include the following:

• Attachment—From the Runtime SDK perspective, an Attachment object is not the real attachment file (the source file) of a feature, rather, it's a bundle of information linked to the actual attachment file in local storage. This bundle of information includes attachment ID, name, size, edit states, and so on.
• AttachmentManager—An AttachmentManager object helps you add attachment objects to features, retrieve attachment objects from features, cancel edits to attachments, and mark attachments as deleted from local storage.
• FeatureAttachmentSyncAgent—A FeatureAttachmentSyncAgent object helps you synchronize attachments without their related features and allows you to specify a subset of attachments to synchronize.
• FeatureAttachmentSyncResults—A FeatureAttachmentSyncResults object represents a list of attachment information after a synchronization session is completed.

Enable attachment functionality

To enable the attachment functionality, you need to have ArcGIS Desktop with ArcEditor or ArcInfo license.

After you've created a feature class out of a database, you will enable attachments for the feature source. See ArcGIS Desktop help document for more details. When completed, an attachment table and a relationship class are created. Add Global IDs to the feature class and the attachment table so that you can edit them. Finally, you can host the mobile service in a ArcGIS 10.1 Server, or use the Create Mobile Map geoprocessing (GP) tool to create a local mobile cache with attachments out of your map document. Both methods allow you to utilize the attachment functionality; however, only the caches created from mobile services support synchronization of attachments (and features). For the local mobile cache, you work in a completely offline environment and check in your edits using the Synchronize Mobile Cache GP tool.

Note:

For more information about using the Create Mobile Map and Synchronize Mobile Cache GP tools, see the relevant topics in the ArcGIS for Desktop help.

Typical use case when working locally with attachments

In the following use case, you'll inspect water meters and attach pictures to them. You'll create several attachment objects and add them to a water meter feature. You'll then cancel the previous add action to one of the added attachments, then mark another existing attachment as deleted. Finally, you'll retrieve the attachment information of a few water meters, and you'll check that the added and deleted attachments are in their correct edit states.

You've just taken two pictures for a water meter using the built-in camera on your device, and the pictures are stored in the SD card (for example, \SD-MMC card\Pictures). You want to attach them to a water meter feature. You'll first create two attachment objects for each image by giving them a name and the object ID of the feature to which they belong. The actual linkage will be established when you use an AttachmentManager to copy or move the actual attachment files from their source location to the attachment folder inside the mobile cache.

You'll then remove one of the attachment objects you just added to the water meter feature. Again, you'll use AttachmentManager, and you'll cancel that attachment by passing its attachment ID.

You then notice that one of the attachments you've downloaded from the server is not showing clearly the water meter you're inspecting, so you delete it with an AttachmentManager by specifying the attachment ID. Upon finishing, the attachment's EditState will become deleted.

AttachmentManager can also be used to retrieve the water meters' attachment information. Retrieving a list of attachment information is particularly useful when, for example, you want to get an idea of the total attachment size before you download it, count how many attachments a feature contains, or when you want to use this list to define a specific subset of attachments to synchronize from or to the server.

You'll retrieve the attachment information of the water meter with which you've been working. You'll get two separate lists of added and deleted attachments by passing a QueryFilter object and the two attachments edit states. Due to the previous operations, you'll find only one added attachment (since you cancelled edits to another) and one deleted attachment.

Note:

Similar to the EditState of a FeatureSource, if an attachment object is created in local storage but not yet uploaded, its EditState will be Added. If it resides in the back-end database, it will be in Original EditState. If an original feature is deleted from local storage, it will be marked as Deleted.

Typical use case when synchronizing attachments

Extending from the previous use case, you'll go through two separate processes of downloading and uploading attachment files with the back-end database. You'll interpret the sync results at last. Synchronization of attachments (and features) is only supported if you use a mobile service.

There are two ways to synchronize attachments: using a FeatureSyncAgent object or using a FeatureAttachmentSyncAgent object. They are similar in that both synchronize attachments from the server (with default settings), and they differ in that synchronizing with a FeatureAttachmentSyncAgent has no effect on the features to which the attachments are associated.

Start from where you download the water meter layer using a FeatureSyncAgent, and keep all the default settings. Upon finishing, you'll find the AttachmentSyncResults property of the FeatureSyncAgent, which gives you statistics of the sync results. In addition, you'll have actual attachment files downloaded to the cache.

Note:

You used the default settings to download features. If you disable the attachment download option of your FeatureSyncAgent, the AttachmentSyncResults returned will be null. Another case is, even if you enable the attachment download option (or use the default settings), but during download an error occurs, you'll still get a list of AttachmentSyncResults, but there will be no attachment files in your cache.

Another way to download attachments is by using a FeatureAttachmentSyncAgent, which will only download the attachment files without the features. A FeatureAttachmentSyncAgent gives you extra download options, that is, you can choose to download attachments for certain features (you can get specific attachments using an AttachmentManager), you can download a particular type of file, and you can set the maximum size of an attachment to download. Again, upon download, you'll find the AttachmentSyncResults property from the FeatureAttachmentSyncAgent object, and you'll have the actual attachment files stored in the local cache.

Finally, you can upload the added and deleted attachments of your inspected water meter back to the database. Similar to downloading, you complete the task with a FeatureSyncAgent. However, you can also use a FeatureAttachmentSyncAgent object, which will give you the option of selecting only a subset of attachments to upload.

Finally, you'll check the AttachmentSyncResults, get the statistics about the attachments uploaded, and see if there are any upload errors.