Defining the File Object

1. Begin by defining a new object within the module of the Agentry application project. For this example we name the object definition Document.
2. Next add a string property to this object that will contain the name of the file the object encapsulates. Note that this property need not be a string, but can be any other data type desired. It’s value is converted to a string when used to name the file being saved. It is recommended it be defined as a string initially to allow for more variability in the file name. In this example we name the property FileName and has the other following attributes. (Attributes not listed here should be left set to their defaults for this example. They can be set as needed for implementation specific requirements):
   • Minimum Length: 1
   • Maximum Length: none (note this can be set to a maximum if deemed necessary to the application; however, it should be sufficiently sized to ensure the file name value is not truncated)
   • Trim: true (this can be important to prevent the file name from containing leading or trailing spaces that could cause issues in numerous file related operations)
3. Now define a property to contain the location of the file on the file system of the Agentry Server’s host system. This string property is used when the source location of the file is on a the file system. Define the property to be a string with. In this example we name the property BackEndFile with the following attributes:
   • Minimum Length: 1
   • Maximum Length: none
   • Trim: true

   This property is always required regardless of where the files are stored, including in a database system or file control system. It is needed during synchronization, as will be apparent in the procedures on this topic.

4. Define any other properties that may be needed for the file object. These could include values for reference purposes, such as the date and time the file was last modified, a revision number for the file, or other similar information. Keep in mind any values must be accessible from the back end system in order to be downloaded for the object.
5. Next the external data property is defined. This property provides the reference to the file as stored on the client device. Begin by adding a property to the object with a data type of External Data. In this example the property is named File. Set the attributes of this new property according to the following:
   1. Set the Client File attributes to specify the source for the file name, behaviors related to if/when to delete the file, whether or not it is read-only, and the behavior of the file dialog when attaching files locally:
      
      

      These attributes are set to reference the property of containing the name of the file as retrieved from the back end system with the File Name attribute set to the string property FileName. We have also defined the file to never be deleted on the client. It is possible to define the file to be deleted only when it was created by the Agentry Client during data synchronization, or to always delete file when the parent object is deleted. Finally, the file has been defined to be read-only, which means users are not able to modify the file on the client device. The File Extension attribute has been left blank, meaning files will keep the extension as returned during synchronization. It is possible specify an extension here, which changes the file extension of all files to the value provided, regardless of the extension of the file when it is downloaded or attached locally.

   2. Next the attributes specifying where the file is to be stored on the Agentry Client are set:
      
      

      The settings defined here result in a client device storage location specific to the mobile application and the parent object to which the files are attached. The base path under the Windows 9.x/NT/2000/XP section is set to “Absolute Path.” The Relative Path attribute then contains the full path to the location where the files are to be stored. Other options include the various standard windows lactations, such as My documents, My Pictures, etc. For the Windows CE section, the attribute Use Path is selected, which will replicate the path for Windows desktops on the Windows Mobile devices. The drive letter is removed from the path.

6. Complete the creation of this external data property clicking the [Finish] button. Then, review the properties for the document object. For this example, the following now exist (others may be included in file objects like this based on need, with these being considered the bare minimum:
   • FileName: A string property that contains the name of the file as it will be stored on the client device. Note that this may different from the file name in the back end system and is set during synchronization, which can include both the back end name and/or other values available at run time. The synchronization procedures provided for this topic address this behavior.
   • BackEndFile: This property contains the full path and file of the file to be downloaded from the back end system. This is referenced by the server processing for synchronization.
   • File: External data property that references the full path and file name for the file stored on the client device.
7. The next step for the file object is to set the key property of the file. View the Object tab in the Properties view of the Agentry Editor. Change the Key Property attribute here to the property that stores the name of the file (in our example the FileName property).
8. Finally, create navigate in the Agentry Editor to the object that will contain the instances of the file object. In our example, this is the Customer object. Add a property to this parent object of type collection and define it to stored instances of the file object just created.

The next area of functionality to implement is the downstream synchronization processing. See the procedure on this topic for guidance on this procedure.