Drawing Code Handling

Contents

Drawing Code Handling
Examples
1. Example: Direct Mapping
2. Example: Indirect Mapping

Drawing codes are composed of components, each of which (generally) has a meaning.
The drawing code components can be mapped to classification (and other fields) in the Drawings record.
- Maps may be direct (to reference tables) or indirect, e.g. via drawing code map tables (see below).
There is a complex syntax described in SomePage (?)
- Drawing codes structures are defined in app/config/Settings-DrawingCode.php
- Drawing code functionality is implemented in app/lib/DrawingCodeBase.php

Drawing Code Definition

The drawing code definition is defined in:

The database table DrawingCodeTypeRef, where an id, code and name for each drawing code type is defined.
The configuration file app/config/Settings-DrawingCode.php, which defines all the components of each drawing code.

Drawing Code Component Definition

The drawing codes are defined in the $_CFG settings array.

Each Drawing Code has two parts:

DrawingCode - defines each drawing code component and separator
RevisionCode - defines:
- each revision code component
- revision numbering rules (starting revision number, are gaps allowed)
- file storage rules for the publish and source files (how the files are named internally)

Top-Level Configuration

$_CFG[ 'DrawingCodeDefinitions' ] = array(

  DrawingCodeTypeRef_DC1 => array( // KEJV: 14-C-9.99.999
    'name' => 'KEJV',

    'drawingCode' => array( // KEJV Drawing code definition
      'components' => array( ... )
    ),

    'revisionCode' => array( // KEJV Revision code definition 
      'components' => array( ... )
      ...
    ),
  ),

  DrawingCodeTypeRef_DC2 => array( // ...
    ...
  ),
),

Component Definition

Components are defined as a series of arrays (starting with component zero):

The following example shows a simple document code with three components:

Drawing Code

X

-

9999

Components

Component	Name	Description
X	Category	Engineering discipline, a single character taken from the field CategoryRef.code
-	Separator	Constant text
9999	Sequence	Four-digit sequence number, with the ability to ask it from the system

This is the definition in app/config/Settings-DrawingCode.php

   'drawingCode' => array( // Example drawing code definition
     'components' => array(
       array( // Component 0: Category - Direct map
         'name'               => 'Category',
         'tag'                => 'catagory',
         'type'               => 'select',
         'length'             => 1,
         'rmTable'            => 'CategoryRef',
         'rmCode'             => 'code',
         'rmName'             => 'CODE_NAME',
         'rmField'            => 'categoryId',
         'parse'              => '/^[A-Z]{0,1}$/',
         'pattern'            => '/^[A-Z]{1,1}$/',
         'fieldOut'           => 'categoryId',
       ),
       array( // Component 1: Separator - Constant text
         'type'               => 'constant',
         'value'              => '-',
         'parse'              => '-',
       ),
       array( // Component 2: Sequence number - Manual entry field
         'name'               => 'Sequence Number',
         'type'               => 'manual',
         'length'             => 4,
         'formatCode'         => '%04d',
         'fieldOut'           => 'drawingNo',
         'formatOut'          => '%d',
         'parse'              => '/^\d{0,4}$/',
         'pattern'            => '/^\d{1,4}$/',
         'getNext'            => 'getNextDrawingNo',
         'getNextPattern'     => array(0,1),
       ),
     ),
   ),

Notes about the components:

The category is a select field of a single character, and maps directly to the field Drawings.categoryId.
The separator is constant text.
The sequence number is a manual entry value, which must be numeric. It maps directly to Drawings.drawingNo.
The next free sequence number can be asked from the system (see getNext and getNextPattern).

Drawing Code Syntax and Keywords

Component Keywords

There are many component keywords. The complete list of valid keywords is defined below.

