Document types

Document Type defines how CADMATIC eShare can turn text labels in a document into links that the user can click to open the referenced entities in the 3D viewer.

If all documents refer to model objects in a consistent manner, defining a single document type might be enough. Multiple definitions are needed for example when two document types contain text labels that have identical formatting but different purpose (label "1234" refers to System in one document type but to Sub-block in another), or when different document types require the target ID of links to be queried from a different attribute.

If the Document Types list contains more than one document type, you can rearrange the document types by dragging.

Document Types

About document metadata

Before defining a document type configuration for documents obtained from an external system, project administrator must define the document metadata that will be used to add links to the documents. This is done in the document data source settings of the adapter that CADMATIC eShare uses to connect to the external system.

If using a database document data source, the first selected value in the Document File Query is always used as the name of the document. This, and all other values in the query, are provided to the document parser as metadata fields.

In general, metadata fields are key–value pairs, where the key is a column name or alias from the Document File Query, and the value is the value of that column or alias. When entering the name of such metadata field into a document type configuration, make sure you type it correctly.

About document type detection

To enable CADMATIC eShare to add links to different types of documents, project administrator must define how document type can be detected from document metadata. This metadata might be stored in various locations: in a document attribute, in systematically assigned drawing numbers, or in a keyword in the document title. When the location is known, project administrator can configure the document adapter to store the document type information in a metadata field. This metadata field can then be used in the document type configuration, as described in Defining a document type.

When a user selects to open a document, eShare applies the document type definitions from top to bottom, looking for a match. Accordingly, the topmost definitions should match specific document types, and the last definition should match any remaining document type, so that all documents are mapped to a document type.

It is also possible to create a single document type definition that matches all documents:

If all documents are of the same type, you can use a metadata field that has a fixed value.
If there are several document types and type is stored in a metadata field, in the detection rule you can use a regular expression that matches all possible values of that metadata field.

About document processing rules

Document processing rules define which parts of a text string are converted into links, and how the IDs of the target items are formed. The simplest way to do this is to use the automatic detection rules. This compares every text element in the documents with known object and group IDs, and when it finds a match it links the text to the entity in the 3D model.

Automatic detection cannot be used in the following situations:

If IDs in document labels and in the 3D model are not identically formed. When this is the case, identifier detection rules can be used to detect the different spellings and convert them to match the IDs in the 3D model.
If IDs in document labels are not complete. For example, a part of the ID is omitted from the document because it is the same for all items in the document. When this is the case, identifier detection rules can be used to extract the missing part from a metadata field and add it to all IDs, so that they match the IDs in the 3D model.
If false matches occur because document contains text that looks like an ID but is not, and you know that this kind of ID should not be present in this type of document. When this is the case, you can create rules that only match valid IDs, and false matches are ignored. Note that it might not be possible to eliminate all false matches; for example, if IDs consist of digits only, any numbers in dimension labels can be detected as IDs.
If IDs in document labels do not exist in the model, but can be found from external data sources. For example, a P&ID might contain IDs of equipment and pipes that have not been modeled yet, but which already exist in the P&ID database and in other systems. The document type rules do not check whether the target ID exists in the model; an ID in the document only needs to match the formatting defined in the rule for a link to be created, and if there is an external data source to provide for it, the user can access it from the link.
If the text in the document labels is split to two or more rows (more than one character per row).

When automatic detection cannot be used, project administrator must specify how the system can detect the required text strings by configuring manual rules for detection.

You can mix document types that use automatic detection with those that use specific rules.

Here is an example of how document processing rules can be used:

In the document, find a text string that starts with the character "V" followed by three digits.
Combine the text string with the value of the "System" document attribute.
Find the combined value from the "Valve Position ID" attribute of model objects.

Using this rule set, if document metadata contains the attribute System=1301 and the document contains a text label with the string "V402", the text label is linked to valve whose position ID in the 3D model is "1301V402".

Defining a document type

In the Document Handling view, the Document Types settings allow project administrator to define how CADMATIC eShare should identify and process documents obtained from CADMATIC design applications or from an external data source. Document type specific document processing rules enable eShare to convert text labels into links, so that users can click a label to jump from a drawing to the related entity in the 3D view.

Prerequisites

