Defining Locally Attached Documents Functionality

Prerequisites
The following items must be addressed prior to performing this procedure:
  • An object must exist in the application project to encapsulate the files to be attached to a parent object (hereafter referred to as the file object).
  • Options exist to specify the location in which files can be selected on the client device. If this behavior is desired, this location should be determined and note for this procedure.
  • Options exist to restrict the type of file a user can attach on the client device. This is controlled by the file extension. If this is desired behavior, the file type and extension should be noted for this procedure.
  • The manner in which files should be stored in the back end system should be researched, including details on how to add the files to that storage location or repository. This processing must be a part of the logic defined to upload the file to the back end.
Task

In this procedure the tasks necessary to allow users to attach files to an object on the client, selecting that file from the client’s file system, are provided. This functionality includes the use of an Add transaction to create a new file object and to capture the properties of that object, including the file to be attached, from the user. A transaction screen set is defined that includes a filed to display the external data property. The field for this property type displays a file dialog to the user when it is selected in the wizard, allowing the user to navigate to the file to be attached.

The synchronization of this data includes steps that update the back end system with the information about the file, including it’s name, the parent object it is attached to, and other information as may be required by the back end system. Typically this information is updated to the back end using a step definition of the type matching that back nd, i.e., a Java, SQL, or HTTP-XML step. A document management step is defined to perform the actual file upload and back end processing necessary to store that file in the location or repository where files are to be stored.

  1. The first task is to define an Add transaction for the file object. As with most add transactions, this one should include transaction properties matching all defined object properties. In the Mobile Northwind example application, the Document object encapsulates the file attached to a parent object. An Add transaction named AttachDoc is defined that targets this object type. It contains the following properties, matching those in the object:
    • File: External data property, initialized to empty, i.e. Initial Value: “Auto-Initialize.” There are some optional changes to the default attribute settings for this property, discussed in the next step of this procedure.
    • FileName: String property. This property is modified from the default initialization to a rule after data entry. A subsequent step in this procedure describes this modification.
    • BackEndFile: String property, initialized to an empty string. This value is not needed for transaction processing, as it only relates to downstream synchronization (e.g., fetch processing). However, it is good form to initialize the value in the add transaction.

    When the transaction is created, assuming the properties from the object were all selected in the add transaction wizard, there will be matching properties in the new transaction definition. In subsequent steps, a property to capture the parent object’s key property value is added to this transaction. First, the initial value of the FileName property must be defined to capture the name of the file on the client device.

  2. OPTIONAL: It is possible to provide a white list of files for file types the user can select, and to also provide a black list of specific files or locations from which the user may not make a selection. Once the external data property has been defined, viewing it in the Properties View of the Agentry Editor displays the three attributes of File Filters, Filter Description, and Restricted Files. File Filters can be set to one or more file types the user can select. Only files of that type will be displayed in the file dialog, and wild cards can be used (e.x., *.doc; *.jpg - Only MS Word Documents and JPEG images). The Restricted Files attribute must be set to an absolute path to the directories, or specific files, that the user will be allowed to select. Multiple paths can be provided and must be pipe delimited. (e.g. \\Windows | \\Program Files - No files can be selected from any path under these two locations.)

    If these attributes are set, the file dialog on the Agentry Client will present only those files and file types defined in the File Filters list, and will prevent users from selecting the files found in the Restricted Files. This is optional behavior and is not a requirement of this functionality. However, it is recommended that options for these attributes be at least considered to prevent users from attaching files that should not be transferred, e.g., executables, resource files, etc.

  3. The FileName property must contain the name of the file on the client device’s file system. This value is not needed during synchronization, but is used for display and reference purposes on the Agentry Client. The property is therefore modified by changing the Initial Value attribute to “Rule - after data entry.” The rule is then defined for this initialization to use the FILE_NAME function, taking the external data property in the transaction as its sole parameter. It returns just the name of the file, to store in the FileName property as required:

    With the change to the property’s initial value attributes, and the definition of the rule, the FileName property within the transaction is now defined to capture the name and extension of the selected file as stored on the client device. The rule contains a simple structure consisting of the FILE_NAME function that takes the external data property (File in the Mobile Northwind example) as it’s single parameter, returning the name of the file it references.

  4. Now that the transaction has been defined, the synchronization logic to update the captured information can be defined. We begin with the document management step responsible for updating the actual file to the back end system. Create a step of type File Document Management. Use the defined File system connection. Advance the wizard and on the enxt screen, set the Used By attribute to “Transaction - AddDocTransactionName”, where the second portion is the name of the transaction defined to add a file to a parent object. Set the Name and Group as desired and finish the wizard.

    In the Mobile Northwind example application the step is defined to be used by the transaction AttachDoc. The name of this step is CommitCustomerDoc. Next document mappings for this new step must be defined.

  5. The document mappings for a document management step used by a transaction define the source property in the transaction referencing the file being transferred, and how that file is to be provided to the command run by the document management step. For the Mobile Northwind example application, the File property contains the reference to the file being transferred. The command being run includes command line processes within the Subversion version control system. These commands expect the file to be stored on the file system. Therefore, the document mapping is defined as follows:

    • Property: The external data property of the transaction.
    • Input Type: How the file is to be provided to the command run by the step; for this example this is set to “File Input to Command Line,” meaning the file is stored on the file system by the Server prior to executing the command for this step. The other option is to stream the file data from the Agentry Server to a command being executed.
    • File Name: Where the Agentry Server should write the file to on the file system. This is disabled if streaming the file to the command. Note that the FileName property is provided for this attribute as a matter of convenience. This attribute specifies the name the file should be given when written to the file system by the Agentry Server. The value specified here can be any desired using any values available to the document management step. Like other steps, this is any value in the transaction, any globals defined in the application project, and any of the other available values for back end processing.
    • Delete File: Whether or not the file should be deleted. In this example the file is being written to the working copy location of the Subversion repository and therefore should not be deleted. In other cases, if this location is a temporary storage to allow the file to be processed and moved by the command, then this option should be selected to remove the file when its processing has been completed.

    Once the document mapping is defined, the Agentry Server will process the file as that mapping dictates, including which property contains the file, how to provide the file to the document management step’s command, and whether or not to clear the file from the file system when processing is completed.

  6. The command for the document management step must now be written. This command processes the file provided by the Agentry Server, either via a file written to the file system, or via a stream to standard input of the command being executed. The command written for the Mobile Northwind application is stored in a batch script and contains the Subversion commands add and commit. The add command adds a new file to the Subversion repository and the commit command commits that addition. The command is then written as follows:
    add <<FileTransfer.BackEndRepository>>/<<transaction.FileName>>
    commit <<FileTransfer.BackEndRepository>>/<<transaction.FileName>>

    When this command is defined, the file is first added to the repository and then subsequently committed to the repository. This is a required set of operations for Subversion. Other version control systems will handle new files differently. This processing assumes the file did not exist in the repository prior to this operation. If files are to be updated in any system, Subversion or others, the order of operations would be different. In general this command should be written only with a full understanding of how the back end stores files and how different situations are handled, e.g., new files vs. updates, etc.

  7. In most systems it is necessary to create the logical link between the file and the business entity to which it is attached. For example, in the Mobile Northwind application the table Customer Files exists in the Northwind database and contains the path to the file’s location in the version control repository and the Customer ID of the customer with which the file is associated. For this application a SQL step is defined containing an insert statement that adds the needed record to the table for a new file. Other information can be included, such as date and time information, file size, or any other meta data that may be needed.
  8. Once the steps have been defined, they must be used by the transaction. A server update step is added for each step involved in the processing of an attached file. In the Mobile Northwind application this includes the document management step and the SQL step discussed in this procedure. In most cases the recommendation is to first execute the Document Management step, followed by any steps that provide the link or other information about that file. This order of operations prevents there being any “empty links” should an error occur with processing the file.
  9. The final step in this procedure is to define the user interface for this functionality. This procedure is the same as defining the wizard for most other transactions. The screen set is defined, including the proper platforms, and finally the detail screen(s) and fields to capture the data from the user. The one item of note is the definition of the field for the external data property. The edit type of this field can be set to “External Data”, or left set to “-- Default --”. At run time, the Agentry Client recognizes that the target property of the field is an external data property and automatically displays a field that includes a control to launch a file dialog to allow the user to select a file from the file system. However, selecting the External Data field type explicitly can make it clearer when returning to this definition in the future. Once the wizard has been defined, the action for it and the transaction can be defined, followed by the control(s) to execute that action.

When this procedure is complete, users will have the ability to navigate to and select files on the client device. These files are then attached to the parent of the file object. During synchronization, the transaction processing will include uploading the file to the Agentry Server and then storing that file in the back end system

Next
A variation on the above functionality is the ability to allow users to select multiple files from the file dialog and attach them in one operation to a parent object. This requires the following differences in the definition of the transaction: 
<<foreach Documents

	copy <<my.FileName>> to <,FileTransfer.RepositoryDirectory>>

	add <,FileTransfer.Repository>>\<<my.FileName>> to repository

	commit <<FileTransfer.Repository>>\<<my.FileName>> to repository

>>
Parent topic: Attached Documents and File Transfer: Key Concepts