Keyword	Description
counterIn	Name of counter field (See below)
fieldIn	Name of field used for initializing the componenet value
fieldOut	Name of field to which the component value should be copied
formatCode	Printf style format code used for building the code
formatIn	Scanf style format code for converting the component into a value for entry
formatOut	Printf style format code used for converting the component into into the destination field
frameIn	Name of session frame variable for retrieving the conponent value
length	Component length in characters
mapId	Id value for an indirect map. Maps to DrawingCodeMapRef.mapId (see below).
name	Name of component, use for building a validation tag
nullClip	Number of characters to remove from code if this component is empty. For removing separators
parse	Length (if numeric), or constant text, or regular expression (if starting with slash character) used to parse/extract the component from user input
pattern	Length (if numeric), or regular expression used to parse/extract the component from the code
readonly	Set to true if the component cannot be modified
replaceIn	Two component array of: 1) search regular rexpresssion, 2) text that it should be replaced with
required	Set to false if component is options. Defaults to true if not present
rmCode	Direct map: Field name (from target table) to use as value for component (typically code)
rmField	Direct map: Target field name
rmFilter	Direct map: Filter field name, Typically contractId
rmFilterValue	Direct map: Filter constat value.
rmName	Direct map: Name of field(s) to display in list. Typically, code, name or CODE_NAME.
rmTable	Direct map: Target table name
tag	Message tag used to display component name
type	Component type. See below.
value	Constant text for fields of constant type.
getNext	Button appears beside this field on the form. Button tag and the name of the event generated by the button are the value of this option. Used to generate the next free DrawingNo, Part Number
getNextPattern	An array containing the indexes of the drawing code components participating in search for the next free value.

Component Types

Type	Description
constant	Component is constant text, typically used for separator characters.
counter	Component is a numeric counter. See below.
manual	Component is manual entry (e.g. no select list is available). Typically used for sequence numbers
select	Component is a select list, requires that a mapping is defined.

Revision Keywords

These keywords apply to RevisionCode definitions:

Keyword	Description
firstRevisionNo	Initial revisionNo value. Typically 0 or 1.
gapsAllowed	True is revisionNo gaps are allowed
publishFilenameFields	Used together with publishFilenameFormat for building filename. See below.
publishFilenameFile	How publish file is named internally on server. See below.
publishFilenameFormat	Used together with publishFilenameFields for building filename. See below.
publishFilenameName	How publish file is named when downloaded. See below.
publishFilenameReplace	Regular expression transformation of filename. See below.
revisionNumberComponent	The component number where the revisionNo appears. Required
sourceFilenameFields	Used together with sourceFilenameFormat for building filename. See below.
sourceFilenameFile	How source file is named internally on server. See below.
sourceFilenameFormat	Used together with sourceFilenameFields for building filename. See below.
sourceFilenameName	How publish file is named when downloaded. See below.
sourceFilenameReplace	Regular expression transformation of filename. See below.

Note that there are many ways for creating filenames, including two methods of creating filenames that are derived from the drawing/revision codes:

FilenameReplace - For performing regular express transformation for filenames.
Filename File/Name - For build more complex filenames.

Example of their usage are shown below.

Filename File/Name Handling

Filename handling refers to the technique (or strategy) for how file names are assigned to source and publish files.

This applies to the following fields:

publishFilenameFile
publishFilenameName
sourceFilenameFile
sourceFilenameName.

The filename handling determines how document files are named.

FilenameFile: Internal filename. Determines how the document files are named internally on the server
FilenameName: User filename. Determines how the file is named when the user downloads it.

Keyword	Value
code	The file must be named exactly according to the document code
format	The file name is determined by a regular expression transformation of the drawing code
free	The file name unrestricted
system	The file name is determined by the system, based in internal ids. See InternalFileNames.

Fielname Replace

FilenameReplace can be used for making relatively simple transformation from a drawing/revision code to a file name. Typically it us used to transform a drawing code's separator characters into alternate characters. A normal use is to durn periods (.) into underline characters (_).

The syntax is an array of search replacement pairs:

'sourceFilenameReplace' = array(
                                pattern-1, replace-1,
                                pattern-2, replace-2,
                                ...
                                pattern-n, replace-n,
                              ),

pattern - regular expression
replace - replacemet text

The pattern/replacements are applied sequentially in the order in which they were defined.

The following example shows an example where a drawing code has dots replaced with underlines and the leading underline in front of a black revision is deleted:

Drawing Code

Filename

CCC.9999.99.9999_A

CCC_9999_99_9999_A.pdf

CCC.9999.99.9999_

CCC_9999_99_9999.pdf

This is the definition:

'sourceFilenameReplace'  => array( '/\./', '_',  // 1. Replace dots with _
                                   '/_$/', ''    // 2. Delete trailing '_' for blank rev.
                                 ),

Filename Fields/Format

For building more complex filenames, FilenameFields and FilenameFormat, can be used to construct a filename using a printf-style format string and an array of components.

TODO: Complete this section.

'sourceFilenameFormat'   => '%s_%s_%s',
'sourceFilenameFields'   => array(  // code_sheet_rev
                              array(
                                'field'   => 'drawingCode',
                                'table'   => 'Drawings',
                                'replace' => array( '/\-{1,2}[0-9]$/', '' ),
                              ),
                              array(
                                'field'   => 'sheetNo',
                                'table'   => 'Drawings',
                                'default' => '1',
                              ),
                              array(
                                'field'   => 'revisionCode',
                                'table'   => 'Revisions',
                                'default' => '0',
                              ),
                            ),

