Overview:
The DocItemConfig rules specify options and characteristics for document Items as well as the defaults for the Get Existing Items dialog box.
The DocItemConfig rule group is found in the Rules Maintenance tool on the System Admin Dashboard. Each rule in the group consists of a rule name, a filter value (which can be blank) and a result value.
Filter Value:
Any Doc type
The DocItemConfig rules accept a Doc type (as defined in the Doc Types tool and appearing on the filter drop-down) as the filter value.
Result Value:
Varies
Result values for the DocItemConfig rules depend on the rule and are indicated within the description of each rule. Some rules are enabled and disabled through a checkbox in the result value, for example:
Rules:
AccountEncoding
Specifies (in the result value checkbox) whether the GLAcct, GLSubaccount and Account Category fields should be automatically initialized based on internal logic using Vendor and Cost Cost. (See also the DocTypeConfig | CanEditEncoding rule in KBA-01154.)
- unchecked = No (default for most Doc types).
- checked = Yes (default for CCO, RFQ and Commitment).
AlwaysAllowUnits
Specifies (in the result value checkbox) whether unit columns will render even when there is no other units data.
- unchecked = No (default). Unless the current Item has a UOM code with the Enable Units flag on (in the Code Maintenance tool) or there is prior unit data detected, the unit field will be hidden.
- checked = Yes. Even if the current Item has a UOM code with the Enable Units flag off, the unit field will be displayed and allow input.
AutoCopyMoveAttachments:xx
Specifies (in the result value checkbox) whether Item attachments should be moved from old Items with the specified status to new Items, when Items are duplicated through the AutoCopyWhen rule (below). xx can be any ItemStatus code as defined in the Code Maintenance tool.
- unchecked = No, Item attachments will not be moved.
- checked = Yes (default).
AutoCopyResetFields:xx
Specifies (in the result value) the nullable fields in xsfDocItem that should be set back to null when a new Item is created by the AutoCopyWhen rule (below). xx can be any ItemStatus code (as defined in the Code Maintenance tool). The result value can accept a list of fields separated by semicolons. The default is Received.
- 0 = disable this rule.
AutoCopyRevItemNum
Specifies (in the result value checkbox) whether Items added (usually by the AutoCopy feature) should use the Item revision (if numeric) to update the current Item number. Notes: A set of documents that share a register should use the same result value for this rule. Errors can result if a prior revision of an item is reset and copied again (due to duplication of the item number revision).
- unchecked = No (default). A new Item number will be generated.
- checked = Yes. The new Item number will be the current Item number with the new .rev# added (0123.2 becomes 0123.3)
AutoCopyRevItemNumFormat
Specifies (in the result value) the format for incremented revision numbers. Default is “G”. Use 00 as the result value for a two digit number with a leading zero.
AutoCopyWhen:xx
Specifies (in the result value checkbox) whether the AutoCopy feature for the specified status should be enabled. xx can by any ItemStatus code as defined in the Code Maintenance tool. When enabled and an Item is saved with the corresponding ItemStatus code, the Item is copied as a new Item on the same document. The new Item is given the status of (O)pen and the Item revision (if numeric) is incremented. For example, AutoCopyWhen:RR is used to copy a Submittal Item when the Item is saved with a status of Revise/Resubmit.
- unchecked = No (default for most Doc types).
- checked = Yes (default for Submittal Packages and Submittal Item Register).
CanGetItems
Specifies (in the result value checkbox) whether the Get Existing option will be available on the Item Options menu.
- unchecked = No.
- checked = Yes (default)
CanPasteItems
Specifies (in the result value checkbox) whether Items will be allowed to be “cut” and “pasted” into Item folders.
- unchecked = No.
- checked = Yes (default).
CanRenumberItems
Specifies (in the result value checkbox) whether the Renumber option on the Items Options menu will be enabled.
- unchecked = No.
- checked = Yes (default).
CostCodeWidth
Specifies (in the result value) the number of width units for the Cost Code display field. The default is 20.
CrossProject
Specifies (in the result value) if Items on the Get Item lookup (Get Existing option) should come from the same or other project.
- 0 = from same project only.
- 1 = from any project.
- Project ID = from the template project indicated by the Project ID (without mask characters).
DefaultAcctCategory
Specifies (in the result value) the default Account Category for new Items. There is no default.
DefaultBillable
Specifies (in the result value checkbox) whether new Items will be marked billable by default. This rule sets xsfDocItem.Billable; interpretation may vary by Doc type.
- unchecked = No.
- checked = Yes.
DefaultFieldList
Specifies (in the result value) the semicolon-separated list of field names and values to be set when a new Item is added. The values are set near the end of the Item creation (after NewItemsLike and DefaultBillable and other such rules have already been applied). The syntax is targetfield=sourcetable.field;targetfield=value; When sourcetable is omitted, the value is assumed to be a simple assignment. Use value NULL to set a field to DBNULL. Use ~= to set the field only if it is still null. Possible source tables are DocMasterDetail, DocRevision and DocRoute (for first route only).
Examples:
- 0 (default; no fields are set)
- MarkupControl=0; (makes the Cap checkbox unchecked OFF by default)
- ProjectReference=DocMasterDetail.Project; ItemStatus=A;AccountCategory=EXPENSE; (copies the Project ID into the Item’s Project Column, sets the Item status to A and sets the Account Category to EXPENSE, overriding the DefaultAccountCategory rule, if any).
- ResponsibleParty~=DocMasterDetail.ResponsibleParty; copies the document header responsible party into the new item if it is still empty
DefaultGetItemMode
Specifies (in the result value) the default mode for the Get Item option on the Item Options menu. (See also the DocTypeConfig | CanCopyItems rule in KBA-01154.)
- Copy = copy Items to the new document.
- Move = move Items to the new document.
- Linked = copy Items to the new document and maintain a link with the original document (applicable only to Commitment-dependent Doc types such as CCO, Pay Request and Receipts.)
- Register = linked to the item register (see UseRegisterDoc below); Default when UseRegisterDoc and GetItemModeList includes Register.
DefaultRevisionNumber
Specifies (in the result value) the default starting Revision Number for Items. There is no default; therefore, a starting number must be provided. For using the “revise and resubmit” feature, good choices are 0 and 1. AutoCopyRevItemNumFormat is not applied, so specify the extract string you wish use. Leading and trailing spaces are removed. Note that AutoCopyRevItemNum requires a simple numeric.
DefaultSort
Specifies (in the result value) how the document Items should be sorted initially. Commas are allowed for sort lists and a space followed by DESC makes the column sorted in descending order. Some example result values:
- AUTO = sort by Item Number if visible (in UI CFG) or by the first visible sortable column if Item Number is not visible (default).
- cmpItemSeq = sort by position; enables drag and drop in UI
- Specification,RevisionNumber = sort by Spec on Submittal Item Register (or related)
- DocItemNumber = Sort by DocItemNumber
- Column = sort by the column specified (as named in the Doc Item table).
- Cmpname = sort by the cmp computed value.
DocCopyItemFilter
Specifies (in the result value) the filter to be applied when copying Items from one document of a specific Doc type to another. The filter is used by the Doc Copy dialog box and the Meeting Minutes “create next meeting” function. The result value accepts a Boolean expression that references fields in the xsfDocItem table, its parents and its children, for example: DocCopyItemFilter = not itemstatus in ( ‘C’ ). Note: for this value to matter, the DocTypeConfig | CanCopyItems rule must be enabled. By default, Doc types (except for Meeting Minutes) do not use filters when copying Items.
ExpandWhenAdded
Specifies (in the result value checkbox) whether a new Item should be shown in Detail view when the Item is first added.
- unchecked = No (default). The Item is shown in Grid view.
- checked = Yes. The Item is shown in Detail view.
ExpandWhenSingle
Specifies (in the result value) how an Item is to be displayed when you first go to the Items tab on a document with only one Item.
- Auto = display the single Item in Detail view only if the Item has no description; otherwise, display the Item in Grid view.
- No = display the single Item in Grid view, not expanded (default).
- Yes = display the single Item in Detail view, expanded.
GetAllItems
Specifies (in the result value) how the Get All option on the Items Options menu will function.
- Auto = automatically copy all Items into the target document.
- No = disable the Get All option on the Item Options menu.
- Smart = automatically copy all open Items into the target document (default for Receipt and Pay Request).
- Yes = offer the Get All option on the Item Options menu (default for all Doc types except Receipt and Pay Request).
GetItemModeList
Specifies (in the result value) the options to be offered by the Get Existing Items dialog box for the specified Doc type. The result value accepts any combination of the following, without commas. See also the DefaultGetItemMode rule (above).
- C = Copy (see also the ItemCopyMode rule below).
- M = Move (see also the ItemMoveMode rule below).
- L = Linked (applicable only to Commitment-dependent documents such as CCO, Pay Request and Receipts).
- R = Register; (requires UseRegisterDoc below)
- W =WBS (Work-Breakdown-Structure).
GetItemsFromRegister
Specifies (in the result value) the label for the “Get Existing form the Item Register” option. The default is Copied from Register.
- 0 = disable this rule.
GetItemFromRegisterLookup
Specifies (in the result value) the lookup and validation used by the Get Existing Item dialog in Item Register mode. This is an advanced rule. The format of the result value is LookupName;ValidationName;AltValidationName;DependsOnValues where
- LookupName is the name of a distributed or custom lookup defined in xsfLookup. The default is DocItemList;
- ValidationName is the name of a DV from xsfLookupResult. The default is DocItem;
- AltValidationName is the name of a DV from xsfLookupResult that takes text and returns a key. The default is DocItemAlt;
- DependsOnValues is one to four UI elements or #field.table references (separated by commas) and passed to the lookup. The defaults are #DocMasterDetail.DocTypeKey,#DocMasterDetail.DocMasterKey,#DocMasterDetail.Project,rblMode. See DependsOn in KBA-01336.
GetItemFromSC
Specifies (in the result value) the label for the “Get Existing from Commitment” option. The default is Copied from Commitment.
- 0 = disable this rule.
GetItemsFromSCLookup
Specifies (in the result value) the lookup and validation used by the Get Existing Item dialog in Linked Commitment Line mode. This is an advanced rule. The format of the result value is the same as described for GetItemsFromRegisterLookup (above). In this case the defaults are:
- SCOLineItem;
- SCOLineItem;
- ;
- DocMasterDetail.Project,#DocMasterDetail.SubContract.
GetItemFromWBS
Specifies (in the result value) the label for the “Get Existing from Budget” option. The default is Budgeted Work Breakdown.
- 0 = disable this rule.
GetItemsFromWBSLookup
Specifies (in the result value) the lookup and validation used by the Get Existing Item dialog in WBS mode. This is an advanced rule. The format of the result value is the same as described for GetItemsFromRegisterLookup (above). In this case the defaults are:
- WBSLine;
- WBSLine;
- ;
- txtProjectLookup
GetItemsFromWBSQuery
Specifies (in the result value) the qAlias to be run in order to return data for added items. The query should return data for all rows in the WBS and the first column should contain WBCode: Account (e.g., 16000: SUB). If the query includes a column (with a non-null value in the row matching the added cost code and account) that matches the name of a column in xsfDocItem or xsfDocItemTask, then the corresponding item column is set to the query value. The result value (say qWBSLine) for this rule should be defined in a rule entry for QueryConfig | qWBSLine:Alias
GetItemLookupNumberFrom
Specifies (in the result value) the field to be shown as the item number. Default is ItemNumber. Other choices are: DrawingNumber, Specification, SourceItemNumber, SOVLineNumber
GLMapFrom
Specifies (in the result value) the source field from a document to be used when automatically populating the GL Account number field.
- BudgetRevID = use the internal budget revision number.
- Company = use the name of the company.
- DocBatchNo = use the Document batch number.
- DocNo = use the Document number.
- Location = use the Location.
- PayControl = use the Pay Control.
- PayItemNumber = use the Pay Item number.
- Project = use the Project ID.
- ProjEntity = use the Cost Code.
- RejectCode = use the Reason or Reject code.
- Section = use the Section.
- Source = use the Source Item.
- SourceDocNo = use the Source number.
- SOVItemNumber = use the SOV Item number.
- Status = use the document Status.
- SubContract = use the Commitment Doc number.
- Subtype = use the Subtype.
- Title = use the Title or Description.
GLMapLen
Specifies (in the result value) the number of characters in the GLMapFrom rule (above) to be used when automatically populating the GL Account number field. The result value accepts any number less than or equal to 256. Note: the GLMapStart and GLMapLen rules work together.
GLMapStart
Specifies (in the result value) the starting position in the GLMapFrom rule (above) to be used when automatically populating the GL Account number field. The result value accepts any number less than or equal to 256. Note: the GLMapStart and GLMapLen rules work together.
GLMapValuen
Specifies (in the result value) the alphanumeric value to be used as the GL Account number for the indicated n value (for example, 16 in GLMapValue16).
ItemAccess
Specifies (in the result value) the access that Contacts have to Items on a document. When the result value is R or C, individual users can be granted additional access through corresponding role capabilities: DOC | Permissions for any item on the document or DOC | Can see all items that have the same company. (For more information about role capabilities, see the Designing User Roles technical white paper.)
- A = provide all Contacts view access to all Items.
- C = provide Contacts view access to all Items for which their company is responsible.
- R = provide Contacts view access only to Items for which the Contact is responsible (default).
ItemCopyLookup
Specifies (in the result value) the lookup and validation used by the Item Copy dialog in Copy mode. This rule is an advanced setting. The format of the result value is the same as described for GetItemsFromRegisterLookup (above). In this case the defaults are:
- DocItemList;
- DocItem;
- DocItemAlt;
- #DocMasterDetail.DocTypeKey,#DocMasterDetail.DocMasterKey;#DocMasterDetail.Project,rblMode
ItemCopyMode
Specifies (in the result value) the Copy choice on the Get Existing Items dialog box. The default for most Doc types is Copied from another document.
- 0 = disable this mode so that no Copy choice appears on the dialog box.
- any text = use this label for the Copy radio button on the dialog box.
ItemDescriptionRequired
Specifies (in the result value checkbox) whether a Description is required for each Item.
- unchecked = No (default).
- checked = Yes.
ItemMoveFieldList
Specifies (in the result value) the semicolon-separated list of field names to be copied from the source document to the target document after the item has been successfully moved. The filter value is the type of the target document of the item migration. The syntax is targetable.field = sourcetable.field (so, for example, DocRevision.NoteA=DocRevision.NoteB would copy NoteB from the source document to NoteA in the target document). You can also specify targetable.field=NULL;. When sourcetable is omitted, the document header is assumed. When targetable is omitted, the source table is assumed. Note that initially the field source is the same as the item source. Include *SWAP; in your field list to swap source and target. There is no default. Zero means do nothing. Other possible tables are DocRevision and DocRoute (for first route only).
ItemMoveFinalStatus
Specifies (in the result value) the new status for the source document (from which an item was just moved) if in fact that item was the last item (so there are no more items on the document). The filter value is the type of the target document. Since the source document is the destination of the status, this rule does not validate the specified result value against the document status code list; double check your result value. Default is C for canceled.
ItemMoveLookup
Specifies (in the result value) the lookup and validation used by the Get Existing Item dialog in Move mode. This is an advanced rule. The format of the result value is the same as described for GetItemsFromRegisterLookup (above). In this case the defaults are:
- DocItemList;
- DocItem;
- DocItemAlt;
- #DocMasterDetail.DocTypeKey,#DocMasterDetail.DocMasterKey;#DocMasterDetail.Project,rblMode
ItemMoveMode
Specifies (in the result value) the Move choice on the Get Existing Items dialog box. The default for most Doc types is Moved from another document.
- 0 = disable this mode so that no Move choice appears on the dialog box.
- any text = use this label for the Move radio button on the dialog box.
ItemNumberFormat
Specifies (in the result value) the number of digits for Item numbers, and if the optional document number prefix is included. The default for many Doc types is D-3 (which means three digits with prefix). The result value accepts a number, with or without the prefix D-. When configuring a family of documents with a shared item register, the child documents must use a different ItemNumberFormat than the register itself (see KBA-01683 step 5B). Other Doc type defaults are shown below:
ItemStatusForDocApproval
Specifies (in the result value) the status to which open Items should be changed when the document is first saved with an approved status. The result value accepts an ItemStatus code (as defined in the Code Maintenance tool). (See also the DocItemStatusIsClosed rule group.) Specify zero(0) to disable the action. Beginning with V2021, Spitfire also checks this rule when Change Orders are posted (revenue or expense, by both Potential and Final Change Order document processes) to determine the new status.
ItemStatusforDocClosed
Specifies (in the result value) the status to which open Items should be changed when the document is first saved with a closed (but not approved) status. The result value accepts an ItemStatus code (as defined in the Code Maintenance tool). (See also the DocItemStatusIsClosed rule group.)
JSIncludes
Specifies (in the result value) the JavaScript resources that should be included when the Item tab is rendered. Spitfire includes two resources—PCOAmountCalculations and SPRAmountCalculations—that are used by Change Order and Commitment-related documents. If no slash ( / ) is included in the result value, the /cscript/ folder and a .js extension are assumed.
JSInput
Specifies (in the result value checkbox) whether the server should accept client-side calculations passed back to update the Item grid.
- unchecked = No (default for most Doc types).
- checked = Yes (default for Commitments and Pay Requests)
JSReady:scriptname
Specifies (in the result value) the JavaScript resources that should be injected into the “On Document Ready” client-side event to initialize client-side features. Scriptname can be any one of the resources that are valid for the JSInclude rule (above). There must be a JSInclude rule for the Doc type that specifies the corresponding scriptname in order for the JSReady rule to take effect.
NegativeRetention
[V23+] Specifies (in the result value checkbox) whether credit lines on Commitment Change Orders (CCOs) and Pay Requests should allow retention.
- unchecked = No (default).
- checked = Yes.
NewItemsLike
Specifies (in the result value) which prior Item to use to provide defaults for new Items. Note [V2020+]: Result values below can be combined. If the result value is 4, or a summed number that includes 4 (for example, 5 because 1+4=5), a copy icon will appear on all Item rows.
- 0 = disable this rule.
- 1 = use the first Item by default.
- 2 = use the last item by default.
- 4 = allow the user to select which Item to use.
- 16 = allow the user to add multiple Items at once.
- 32 = apply the AutoCopyResetFields rule (above). Note: unlike in other scenarios, this usage of AutoCopyResetFields always uses the default Item status because the new Item is always brand new.
- 64 = use the selected item only once (must modify 4, so use 68); causes the default for new items to return to empty.
PDFMerge
Specifies (in the result value) the name of a merged PDF file and enables the merging of all PDF files (converted from DOC*, XLS*, JPG, TIF, PNG and GIF files attached to Items) with the Item Cover printout when creating an outbound email. Since most implementations will require a unique PDF name for each Item, the result value also accepts replacement markers. These markers can be any string value form the DocItem alias (xsfDocItem). For example, Ref-$$SPECIFICATION$$($$PARAGRAPH$$)-Rev#$$REVISIONNUMBER$$ creates filenames based on specification, paragraph and revision. The resulting file would look like Ref-ABC(3)-Rev#3b.pdf. Note: PDFMerge has no effect if there is no Item Cover template for the Item. For information about Item Cover templates, see the Focus on Documents and Items guide.
Renumber
Specifies (in the result value) if Items from the Get Item dialog (Get Existing option) should be renumbered to match the Item numbering of the target document.
- Always = always renumber Items. Users cannot override numbering.
- Never = never renumber Items. Users cannot override numbering.
- No = do not renumber Items, but allow users to override numbering.
- Yes = renumber Items, but allow user to override numbering.
RenumberSeq
Specifies (in the result value checkbox) whether the Item Number Sequences should be automatically updated to reflect the DefaultSort.
- unchecked = No.
- checked = Yes (default), except for SOV Payment Applications where line order is maintained inside the SOV Workbook.
ResetItemStatusTo
Specifies (in the result value) the ItemStatus code (as defined in the Code Maintenance tool) to be assigned to copied Items. The default is O for open. Note: This rule does not apply to Items copied through the AutoCopyWhen rule (see above).
RowInfo
[V23] Specifies (in the result value) the text to display as an item tip (under the item grid). By default, this is enabled only for Commitments and Commitment Change Orders using the example below. You can include placeholders in [] using the fields from DocItem and DocItemTask (see schema). The only additional placeholder is [EstimateToComplete], which is replace by the amount remaining on the budget line. To disable this rule, enter 0 as the result value.
- Example/Default: Based upon estimate to complete for WBS [ProjEntity] : [AccountCategory] [EstimateToComplete] may be available
ShowExpandItem
Specifies (in the result value checkbox) whether the “expand Item” icon should be visible to users. If this rule is turned off, the icon will not appear regardless of user permissions.
- unchecked = No.
- checked = Yes (default).
SingleDocOnly
Specifies (in the result value checkbox) whether registration Items should be excluded from the Get Item lookup (Get Existing option) if the Item is already on another document of the same Doc type as the current target document.
- unchecked = No (default).
- checked = Yes.
Sparse
Specifies (in the result value checkbox) whether empty Item Task records should be discarded.
- unchecked = No, preserve Item Task records even when they do currently store any significant data.
- checked = Yes (default).
UseRegisterDoc
Specifies (in the result value checkbox) whether Items should be automatically added to a parent document. To be effective, this rule requires the filter Doc type to have a parent Doc type.
- unchecked = No (default).
- checked = Yes.
Additional Comments:
KBA-01158; Last updated: March 26, 2024 at 8:25 am; green text = new
Keywords: copy item, move item, rules, item pdf merge, How do I configure characteristics of document Items?
How do I control the default settings of the Get Existing Item dialog?