KBA-01294: Defining Masks for Project IDs and Cost Codes

Question:

How do I control the way that Project IDs and Cost Code are divided into parts?

Answer:

You set up your mask for Project IDs and Cost Codes on the System Admin Dashboard using the Mask Maintenance tool.  Sites that are integrated with an accounting system should review the additional comments at the end of this article. The mask definition effectively divides the 16-character Project ID and 32-character Cost Code into pieces, called segments.  Up to six segments can be defined, and the length of the segments can be set independently, as long as the sum of the lengths is less than or equal to the total available.

When displaying a masked ID, Spitfire generally adds a separator character (the default is a dash (-)), so that a project ID may display as GC-07-028 instead of GC07028.  In this example, the three segments represent a project type (GC), year (07) and sequence number (028).  The separator character does not count against the total length.

When defining a segment, you specify:

• Segment Length
• Segment Name – be sure not to use the same name for more than one segment
• Segment Mask Type
  • Numeric – for a segment that must be entered as a number; Spitfire will suggest an auto-incrementing value for the last numeric segment.  By default, this auto-incrementing value will be specific based upon all the proceeding data.  See the Lookup field below.
  • Uppercase Alpha
  • Uppercase Alphanumeric (optionally uses comma separated values to create a drop down)
  • Validated Text (uses Lookup and Values)
  • Year (Auto Fill) Supports length of 2,3 or 4
    • for document numbers:  Auto fills if Value is left empty.
    • for project numbers: specify seed in Value.  Updated each morning to current year.  Can be overridden.
• Lookup – Required for the Validated Text mask type and optional for the Numeric mask type.
  • Required for the Validated Text mask type:
    • All sites can use ‘CSICode’ for the lookup if the mask segment is based upon CSI Code, or use ‘CSICodeLike’ for the lookup if the mask segment is based upon CSI Code and upon prior segments (16 -> electrical choices).
    • All sites can use ‘CodeLookup‘ for the lookup and the name of a Spitfire Code Set (CodeList type) in Values
    • Sites integrated with Microsoft Dynamics SL can use ‘PJCODE‘ for the lookup and the name of the DSL code in Values
    • (Advanced) Custom lookups can be used by providing the xsfLookup lookup name and a value for @PD1 in the Values field
  • Optional for Numeric mask type:  Default is to base the counter on the entire prefix.
    • Use 0 to base the counter globally.
    • Use -1 to disable the counter feature
    • For projects only:
      • Specify a number of characters of the prefix to use; If you specify a number greater than the number of prefix characters, the entire prefix is used.
      • To use a prefix that skips some of the leftmost characters, add a semicolon and the number of characters to skip.  For example, given GCH… a lookup of 2;1 would base the counter on CH.
• Values
  • For Uppercase Alphanumeric fields, you can
    • specify a string (without any commas) for the default;
    • enter a set of choices separated by commas in this field. These choices are presented as a drop down list.  You should not include spaces in this string of choices.
  • For a numeric, you can specify a number to use as the default (or leave blank)
  • For Lookups
    • specify a value for the lookup, usually the code set name for CodeLookup or PJCODE
    • [v2021] Use % to indicate the entire prefix should be passed (% is not valid in the first segment)

Additional Comments:

Sites integrated with Microsoft Dynamics SL must be aware of the following limitations on the use of the code masking:

• The Project, Task and Commitment must match the corresponding Microsoft Dynamics SL Flex Key. The number of segments, individual segment size and total length must be identical.
• Generally, the flex keys are created in Microsoft Dynamics SL and imported into sfPMS.
• You can tailor the lookup and validation applied to a segment by Spitfire.  For example, Microsoft Dynamics SL will use PJCode for the CSI segment in the Task Mask, sfPMS should use CSICode.
• When sfPMS encounters the final numeric segment, it synchronizes with the counter setup for the flex key in Microsoft Dynamics SL.

See also KBA-01277 for using masks to control entry of document numbers.

Information about the Mask Maintenance tool can be found in the Focus on System Administration guide.

KBA-01294; Last updated: February 14, 2023 at 14:05 pm;
Keywords:  flex key;mask;task;parts