Note that FilenameReplace and FilenameFields/FilenameFormat can both be used.

TODO: Check the order in which replace and fields/format are applied

Counters

TODO: to be completed

Drawing Code Maps

Drawing code maps allow classification (and other) fields to be directly set based on drawing code components. This is main mechanism for automatically setting classification fields based on a drawing code.

There are two kinds of maps

Direct maps - map a drawing code component value directly to the code of the target field
Indirect maps - which use DrawingCodeMap tables to map from a drawing code component
- value to one (or more) target field/values pairs.

Set the drawing code input fields based on a change in a classification field and v.v.

If the checkbox 'setClassifications' is checked on the new/update form, the drawing code input fields will be changed on a change in a classification field (see function setDCField() in drawmgt.js) and v.v. (see function populateValueById() in drawmgt.js).

The default value of 'setClassifications' is determined by $_CFG['SetClassifications']['Document'/'Revision']['New'/'Update']. All of these values are set to true in Settings.php. If you want, that drawing code fields and classification fields always correspond to each other, leave these configuration values true and set the checkbox 'setClassifications' to hidden (style="display:none") to disable overwriting of the default.

Examples

Example: Direct Mapping

Uses the rmTable, rmCode, rmName, rmField keywords.

Suppose a drawing code component requires a mapping from a single character code directly to the CategoryRef.code classification

The following definition is required:

   'drawingCode' => array( // Example drawing code definition
     'components' => array(
       ...
       array( // Component with direct map
             'name'               => 'Category',
             'type'               => 'select',
             'length'             => 1,
             'rmTable'            => 'CategoryRef',
             'rmCode'             => 'code',
             'rmName'             => 'CODE_NAME',
             'rmField'            => 'categoryId',
             'parse'              => '/^[A-Za-z]{0,1}$/',
             'pattern'            => '/^[A-Z]{1,1}$/',
             'fieldOut'           => 'categoryId',
           ),
       ...

Example: Indirect Mapping

Uses the mapId keyword.

Suppose a drawing code component requires the following indirect mapping:

Drawing Code	Mapping		Description
Component	projectPhaseId	categoryId
A	101 (1 - Design)	205 (E - Electrical)	Double mapping
B	102 (2 - Construction)		Single mapping
C		203 (C - Civil)	Single mapping
D	103 (3 - Planning)	205 (E - Electrical)	Double mapping
E			No mapping

The indirect mapping uses the following database tables:

DrawingCodeMapRef - Defines a drawing code component map (basically its name and id)
DrawingCodeMapCodes - Defines the code values allowed for the drawing code component
DrawingCodeMapValues - Defines mapping from the drawing code component values to classification id values

Define the map, which we arbitrarily call EX1, in the DrawingCodeMapRef table:

DrawingCodeMapRef
drawingCodeMapId	code	name	description	define
1001	EX1	Example Map	null	EX1

Define the possible component codes, which appear in the component's select list, in the DrawingCodeMapCodes table:

DrawingCodeMapCodes
drawingCodeMapId	code	contractId	name	description
1001	A	0	Design/E	null
1001	B	0	Construction	null
1001	C	0	Civil	null
1001	D	0	Planning/E	null
1001	E	0	Concept	null

Define the mappings of the codes to the target fields in the DrawingCodeMapValues table:

DrawingCodeMapValues
drawingCodeMapId	code	contractId	fieldName	valueId	valueChar
1001	A	0	projectPhaseId	101	null
1001	A	0	categoryId	205	null
1001	B	0	projectPhaseId	102	null
1001	C	0	categoryId	203	null
1001	D	0	projectPhaseId	103	null
1001	D	0	categoryId	205	null

Note that no record for code E is required in the DrawingCodeMapValues table.

The following component definition is required:

   'drawingCode' => array( // Example drawing code definition
     'components' => array(
       ...
       array( // Component with indirect map
             'name'               => 'EX1',
             'type'               => 'select',
             'length'             => 1,
             'mapId'              => 1001,
             'parse'              => 1,
             'pattern'            => '/^[A-Z]{1,1}$/',
           ),
       ...

Drawing Code	Filename
CCC.9999.99.9999_A	CCC_9999_99_9999_A.pdf
CCC.9999.99.9999_	CCC_9999_99_9999.pdf