A document adapter defines a document data source that contains documents. File System Document Adapter is the simplest method—it can access documents stored in the local file system or a mapped network drive. See Adapters and data sources.
To define Metadata Processing Rules, the metadata field has been defined in the document data source settings of the adapter.
To highlight links using colors that represent part's status, the required status tracking settings have been defined. See Status tracking and object grouping.
Document conversion format settings have been defined, if needed. See Document conversion formats.
You know how to use regular expressions. See About .NET regular expressions.

Do the following:

Navigate to the project to edit, and then click Project Admin in the main menu. The project administration view opens.
Open the Document Handling view.
In the Document Types pane, click Add. The Document Type Settings view opens for defining the following settings.
Intelligent Document Type

Name – Enter a descriptive name for the document type. Example: "Isometric Drawings".
Target Document Type
- External – Documents are obtained from some other system or application.
- Managed – Documents are published from CADMATIC design applications.
Show Managed Links – Set to Yes, if you want managed links to be visible. Default is Yes. Selection is visible, if Target Document Type is set as Managed.
Highlight Links – Set to Yes if you want the links that eShare adds to documents to be highlighted.

Document Link Coloring
- Color Links – If set to Yes, in the Link Coloring Configurations you can select links to be colored based on a specific property of the target objects.
- In Link Coloring Configurations, specify the following settings:
  Show/hide details
  - Name – Give the coloring configuration a descriptive name. This name is shown also in Document Viewer.
  - Color According to
    
    If set to Model, select a color from the color picker for:
    
    Show/hide details
    
    Object Found
    
    Object not Found
    
    Attribute not Found
    
    Show Legend – Set to Yes if you want a status color legend to be displayed in the documents.
    
    For information on configuring model attributes, see Attribute settings.
    
    If set to Status Tracking, specify these settings:
    
    Show/hide details
    
    Used Status Trackers – Select a status tracker from the list.
    
    No Category – Select a color from the color picker.
    
    Object not Found – Select a color from the color picker.
    
    Show Legend – Set to Yes if you want a status color legend to be displayed in the documents.
  To add a new coloring configuration, click Add new.
Detection of Document Type

Detection Method – At least one of the detection methods needs to be enabled. If both detection methods are enabled, both methods will be used when determining the document type. The opened document only uses this configuration, if it is from the listed data source, and it contains the specified metadata key with a matching pattern.
- If Metadata is enabled, specify the following settings:
  - Identifier Name – Enter the name of the metadata field to use for detecting document type. Enter "Path" to detect it from the file path.
    
    If the configuration targets managed documents, a drop-down menu of suggested identifier names is shown.
  - Pattern to Match – Enter a regular expression that Identifier Name must match to designate document type. If the value is a fixed string, just enter the string. Or, define a more complex expression, for example if only a part of the metadata field's contents can be used for detecting document type.
    
    If the configuration targets managed documents, a drop-down menu of suggested expressions is shown.
- If Data Source is enabled, specify the following setting:
  - Target Document Data Sources – Add a document data source. There can be multiple data sources.
    
    Note: All the documents under the listed data sources will use the configuration. If the configuration targets managed documents and detection method is set to Data Source, the configuration will target all the managed documents in the project.

Document Format
- Desired Format – "Default Format" keeps the format of the original document. To use a custom format defined in document conversion settings, select it from the list.
- Force Paper Size
  - No – Keep the page size of the original document.
  - Yes – Convert documents to the page size defined in the selected document conversion format.
Document Processing Rules

Specify how to link text labels in a document to objects in the 3D model.
- Metadata Processing Rules define which document metadata fields are to be used for constructing links.
  
  To add a field, click Add new and specify the following settings.
  - Source Field – Enter the name of the metadata field to use. Make sure you type the name correctly.
  - Processing – Select whether to use the metadata field's value as-is, or to extract only a part of the value. If you choose the latter option, an additional field is displayed; in this field, enter a .NET regular expression that extracts the required value and contains named capture groups, and then use those groups in the Target ID Format field of the Identifier Detection Rules section.
