Defining the Download Logic for File Transfer

Prerequisites

The following items must be addressed prior to performing this procedure:

The object definition encapsulating the files to be downloaded (hereafter referred to as the file object) must be defined. The collection property to store the file object instances must already be defined in the parent object.
This procedure assumes a fetch exists within the application project to retrieve the parent objects of the file object.
The location of the files in the back end system must be known and the manner in which they are to be retrieved from that location should be determined. This is especially true if a version control system is to be accessed or if the files are stored in a database.
Agentry Client Agentry Server

Task

This procedure describes how to define the steps and step usage definitions to retrieve files from the back end system to be transferred to the Agentry Client. In the example used here the files are stored in the version control system Subversion. As a part of downloading the files, the command line process export is used. This process extracts a revision of a specific file from the repository and copies it to a designated location on the file system. This copy is not maintained by the version control system, which is a desirable behavior for this logic as the copy we create will be temporary and will be removed when the Agentry Server has finished transferring it.

This procedure describes what information is needed prior to the retrieval of the actual steps. How this information is retrieved will vary from one system and one back end type to the next. However, the general information required for this processing is the same.

As will be illustrated in the portion of this procedure related to the object read steps, one of the key items is to define the proper run behavior for the Document Management step that actually retrieves the files. Files are retrieved one at a time. Therefore, the document management step must be defined to run once for each file to be retrieved. This is controlled by the Run attribute of the object read step definition that uses the document management step. Note that only the object read step definition type contains the proper setting for the Run attribute. This step cannot be run to retrieve files in a fetch step usage definition.

In order for the document management step to run properly, therefore, the files to be retrieved must be known in advance. This is a part of the general information retrieved from the back end, where presumably the information relating the files to the business objects is located. this information is used to instantiate the file objects and, therefore, must include the value of the key property for each of those objects. In the architecture recommended here, this is the name of the file to be retrieved as it will be stored on the Agentry Client.

In this example, the Customer object contains a collection of file objects named Documents. A fetch already exists to synchronize the Customers collection, including it’s nested collections Orders and Products. To this processing we will add the steps to get the document objects and the actual files to be referenced by those objects.

First, define the step to retrieve the property values for the file object, other than the actual external data property. In our example the file object includes the values of the FileName and BackEndFile properties. As with the synchronization of any nested collection, this processing must also include the key property of the parent object, which in this case is the CustomerID. For the sample Mobile Northwind application a SQL statement is written that selects the BackEndFile location and the FileName values from the table CustomerDocuments in the database. The step definition is a SQL step named GetDocumentInfo.
Next the document management step must be defined to retrieve the actual files to be transferred. This consists of several pieces, which are broken down over the next steps of this procedure. Begin by adding a step to the module of type File Document Management that uses the file system connection within the project. In the second wizard screen, select the attributes to specify which object is to contain the files it retrieves. In our example application the selection for this attribute is “Object - Document.” Steps of this type need to know for which definition they will be retrieving data to provide access to the proper values to the logic they contain, as will be demonstrated in the following steps. Set the name and group attributes and then finish the wizard.
Now that the step is created, the next task is to define the document mapping(s) for the step. Document mappings define the relationship between the properties of the definition selected when the step was created, and the command the step will execute at run time. In the Properties view of the Editor, select the tab Document Mappings. To add a new mapping, select the add button above the empty list. The Add Document Mapping wizard displays.

Set the attributes of Property, which should be the external data property for the file object. Then, set the Output Type, which is how the file to be transferred is output by the command we will write to retrieve the file from the back end. In our case, the file is retrieved from the version control system and saved to the local file system of the Agentry Server, so the proper selection is “File created by command.” Other options are to capture the processes output to standard error or standard out, or the processes exit code. These are discussed in the later, optional steps to this procedure. Leave this wizard open to set the next attribute, File Name, as discussed in the next step of this procedure.
First, check the box below the File Name attribute marked Delete File. This setting removes this temporary file from the file system for the Agentry Server once the Server has completed processing it. The File Name attribute specifies the name of the file as it will exist on the file system of the Agentry Server once it has been created by the document management step. This file name can be set to any value, as it is only temporary and does not need to match the file name as it will be stored in the Agentry Client. This attribute can, and likely will include SDML data tags. In our example, the file name is a combination of the fileName property of the file object, the CustomerID of the parent Customer object, and the user’s login value. This combination guarantees a unique file name for the file on the Server. This attribute can, and in most cases should include the path information to where the file is to be stored. This location should be one to which the Agentry Server has read-write access and is typically one created specifically for use by the Agentry Server. The full value of this attribute in our example, then, is:
```
C:\MobileNorthiwndFileTransfer\<<document.fileName>><<customer.CustomerID>><<user.agentryID>>.tmp
```
Note that any property value from the object is valid with the exception of the external data property. This value, then creates a file in the specified location, with a name guaranteed to be unique for each user and customer object combination. As demonstrated shortly, the values used here to create the file name should be noted, as they will be needed in the creation of the command for the document management step. Once the File Name attribute has been set, finish the wizard.
OPTIONAL: Additional Document Mappings can be defined for this document management to capture other information from the command it executes. The Output Type setting controls this behavior, with the options Command Exit Code, STDERR, and STDOUT. Each of these values produced by the command can be mapped to a property within the definition for which the document management step was defined, e.g., the Document object in our example. The Command Exit Code and STDERR options are typically selected to capture any errors to support processing them accordingly. STDOUT is selected when the process executed by the document management step streams the file data to standard output rather than creating a file on the file system. STDOUT can be mapped to the external data property when the process behaves in this manner.

