File system document adapter

CADMATIC eShare supports a couple of ways of accessing documents stored in a file system. You can create a database adapter with a document data source if the document metadata and folder hierarchy are defined in a database, as described in Document data source, but a much easier method is to use a file system document adapter.

You can enable CADMATIC eShare to access documents in a file system simply by defining the document base path in the adapter's data source configuration. To enable the system to also create links from 3D objects to relevant documents in that location, you must define suitable path detection patterns.

Note that if you want the Documents view to provide additional information about the documents in the tree, the file system document data source is limited to metadata provided by the file system, whereas a database document data source can use any attributes that you can retrieve by querying the document database.

Creating a file system document adapter

Create a file system document adapter, and then add a data source configuration to it, to enable CADMATIC eShare to connect to a file system and access documents.

Do the following:

  1. Navigate to the project to edit, and then click Project Admin in the main menu. The project administration view opens.
  2. Click Adapters and Data Sources. The Adapters and Data Sources configuration view opens.
  3. In the Adapters section, click Add.
  4. In the Available Adapter Types section, select File System Document Adapter, and then click Create adapter.
  5. In the Adapter section, enter a name and description (optional) for the adapter, and specify whether the adapter should be enabled.
  6. Click Save.

Related Actions

Add a data source to the adapter as described in Creating a file system document data source.

Creating a file system document data source

Add a data source to a file system document adapter to enable the adapter to provide access to document files and to enable objects in the 3D model to be automatically linked to documents.

Prerequisites

  • You know the base path to project documents stored in the file system.

  • To enable indexing, a suitable document type must be defined as described in Defining a document type. For example, the following settings allow all documents under the base path to be indexed:

    • Detection of Document Type

      Identifier Name: Path

      Pattern to Match: .*

    • Document Processing Rules

      Detection of Model Objects: Automatically

  • To define path detection patterns, you need to know what kind of information is stored in the file path or file name of documents, and how that information can be mapped to the attribute values of objects in the 3D model.

Do the following:

  1. Navigate to the project to edit, and then click Project Admin in the main menu. The project administration view opens.

  2. Click Adapters and Data Sources. The Adapters and Data Sources configuration view opens.

  3. On the Adapters list, click the file system document adapter to which to add a data source.

  4. In the Data Sources section of the adapter settings, click Add data source.

  5. In the Available Data Source Types section, File System Document Data Source is already selected—click Create data source.

  6. In the Data Source section, specify the following settings:

    • Name – Enter a name for the data source. This name will be shown in the Documents view of the project as the name of the top-level document folder, but it will not be visible in the 3D model viewer.

    • Description (optional) – Enter a description for the data source.

    • State – Specify whether the data source is disabled or enabled (default).

  7. In the Groups allowed to see the data section, select user groups that should be allowed to see the data that this data source provides.

    • If no groups are selected, only administrators will see the data.

    • Add user groups with Add.

    • Remove user groups with the remove button.

    • If the All Users group is selected, other group selections will be ignored.

    8. The Adapter Configuration section is not relevant for this data source type.

  8. In the Data Source Configuration section, specify the following settings.

    • Indexing — Select if document indexing is enabled. If you enable it, the system can search for object links in documents, store those links in the project database, and use this document index to create links from 3D objects to relevant documents. The documents must be found in the subfolders of the document base path. See Adapters and indexing.

      Note: If you save the data source configuration with indexing, all data sources of the same adapter with indexing enabled, will be indexed again.

      If Enabled, specify the following settings:

      • Indexing Speed – Define the duration of indexing.

        If you select Duration, specify the target duration of each indexing round in Target Indexing Duration field (in minutes). The set duration takes effect only after the first full round of indexing has been completed. The default is 120.

        If you select As Fast As Possible, the target of each indexing round is to be completed in the shortest time as possible.

      • Indexing Mode – Indexing is done every time the data source configuration is saved. Indexing can also be triggered manually from the Project Administration's General view.

        If you select Once, indexing is done only after saving.

        If you select Daily, indexing is done once every day.

        If you select Once per Days of Week, indexing is done once on the selected days.

        If you select Given Times in Days of Week, indexing starts on given times of the day on the selected days. The times are given in the server's local time.

        If you select Days of Month, indexing is done once on the selected days of the month.

        If you select All the Time, indexing is done continuously. Warning: This can consume a lot of resources if As Fast as Possible is selected as indexing speed.

    • Show documents inside ZIP files — If enabled, also documents that are inside .zip files can be read from the file system. If a .zip file contains documents whose file type is enabled in the File Types setting, the adapter takes the first document from the file. If the .zip contains files of different types, the document is selected using this preference order: .dgn, .dwg, .dxf, .pdf

    • Load Subfolders On Demand — If enabled, the entire document tree is not loaded at once, but the contents are loaded and visible following the user's examination. The default is Disabled.

    • Document Base Path — This mandatory setting specifies the base location under which documents are stored in the file system. Any subfolders that exist under this top-level folder are displayed as a tree in the Documents view.

    • File Types — Select which file types to display from the data source: .pdf, .dwg, .dxf, .dgn, Images

    • Additional File Types to Show — If the document data source adapter should support other file types, list them here. Separate the file types with a comma.

    • Path Detection Patterns — A path detection pattern allows the system to use .NET regular expressions to match attribute values of 3D objects to document paths in the file system, to automatically link objects and groups to documents. The matching is relative to document base path, and it looks for matches in folder names and file names. Click Add pattern, specify the pattern to use, and then click Validate to test that the pattern functions as expected.

      You can use object attribute names in the pattern to indicate that that part of the path should match the value of the specified object attribute.

      You can use Project Name and ProjectDatabase Name as variables in the pattern. These will be replaced with the name of the project and the name of the project database, respectively.

      To add a text string to the pattern, type the text and press Enter. 
      Free-form text is displayed with a black background.

      To add an attribute to the pattern, start typing the name and then select the appropriate attribute from the drop-down list. 
      Attributes are displayed with a blue background.

      Examples:

      • \System\Position Id\.*

        This setting finds documents that are located in any subfolders under a path where the name of the first folder is to match the System of the object, and the name of the second folder is to match the Position Id of the object. If both values match, the object displays links to the documents in this location.

      • .*\IsoPipeline.*

        This setting finds documents that are located in any level of the folder structure, if the document's filename starts with 'Iso', then contains the value of the Pipeline attribute, and the rest of the filename consists of any string.

  9. Click Save.

  10. If you defined a path detection pattern and used attributes in it, you can check that in the saved configuration any attributes are displayed in curly brackets: \{System}\{Position Id}\.*.

Results

In the Documents Browser of the project, you can browse the folder structure specified in Document Base Path and open documents that it contains.

If indexing is enabled, simple search can find indexed documents if the search term is like the value of the link.

When a user examines an object in the 3D view, if the object has properties that can be matched to a document index or path detection patterns, the related documents are listed in the details pane.