- Extract Metadata from Documents – If set to Yes, a preview window with a document affected by the document type configuration appears. To change the document used in the preview, modify the configuration in Detection of Document Type section.
- Metadata Extraction Rules – Shown when metadata extraction enabled.
  
  To add metadata extraction areas to the document, select Add new. A new rectangular area with two crosses in opposite corners appears in the preview window. The area can be moved by dragging the crosses. The new rule is also added below the preview window.
  - Pattern specifies which parts of the text within the metadata extraction area should be extracted, and what they should be called. The pattern should be a regular expression with at least one named capture group, marked with <> notation. All of the named capture groups can be used in Identifier Detection Rules to generate links. By default, a rule is assigned a pattern that extracts all text in the area within a single named capture group.
  - Origin Corner defines which corner the metadata area anchors itself to. This means that the area will always stay at the same distance from the corner, regardless of document size. By default, the origin corner is set as Bottom Left.
  - Page defines which page of the opened document the metadata area will be used on. When a new rule is created, its page is automatically assigned to be the page number currently open in the preview document. The document preview only shows metadata areas assigned to that page. The value can be a negative number. In this case, the page of the metadata area will be counted from the end of the document. For example, page value set as -1 refers to the last page of the document, -2 to the second to last, and so on.
  To test the metadata extraction rules on the preview document, select Test Extraction Rules. The test outputs a table with the metadata keys on the left (capture group names), and the extracted results on the right.
- Identifier Detection Rules enable the system to detect text that matches a given pattern and link the text to the related entity in the 3D model. When the user opens a document that contains text strings, the first identifier detection rule that matches the text is used. Accordingly, the topmost rules should identify some special cases, and these would be followed by more general rules, so that all required texts can be converted into links.
  
  If text labels consist of multiple lines, see Linking multiline text strings.
  - Automatic detection of model objects and Automatic detection of smart points.
    
    The automatic detection of smart points compares the document to the external IDs of smart points.
    
    Select the check box for the rule(s) to use. The configuration is shown when the rule is enabled (check box selected). Click Show Options for each rule to specify the following settings:
    - Maximum Combined Line Length – Sets the maximum length of components that are used to define a label. The default value is 3. Increasing this can help find additional labels, but it may affect performance. When the field is left empty, the default value is used.
    - Line Item Search Range – Sets the relative size of the area used to search for components of a label. The default value is 2. Increasing this can help find additional labels, but it can affect performance. When the field is left empty, the default value is used.
    - Maximum Line Number – Defines the number of lines in a document that can be combined to a single link. The default is 2. When the field is left empty, the default value is used.
  - Pattern rules – Configuration is displayed when the rule is enabled (check box selected).
    
    Note: AI support can be configured by system administrator to assist in creating a configuration. When AI support is enabled, Ask AI button is shown. See AI assistant.
    
    To create a new rule, click Add new and specify the following settings:
    - Pattern rule name – Enter a name for the pattern rule or use the default name. The field cannot be empty.
    - Pattern to Match – Enter a .NET regular expression that can capture the required text strings. By using named capture groups in the pattern, you can use the whole captured text or just parts of it, and then use the groups in the Target ID Format field.
    - Target ID Format – Specify how the ID of the target object or group in the 3D model is formed. You can use the following elements:
      - Metadata fields or parts of them, as defined in the Metadata Processing Rules section.
      - Named capture groups from the Pattern to Match field.
      - Text strings.
    - Target Type – Select whether the target in the 3D model is:
      - Any model item – The target can be any type of item. The attribute of the item must be either its key attribute or a group defining attribute.
      - Model items identified with an attribute – The target can be only items whose identifier is a specific attribute. If this is selected, an additional Attribute field is displayed, and you can select the attribute or its abbreviation from the drop-down menu. The attribute of the item can be either a key attribute, a group defining attribute, or a normal attribute.
      - Smart Points – The target is Smart Points. If this is selected, an additional Smart Point Type field is displayed, and the used Smart Point Type must be selected. The target type must have an External ID attribute in use.
    - Click Show Options, if you want to specify the following settings for the pattern rule:
      - Maximum Combined Line Length – Sets the maximum length of components that are used to define a label. The default value is 3. Increasing this can help find additional labels, but it may affect performance. When the field is left empty, the default value is used.
      - Line Item Search Range – Sets the relative size of the area used to search for components of a label. The default value is 2. Increasing this can help find additional labels, but it can affect performance. When the field is left empty, the default value is used.
- Click Show Options, if you want to specify the following settings for the document processing rules:
  - Skip Pages From Start – If you set a positive value to the field, the link injection will skip the set number of pages from the start, such as title page or revision information. The default is 0, which means no pages are skipped. When the field is left empty, the default value is used.
  - Skip Pages From End – If you set a positive value to the field, the link injection will skip the set number of pages from the end. The default is 0, which means no pages are skipped. When the field is left empty, the default value is used.
Click Save.
To apply the settings, publish the 3D model.