Create any additional document mappings, as needed. The attributes File Name and Delete File are not available when these options are selected, as there is no physical file included in the processing.
Next the command to retrieve the file from the back end is written. In the Properties View select the Document Management Script tab. The command can be written either directly in the Command attribute (set to <<script>> by default) or in a separate script file. To run a separate script, the default <<script>> data tag should be left as the value for the Command attribute. The separate script file is the default behavior, and the Command field is typically only used when a single short command is needed. In most real-world applications the command is stored in the separate script file. Click the edit button tot he right of the File attribute on this screen to display this script, which is shown in the text editor view.
The command executed can be any series of one or more command line utilities that may be needed to retrieve the file from the back end storage system. In our example we assume the version control Subversion contains a repository of files for customers in the Northwind system. We extract the files, therefore, from this system. We use the export command in Subversion for this processing, writing the file to the file system for the Agentry Server. Regardless of the tools used, the command written here must extract the file from the back end system, making use of the information retrieved previously regarding which file and where it is located. the command can then either write the file to the file system, or stream it to standard output for the Agentry Server to capture. The proper behavior must be matched to the defined document mappings for the Document Management step. The following is the example command used for the Mobile Northwind application:
```
export <<document.backEndFile>> C:\MobileNorthwindFiles\<<document.fileName>><<Customer.CustomerID>><<user.agentryID>>.tmp
```
The above command executes the export utility for the Subversion system. It extracts the file from the location where it is stored in the repository, which is the value returned by <<document.backEndFile>>. The file is then written to the location where the Agentry Server expects it. The file name is then set to match the values of the name of the file in the back end (<<document.fileName>>), the parent CustomerID property values (<<customer.CustomerID>>), and the user’s client login (<<user.agentryID>>).
Now that steps are defined, they must be used. For file transfer functionality this requires the use of object read steps. In our sample Mobile Northwind application there already exists a fetch named GetCustomers, which targets the top-level Customers collection. Therefore, the read steps will be added to the Customer object and read into the Documents collection property of that object. First, the GetDocumentInfo step must be run. Remember that this is the first step we defined in this procedure and is the one to retrieve the information about the file to be transferred. Create a read step within the object to run this step. The Run attribute for the mobile application is Run one time, as all information about the files can be retrieved in a single query. For other systems, determine if the logic can perform this type of batch processing and set the Run attribute accordingly.
Next we define the read step for the document management step. In the Mobile Northwind application this is the GetCustomerFiles step. When defining this read step, the attributes should be set to reference the document management step and to read into the collection of file objects. The Run attribute must then be set to Run Once per Collection Object. This will execute the document management step once for each of the file objects contained in the collection, returning the file based on the other property values of that object.
Once these read steps are defined, verify the proper order. The first step run should be the one that retrieves the information about the files to be transferred. The result of this step’s execution is the creation of the file object instances to be stored in the collection. This should then be followed by the document management step that retrieves the actual files. Since this step is executed once per collection object, the step to create the file objects must come first, followed by the document management step.

With the completion of this procedure the file transfer functionality is added to the mobile application. If following the steps and general architecture of this procedure, the following is the overall processing and data flow of this change:

A transmit is initiated by the Agentry Client. The fetch for the top level collection is processed as it was prior to this modification.
The object read steps of the object type being targeted by the fetch are processed by the Agentry Server. When the step to retrieve the information about the files to be transferred is run, the Agentry Server processes the results of that step and instantiates the file objects, storing them in the collections of the parent object instances. These file objects include the information about where the file is located in the back end, and the name of that file.
The document management step is run next. It is executed once for each object instance in the collection of file objects. For each execution, the file is retrieved from the back end system and stored in a temporary location for the Agentry Server to access it. This location is determined by the command in the document management step.
When the command completes execution, the Agentry Server uses the information in the document management step’s document mappings to read the file from the location the mapping specifies. It sets the property the mapping specifies within the file object to reference the file it reads in.
The file is transferred by the Agentry Server to the Agentry Client, where the file is stored on the client device according to the storage location defined in the external data property.
The above steps concerning the execution of the document management step are repeated once for each file object until all have been processed.

Next

If not already accomplished, the user interface to display a list of the files downloaded, as well as to possibly allow the user to display those files and edit them needs to be implemented. See the procedures in this tutorial on the user interface and actions related to the files downloaded to the Agentry Client.