Importing and Exporting Document Fields (Data Transfer)

If the view that you are importing to includes a Document field with associated documents, the import action imports the documents from server-side folders to the database afm_docs and afm_docvers tables.

When exporting data, if the view includes a Document field, and this field is visible in the view, any document files stored in the afm_docs and afm_docvers tables are saved into specified server folders.

Note: For general information about Data Transfer, see Data Transfer Overview.

Exporting the Inventory, Archibus Documents, and Archibus Document Versions Tables

Exporting the Inventory Table, exports the documents associated with that table. For instance, exporting the activity_log table exports all activity_log documents.

Exporting the afm_docs and afm_docvers table exports the document metadata: descriptions, version descriptions, dates of change, and authors.

Both match up again if they are re-imported into the same database. You can import the documents or the metadata first. It doesn’t matter, since the import rematches them based on their primary key.

If you don’t re-import the metadata, the documents can still be uploaded and downloaded. This condition can happen if you use the Project Update Wizard on the inventory tables, but not on the metadata tables.

Note the following about exporting document files:

Use Web Central to attach documents to records. Web Central has views that include a document field that you can use to attach a document to the record. For example, the view for defining equipment standards has a document field that you can use to attach an image of the standard that is used in reports. When you attach documents using Web Central, you can name the file whatever you want; the application will handle the naming of the file that the system requires. See Naming Conventions for Files and Folders, later in this topic.
Where to find exported files. The export action places the files in the following location:
C:\Users\Public\Archibus\projects\users\afm\dt." Notice, that there is a folder containing the image files, as well as a CSV file.
CSV is the preferred file format. Using the CSV file format gives you the most flexibility. For example, scripts used by the Database Update Wizard must use the CSV file format.

Procedure: Importing document fields

Note the following about importing files:

You will often import files that you have previously exported.
The import action looks for the files to import in the following location, so you will need to move your exported files there:
C:\Users\Public\Archibus\projects\users\public\dt\database-update\personalized-database
If using new files, you will need to follow the naming conventions below. To avoid this, you can attach a file to a record using a Web Central view, such as Define Room Standards. When you attach the file in this way, Web Central handles the naming.
The version of the image file may need to be changed. If you are importing document files that do not currently exist in the database, then all versions of the images should be "1." If there is an existing document (photo) in the database, the version must match the latest version in the afm_docvers table.
See Transfer Images In and Out of Archibus for a description of exporting and importing that uses an example.

Follow these steps to import document fields:

Export records from the source database
When importing , use the following folder structure and file naming conventions for the files:
- For the import file: [your_user_name]\dt\[your_csv_file]
  For example: afm\dt\activity_log.csv
- For the documents associated with the Document (doc field) of the table: [your_user_name]\dt\[your_table_name]\[all_your_image_files_for_the_table
  For example: afm\dt\activity_log\doc4^8665^1^activity_log-8665-doc4.png for a document image file associated with the Action Items table.
Make some change to the records to be imported (for example, a comment change), so Data Transfer recognizes a difference in the record.
Use Data Transfer to import the csv file.

For each subfolder name that is a table name, the application reads all file names in that subfolder.

For each file, the application:

Gets the primary keys of the document tables from the subfolder and file name.
If there is no corresponding afm_docs record, creates one.
If there is no corresponding afm_docvers record, creates one.
Reads the document into that afmdocvers record.

Naming conventions for folders and files

When you export views with documents, follow these conventions:

Folder naming

Store the document files in subfolders named after the Inventory Table to which they belong, for example,
[your_user_name]\dt\[your_table_name]\[all_your_images_file_for_the_table}
that is:
\afm\dt\activity_log\doc4^8665^1^activity_log-8665-doc4.png for a document associated with the activity_log table

File naming

Name the files with the primary key parts plus the file name, separating the parts with carats.

Name the file in this manner: fieldName+recordKey+docVersion+docName
The naming convention is: [documentFieldName]^[documentTableRecordKeyValue]^[documentVersion]^[documentFileName]
The Document Table (afm_docs) has Inventory Table (table_name), Inventory Field (field_name), and Inventory Primary Key (pkey_value) as its primary keys. The Inventory Primary Key is placed between the Inventory Table and the Inventory Field.
The Document Versions Table (afm_docvers) has those three fields plus Version (version) as its primary keys.

Ensure that the file name for each of the documents places the primary key between the Inventory Table Name (table_name) and the Inventory Field (field_name).

For example:

doc^5^1^msds_data-5-doc.pdf, where “5” is the primary key of the asset record to which the doc is associated, and msds_data is the Inventory Table name and doc is the Inventory Field.

Note: If a file name contains a carat (^) replace that with two carats (^^). This enables the application to distinguish between multi-part keys and the file name itself.

Example

Consider the activity_log table's two document fields: doc1 and doc2.

Following the conventions for directory naming and file naming discussed above, the files would be named and stored as follows:

\afm\dt\activity_log\doc1^1234^1^document1.pdf
\afm\dt\activity_log\doc2^1234^1^photo1.jpg

Automatically Named Files or Using File Names on the Server

The data transfer process can automatically name files, or instead use the name for the file stored on the server. The method used depends on the schema A/FM field’s definition of the field.

In the cases where the name is automatically generated, the application assigns file names using the following convention:

For example,

activity_log-doc-305.doc

If you previously imported documents using an older version of Archibus that used a different convention, the files are renamed using the new convention when you check in a new document, or check in revisions to existing documents.

If the file name is not automatically generated based on the schema A/FM field’s definition of that field, data transfer takes whatever file name is on the server and imports it. For example, the following file names are the actual file names on the server:

ConstructionContract_R01.doc and ConstructionContract_R02.doc

Document Version Information

If the document field supports multiple versions, a new record will be generated for each new document version checked in. If the document field does not support multiple versions, the table will contain one record for the single version that is checked in. This will be numbered version 0.

When multiple versions are supported, data transfer automatically updates the version number when documents are imported by incrementing the version number by one. The version number is used by the application to identify the document, so do not remove this number. In the following example, 1 is the version number:

doc^5^1^msds_data-5-doc.pdf