Create drawings from models (Creo Elements/Direct Annotation) > Advanced topics > Customization for advanced users > BOM functions
  
BOM functions
The BOM functionality in Creo Elements/Direct Annotation can be controlled by a number of functions. The most important of these load BOM layouts and register attributes and text references. You can also disable the Scan Model button in the event that the WorkManager database is to be the sole source of BOM information.
The following sections explain the functions:
Loading BOM head, component, and flag layouts
Registering BOM attributes and text references (Without WorkManager) and Registering BOM attributes and text references (With WorkManager)
Setting the default attach mode and growth direction
A Complete BOM Registration Example
Loading BOM head, component, and flag layouts
A layout is the template that determines the appearance of BOM tables and position flags. You can load and register any MI file as a BOM layout. The three distinct layouts for BOMs are the following:
The head layout for the title of the BOM table. This layout can contain information about the BOM root assembly.
The component layout for the individual rows in the table.
* 
A valid table layout requires both a head and a component layout with the same UI-NAME option
The flag layout for the BOM position flags.
Values can be filled into special Registering BOM attributes and text references (Without WorkManager) that are applied to the layouts in the BOM layout customization menus. Loaded layouts can be edited in a temporary sheet 0 and then stored to file with the normal "Save Sketch" command. The figure shows typical BOM layouts.
BOM Layouts
The first graphic shows a table head layout (top) and a component layout (bottom), and the second graphic shows a flag layout.
The layout functions and their options are listed below. See the individual links for information about them. An Example is given below.
Syntax
(DOCU-LOAD-BOM-HEAD-LAYOUT --+--> UI-NAME option---->+--->
| ^
`--> FILE option------->'
(DOCU-LOAD-BOM-COMP-LAYOUT --+--> UI-NAME option---->+--->
| ^
`--> FILE option------->'
(DOCU-LOAD-BOM-FLAG-LAYOUT --+--> UI-NAME option---->+--->
| ^
`--> FILE option------->' DOCU-UNLOAD-ALL-BOM-LAYOUTS function
UI-NAME option
:UI-NAME specifies the layout name that will be seen in either the Sketch Layout or Flag Layout table. Related head and component layouts must have identical UI-NAME strings to define the whole table layout. Flag layouts are independent and need not share a table layout name.
Syntax
-->(:UI-NAME)----->|"interface name"|------->
FILE option
:FILE specifies the MI file used as the layout. Usually this would be a layout sketch saved with Save Sketch. The named file is automatically loaded by Creo Elements/Direct Annotation at start-up.
Syntax
-->(:FILE)----->|"filename"|------->
DOCU-UNLOAD-ALL-BOM-LAYOUTS function
The DOCU-UNLOAD-ALL-BOM-LAYOUTS function unloads (and de-registers) all previously loaded layouts. In the am_customize file (or in a separate file), use this function before instances of (DOCU-LOAD-BOM-...-LAYOUT ...) if you do not want the default layouts to be available.
Example
The following is an example of a layout registration:
(docu-load-bom-head-layout
:ui-name "Example1"
:file "/bom/head1.mi")
(docu-load-bom-comp-layout
:ui-name "Example1"
:file "/bom/comp1.mi")
(docu-load-bom-flag-layout
:ui-name "Example1"
:file "/bom/flag1.mi")
Registering BOM attributes and text references (Without WorkManager)
The functions described below apply when WorkManager is not being used. See Registering BOM attributes and text references (With WorkManager) for WorkManager-specific information.
Creo Elements/Direct Annotation provides a simple BOM generator. From a specified assembly it scans the model tree and generates BOM data for each object found. You can register particular attributes with related value functions to define the contents of the BOM.
The attribute functions, their options, and related functions are listed below. See the individual links for information about them. An Example is given below.
(DOCU-REGISTER-BOM-ATTR --+--> ATTR-TYPE option--------->+--->
| ^
|--> ATTR-TITLE option-------->|
| |
|--> ATTR-DISPLAY option------>|
| |
`--> ATTR-VALUE-FNC option---->' DOCU-UNREGISTER-BOM-ATTR-ALL function DOCU-UNREGISTER-BOM-ATTR function DOCU-REGISTER-BOM-TR-GROUP function DOCU-REGISTER-WMBOM-TR-GROUP function
ATTR-TYPE option
:ATTR-TYPE specifies the attribute type that determines the target text reference type. See also DOCU-REGISTER-BOM-TR-GROUP function.
Syntax
-->(:ATTR-TYPE)----->|"text reference type"|------->
ATTR-TITLE option
:ATTR-TITLE specifies the name of the BOM attribute as seen in the Current BOM Table.
Syntax
-->(:ATTR-TITLE)----->|"name in table"|------->
ATTR-DISPLAY option
:ATTR-DISPLAY specifies whether the BOM attribute should be displayed in the Current BOM Table. You can "hide" the attribute if necessary, although it will still be determined during a scan.
Syntax
-->(:ATTR-DISPLAY)----->|t or nil|------->
ATTR-VALUE-FNC option
:ATTR-VALUE-FNC specifies the function that determines the value of the BOM attribute. The value function must be defined before it can be registered. It has one parameter that describes a sel-item part or assembly, and it returns a string that holds the value to be filled into the BOM.
See also the A Complete BOM Registration Example of using Integration Kit functions for BOM attribute value functions.
Syntax
-->(:ATTR-VALUE-FNC)----->|#'value-function-name|------->
Note that for system-defined attributes, such as DOCU_BOM_QUANTITY, the system value function is used. However, the attribute must still be registered to appear in the BOM table. Use nil for the value function in these cases:
-->(:ATTR-VALUE-FNC)----->|nil|------->
(Note that the system attribute DOCU_BOM_POS_NO is automatically available, and does not need to be registered.)
See also the Example below.
DOCU-UNREGISTER-BOM-ATTR-ALL function
The DOCU-UNREGISTER-BOM-ATTR-ALL function de-registers all previously registered BOM attributes. In the am_customize file (or in a separate file), use this function before instances of (DOCU-REGISTER-BOM-ATTR ...) if you do not want the default BOM attributes to be available.
DOCU-UNREGISTER-BOM-ATTR function
The DOCU-UNREGISTER-BOM-ATTR function de-registers a previously-defined BOM attribute. You can specify any existing attribute's ATTR-TYPE option value, enclosing it within double quotes.
Syntax
(DOCU-UNREGISTER-BOM-ATTR "attribute type")
DOCU-REGISTER-BOM-TR-GROUP function
The Creo Elements/Direct Annotation BOM generator counts occurrences of shared parts and supplies this data in a system BOM attribute named "DOCU_BOM_QUANTITY". The default text reference group for BOM text references is "BFG". It is possible to specify a different group with the DOCU-REGISTER-BOM-TR-GROUP function.
All registered BOM attributes automatically generate new text reference types (of the same name) in this group. These text reference types are available in the BOM layout customization menus.
Note that the system text reference "DOCU_BOM_POS_NO" is used to display position numbers; it is made available automatically.
Syntax
(DOCU-REGISTER-BOM-TR-GROUP "group name")
Registering BOM attributes and text references (With WorkManager)
The following functions are applied in conjunction with WorkManager.
DOCU-REGISTER-WMBOM-TR-GROUP function
WorkManager delivers tables that define BOM attributes in title columns and the data in rows. The configuration table specifies which attributes are to be displayed in the BOM display table. Therefore, most of the customization must be done in WorkManager.
The default text reference group for WorkManager BOM attributes is "BFG". This can be changed with the DOCU-REGISTER-WMBOM-TR-GROUP function.
The system automatically obtains a list of WorkManager attributes under this name and generates new text reference types (of the same name) in this group. These text reference types are available in the BOM layout customization menus.
Note that the system text reference "DOCU_BOM_POS_NO" is used to display position numbers; it is made available automatically.
Syntax
(DOCU-REGISTER-WMBOM-TR-GROUP "WorkManager group name")
Example
The following is an example of a BOM attribute registration:
(defun docu-bom-attr-part-name (selitem)
(let ((contents-name (oli::sd-inq-obj-contents-name selitem)))
(if contents-name contents-name (oli::sd-inq-obj-basename selitem))
)
)
(docu-unregister-bom-attr-all)
(docu-register-bom-attr :attr-type "PART_NAME"
:attr-title "Part Name"
:attr-display t
:attr-value-fnc #'docu-bom-attr-part-name)
(docu-unregister-bom-attr "PART_NAME")
(docu-register-bom-attr :attr-type "DOCU_BOM_QUANTITY"
:attr-title "Quantity"
:attr-display t
:attr-value-fnc nil) ;; system BOM attribute
(docu-register-bom-attr :attr-type "PART_NAME"
:attr-title "Part Name"
:attr-display t
:attr-value-fnc #'docu-bom-attr-part-name)
Setting the default attach mode and growth direction
Attach Mode
You can set the default cursor attach point used when positioning BOM tables. The default is the center point of the table (MIDDLE_MIDDLE).
Syntax
(DOCU::DOCU-SET-CURRENT-BOM-ATTACH-MODE "position")
The position can be one of the following: UPPER_LEFT, UPPER_MIDDLE, UPPER_RIGHT, MIDDLE_LEFT, MIDDLE_MIDDLE, MIDDLE_RIGHT, LOWER_LEFT, LOWER_MIDDLE, or LOWER_RIGHT. Note that these options are case sensitive and must be entered in capitals.
Growth Direction
You can also set the default growth direction for BOM tables. This determines whether the BOM information is listed from top to bottom (down) or from bottom to top (up).
Syntax
(DOCU::DOCU-SET-CURRENT-BOM-GROWTH-DIR :GROW-UPWARD or :GROW-DOWNWARD)
A Complete BOM Registration Example
The following example demonstrates how to attach attributes to the model, and how to retrieve the attributes into the BOM.
;;-----------------------------------------------------------------------------
;; simple example how to implement BOM attributes using IK functions
;;-----------------------------------------------------------------------------
(in-package :my-special-bom-attr)
(use-package '( :oli ))
;;-----------------------------------------------------------------------------
;; functions to inquire attached BOM information of an SD part or assembly
;;-----------------------------------------------------------------------------
(defun bomattr-get-material (object)
(let ((attr (sd-inq-item-attribute object "MY_SPECIAL_BOM_ATTR"
:values :attachment :contents)))
(if attr (getf attr :material) nil)
)
)
(defun bomattr-get-partno (object)
(let ((attr (sd-inq-item-attribute object "MY_SPECIAL_BOM_ATTR"
:values :attachment :contents)))
(if attr (getf attr :part-number) nil)
)
)
;;-----------------------------------------------------------------------------
;; dialog to attach BOM information to an SD part or assembly
;;-----------------------------------------------------------------------------
(sd-defdialog 'my_special_bom_attr
:dialog-title "BOM Attr"
:start-variable 'object
:variables
'(
(OBJECT
:value-type :part-assembly
:modifies :contents
:title "Part/Assy"
:prompt-text "Select a part or assembly."
:after-input
(progn
(setq material (bomattr-get-material object))
(setq partno (bomattr-get-partno object))
)
)
(MATERIAL
:range ("Steel" "Aluminium" "Brass")
:title "Material"
:prompt-text "Enter material info."
)
(PARTNO
:value-type :string
:title "Part No"
:prompt-text "Enter part number info."
)
)
:ok-action
'(progn
(sd-attach-item-attribute object "MY_SPECIAL_BOM_ATTR"
:attachment :contents
:on-copy :copy
:on-merge :maintain
:on-split :copy
:on-xform :maintain
:filing '(:sd-file)
:values
`(
:material ,material
:part-number ,partno
)
)
)
)
;;-----------------------------------------------------------------------------
;; convenience functions to inquire attached BOM information
;;-----------------------------------------------------------------------------
(defun bomattr-get-material (selitem)
(let ((attr (sd-inq-item-attribute selitem "MY_SPECIAL_BOM_ATTR"
:values :attachment :contents)))
(if attr (getf attr :material) nil)
)
)
(defun bomattr-get-partno (selitem)
(let ((attr (sd-inq-item-attribute selitem "MY_SPECIAL_BOM_ATTR"
:values :attachment :contents)))
(if attr (getf attr :part-number) nil)
)
)
;;-----------------------------------------------------------------------------
;; examples of how to customize some simple BOM attributes
;;-----------------------------------------------------------------------------
(defun my-bom-attr-part-name (selitem)
(let ((contents-name (oli::sd-inq-obj-contents-name selitem)))
(if contents-name contents-name (oli::sd-inq-obj-basename selitem))
)
)
(defun my-bom-attr-part-no (selitem)
(let ((part-no (bomattr-get-partno selitem)))
(if part-no part-no "")
)
)
(defun my-bom-attr-material (selitem)
(let ((material (bomattr-get-material selitem)))
(if material material "")
)
)
(docu::docu-unregister-bom-attr-all)
(docu::docu-register-bom-attr :attr-type "DOCU_BOM_QUANTITY"
:attr-title "Quantity"
:attr-display t
:attr-value-fnc nil) ;; system bom attribute
(docu::docu-register-bom-attr :attr-type "PART_NAME"
:attr-title "Part Name"
:attr-display t
:attr-value-fnc #'my-bom-attr-part-name)
(docu::docu-register-bom-attr :attr-type "PART_NO"
:attr-title "Part No"
:attr-display t
:attr-value-fnc #'my-bom-attr-part-no)
(docu::docu-register-bom-attr :attr-type "MATERIAL"
:attr-title "Material"
:attr-display t
:attr-value-fnc #'my-bom-attr-material)