Document management

The Effector system is able to attach documents to particular business objects, furthermore it can store or look them up. This chapter introduces the prerequisites necessary for a smooth operation and summarizes the configuration options of attaching documents.

Working mechanism

Using the DocumentTextBox control on the interface, the user can select a file to be attached. Once the document has been selected, Effector uploads the file to a temporary directory on the server. Depending on the prior value of the input field, a window pops up inquiring if the currently uploaded document will be the new version of the previous one. (This mechanism can be turned off.) When the Save button is pressed, the framework renames and copies the file to its final location.

NOTE: Once the file copied to its final location, it gets deleted from the temporary storage. However, if the attachment fails, the file gets stuck in the temporary directory, so this directory should be emptied from time to time.

Environment settings required for the operation

For a proper operation, the following need to be set in system:

• We need to grant editing rights for the _temp\fileuploads\ directory in the Effector directory. The temporary files will be stored here.
• The AppPool allocated to Effector must run under a user ID with editing rights on the final document directory.

Database dependencies:

• Each row of the Document table represents a document version. The value of the ParentDocID field stores which document the given row belongs to (a version of which document can be found in the given row). The Version field contains the version of the row.
• DocumentConnection: : It is recorded in this table, that one Document row is assigned to which object (Event, Project, etc.). The trigger found on the Document table also inserts a row in this table, for which it uses the BoType and BoID columns found in the Document table.

NOTE: Using the BoType and BoID columns of the Document table for the joins on the interface is not advised. Instead, the same columns of the DocumentConnection should be used.

Configuration

DocumentTextBox

As discussed in the EditForm chapter, the DocumentTextBox control can be used to attach files.

NOTE: We can select a document from the database only if a Screen is set at the configuration of the DocumentTextBox, and the business object of the EditForm is not a BusinessObjectDocument! If these conditions are not satisfied, the system allows the attachment of new documents only. This is due to the configuration.

Configuration of attaching documents

A file called DocumentStoreSettings.xml has to be created in the root directory of the XML package. In this file, we can specify where and under which name the attached documents be saved. The file contains these settings according to object types; therefore, each document can have different settings. Furthermore, we can specify a default setting, which can be done by setting the value of the IsDefault node to true.

The settings pertaining to individual document types can be configured by using the DocumentStoreSetting elements of the DocumentStoreSettings collection. With the help of the nodes available here, we can specify the given type to witch the rules are applicable, as well as the rules the system uses when handling documents.

• The value of the DocumentObjectType node contains the name of the document subtype. With this setting, we can specify to which document type the entry belongs.
• Its location after copying can be set by using the TargetPathTemplate RuleValueType node (Rules). The return value of the rule specified here is a path which is always evaluated on the server. In this setting we can use [##Field.*##] and [##Filter.*##] references; the [##Field.*##] references can be the fields of the BusinessObject on which the DocumentTextBox control is located.
• The name of the attached document file can be specified using the TargetFileNameTemplate node, which is also a RuleValueType type node (Rules). Its return value is the name of the new file. In this setting we can use [##Field.*##] and [##Filter.*##] references; the [##Field.*##] references can be the fields of the BusinessObject on which the DocumentTextBox control is located.

Example

<DocumentStoreSettings>

    <DocumentStoreSetting>
        <IsDefault>true</IsDefault>
        <TargetPathTemplate type="SQL" return="string" default="">
            <![CDATA[
            DECLARE
            @base_path VARCHAR(2000)

            SET @base_path = (SELECT TOP 1 CodeValue FROM FSYS_ApplicationSetup WITH(NOLOCK) WHERE Code = 'DocBasePath' ORDER BY ApplicationSetupID DESC)

            SELECT @base_path + REPLACE(dbo.Oriana_Short_Date(GETDATE()), '-', '') + '\'
            ]]>
        </TargetPathTemplate>
        <TargetFileNameTemplate type="SQL" return="string" default="">
            SELECT dbo.ofn_CutAccent(dbo.ofn_RemoveSpecialCharacters_COLLATE(`[##Field.OriginalFileName##]`,`0-9a-zA-Z`))
        </TargetFileNameTemplate>
    </DocumentStoreSetting>
    <DocumentStoreSetting>
        <DocumentObjectType>Document</DocumentObjectType>
        <CopyPathTemplate type="SQL" return="string" default=""><![CDATA[ 
            DECLARE
                @base_path VARCHAR(2000)

            SET @base_path = (SELECT TOP 1 CodeValue FROM FSYS_ApplicationSetup WHERE Code = 'document_base_path' ORDER BY [ApplicationSetupID] DESC)
            SET @base_path = @base_path + 'Document\'

            SELECT @base_path
            ]]>
        </CopyPathTemplate>
    </DocumentStoreSetting>
<DocumentStoreSettings>

Attaching multiple documents at once

If the document is attached in a form where the BO is BusinessObjectDocument (or its descendant), it is possible to select and attach multiple files at once.

When value of IsMultipleFileUploadAllowed setting is true you can turn on the ability to upload multiple files. In this case, as many files are attached, as many Document rows are created. However, you can only select only one for modify.

Files that do not meet the size limit or allowed file types will not be attached but will be highlighted in the list. The tooltip of the given item will show the reason for the rejection.

The OnValidate rule runs on only one document (BO). With @AdditionalFileNames extension in the rule you can refer to further filenames, for example [##Field.DocumentID@AdditionalFileNames##]. File names will be separated by | and will contain only the names of the further files.

The AfterSave rule is also handled, but it is important that in this rule additional documents can only be referenced with their own fields (i.e. only values starting with [## Field.xx] will be replaced, [## Filter.xx] won't.)