Attached Documents and File Transfer: Key Concepts

Within Agentry it is possible to retrieve files during the download portion of synchronization, store those files on the client device with reference to them from the mobile application, and to send files up from the client device during the upload portion of synchronization. Files can also be attached to objects locally on the mobile application if those files are stored on the client device.

The implementation of this functionality involves several different definition types within the application project:

A property with a data type of External Data to reference and track the file.
Object definition to represent the document within the mobile application.
A list to display the documents attached to a given parent object.
One or more step definitions of a type compatible with the back end system to retrieve information about the files associated with an object and the location of those files.
One or more File - Document Management step definitions to download and upload attached documents.
An action step of type Windows Command to display a selected file on the client device.
A transaction to allow the user to attach documents locally on the client and upload them to the back end system.
A transaction to process documents that have been changed on the local client device and need to be updated to the back end system.
One or more rule definitions to check the state of a file, including its location, size, and whether or not it has been modified since being downloaded.

For a given implementation some or all of these definitions may need to be defined. As an example, if files are to only be downloaded to the client, but never attached locally or uploaded to the back end system, then transactions and steps to process such operations are not needed.

External Data Properties and File References

When implementing the attached documents or file transfer functionality it is important to understand how the file is stored and referenced by the mobile application. An external data property is defined to reference a file stored on the client device. Files downloaded to the client device, and files attached locally on the device for later upload are not stored with the production data of the mobile application. Rather, they are stored external to the production data, with their location on the client device referenced by the external data property.

Encapsulate the File - Object Definition

As a recommended practice, the files to be downloaded, attached, and/or uploaded should be encapsulated within the application project as an object definition specifically for this purpose. While an external data property can be added to any object definition, it is a cleaner and more manageable architecture and design to create an object definition specifically for the files and to then store instances of that object definition in a collection property at run time.

All file-related operations and behaviors are far easier to implement and maintain when following this model, including downloading and uploading files, listing the files associated with a given parent object, and other operations.

Typically an object definition to represent a file is defined to include the external data property, a property to contain the name of the file (normally a string property) and a property containing the location of the file on the back end system when that location is somewhere on the file system. Normally the property containing the file name is defined to the be the key property of the object, as having more than one file with the same file name would cause issues during synchronization and storage, and designating this property as the key property will prevent such a circumstance.

Client-Side File Operations

As external files to the mobile application, files referenced by external data properties are not directly displayed in the mobile application. Rather, a list of the external data properties displayed on the client will include the name and location of that file. Similarly, detail screen fields displaying these properties include similar information about the file.

The mobile application can be defined to display an attached file in an application on the client device associated with the type of file being referenced. This application must exist on the client device and is not a part of the mobile application built in Agentry. To display a file in its native application, a Windows Command action step must be defined. It then contains as it’s command the full path and file name, which is provided by the external data property. This path is passed to the operating system, which in turn “launches” the file in its associated application the device. From this point the user can perform what ever operations the application for the file allows. The only exception to this is when the file is set to be read-only, an option within the external data property. Such files are then not editable on the client device.

When attaching files locally on the client device, a file dialog is displayed to allow the user to navigate the file system and select the file to be attached. This operation is a part of a wizard screen set displaying a transaction to support this behavior. The transaction is no different than any other, containing properties to capture data from the user. An external data property is displayed in a field type specific to that property type that supports the selection of a file from the client device’s file system.

Rule Functions for External Data Properties

There is a set of rule functions available for rule definitions to work specifically with external data properties:

FILE_CHANGED: This function returns a Boolean value indicating whether or not the referenced file has been modified since it was downloaded to the client device. this can be useful when determining whether or not files downloaded to the client device are in need of update to the back end system based on changes the user may have made to those files.
FILE_EXTENSION: This function returns a string containing just the file extension of the file referenced by the external data property. This can be useful in filtering a list of files, e.g. show just image files (.jpg), and similar behaviors.
FILE_NAME: This function returns the name of the file referenced by the external data property. This is the file name only, excluding any path information.
FILE_PATH: This function returns string containing the full path to the location of the file referenced by the external data property, excluding the file name.
FILE_PATH_AND_NAME: This function returns a string containing the fill path and file name of the file referenced by the external data property.
FILE_SIZE: This function returns an integer that is the size of the file in bytes referenced by the external data property.

These functions can be used in various situations related to working with the file referenced by an external data property stored on the client device. Some use cases for these functions are provided in the information on implementing this functionality.

Data Synchronization for File Transfer

When defining the synchronization logic to retrieve files from the back end system for storage on the client device, it is necessary for this logic to perform a set of operations related to each file:

Retrieve the parent object that will contain the collection of attached documents. This logic is contained in a step type matching the back end system.
Retrieve the information about those files to be stored in the parent object, including the file’s name, its storage location on the back end system, and excluding the file itself. This logic is contained in a step type matching the back end system.
Retrieve the file from the back end system. This logic is contained in a file document management step.

One of the keys to this functionality is that the back end system must have information available about which files are associated with which objects, and the specific location of those files on the back end system so that the Agentry Server can retrieve them. This location must be one to which the Server has read access.

While the above operations includes three distinct steps, it may be possible in some back ends to perform the first two operations in a single step definition. As with other synchronization operations, what data can be retrieved at which point is dependent on the back end system’s structure and the interface type in use (i.e. Java, SQL, HTTP-XML). The retrieval of the actual file always requires a the definition of a file document management step.

When defining the synchronization logic to upload files to the back end system for storage in the back end system, it is necessary for this logic to perform a set of operations related to each file:

Upload the file to the Agentry Server and then tot he back end system. This logic is contained in a file document management step.
Update the back end system with the necessary information about the file, including the business entity with which it is associated, revision/upload date, and any other information the back end requires for the file. This logic is contained in a step type matching the back end system.

Supporting Infrastructure Tasks

In addition to changes within the Agentry application project, there are certain tasks that should be performed in support of implementing this functionality:

Verify the proper applications are installed to client devices in the environment for the file types expected to be a part of this functionality.
The file system on the host system fro the Agentry Server must contain a location to which the Agentry Server has read-write access. The Agentry Server typically requires a location to temporarily store the files being transferred. This location should be noted for reference during the development and implementation of this functionality.
The location to which files will be written on the client devices should be determined. This location is created by the Agentry Client during synchronization if it does not exist, and can include components based on the parent object of the file, as well as the user’s ID.
The method in which files are stored by the back end system should be known. The processes, tools, and/or other items that system employs should be evaluated to determine if they can be used by the file document management steps of the mobile application during synchronization. Typically such items include command line processes that can be called to check out and check in files from a version control system, or a process that extracts the files from a database when the files are stored in this manner.