KBA-01410: How to Add a Custom Entry on the Spitfire Site Menu


How can I add my Custom DocType to the Site Menu?


The xsfDashboard table in the Spitfire database holds the entries for the dashboard menus.

INSERT  [dbo].[xsfDashboardMenu]
([MenuItemKey]      ,[DocTypeKey]          ,[ContainerKey]
,[MenuPath]         ,[MenuItemID]          ,[MenuSeq]
,[ItemText]       ,[TipText]           ,[ActionText]
,[UCModule]         ,[UCFunction]          ,[RequiredPermit]
,[Active]          ,[SiteActive])
VALUES (    MenuItemKey             — uniqueidentifier
,DocTypeKey              — uniqueidentifier
,ContainerKey            — uniqueidentifier
,MenuPath                — varchar(64)
,MenuItemID              — int
,MenuSeq                 — int
,ItemText                — varchar(64)
,TipText                 — varchar(64)
,ActionText              — varchar(128)
,UCModule                — char(4)
,UCFunction              — varchar(50)
,RequiredPermit          — int
,Active                  — bit
,SiteActive              — bit

  • MenuItemKey is a GUID, probably NEWID().
  • DocTypeKey is the relevant Doc type GUID.  This enables support for user-based permission sensitivity and site name substitution.
  • ContainerKey is unused at this time, leave NULL.
  • MenuPath is generally a backslash (\) or Help|
  • MenuItemID is a unique number, equivalent to the old xsfMaintAK field.  Important: custom entries should use ODD numbers!
  • MenuSeq is a controls sequence in the File | New menu and a specific entry in the Help menu.
  • ItemText is text for menu.  Note that $$DTSN is replaced by the Doc type site name.
  • TipText is optional additional descriptive text.
  • ActionText is the command that gets run. (See samples below; $$DTK gets replaced by the Doc type GUID.)
  • UCModule is the xsfUCFunction module for permission-sensitive entries.
  • UCFunction is the xsfUCFunction UCNAME for permission-sensitive entries.
  • RequiredPermit is a bit masked level on the above capability: 1=Read; 2=Ins; 4=Update; 8=Delete, 16=Special.
  • Active is standard usage (0 = inactive).
  • SiteActive is standard usage  (0 = inactive).

Samples from Current Distribution:

A Choice on the Create Document menu:

The system ships with the following document types ready for “create” from the Site Menu if the corresponding document type is Site Active

  • Bid
  • Charge Entry
  • Bid Package
  • Estimate
  • Task
  • Expense Entry
  • Invitation to Bid
  • File Batch

To add your own, using the example, you should change

  • Use your own NEWID() for [MenuItemKey] (not ‘AF2E1486-DBF0-40BD-B52E-0E816FD34571’)
  • The document type GUID (shown in color). Use the GUID for the doc type you want.
    • This document type must be site active
    • The current user must have create permission for the document type
  • Use a unique value for [MenuSeq], not 100
  • $$DTSN is replaced by the document site name, you can omit that placeholder and use any ItemText you prefer.

INSERT xsfDashboardMenu([MenuItemKey],[DocTypeKey],[ContainerKey]
,[TipText],[ActionText], [UCModule],[UCFunction]
,NULL,’\’,100,100, ‘Create $$DTSN’,NULL

— Note: no recycle is necessary

A separator:

INSERT xsfDashboardMenu([MenuItemKey],[DocTypeKey],[ContainerKey]
,[TipText],[ActionText], [UCModule],[UCFunction]

A custom URL:

INSERT xsfDashboardMenu([MenuItemKey],[DocTypeKey],[ContainerKey]
,[TipText],[ActionText], [UCModule],[UCFunction]
,999,29,’News Headlines’,NULL,’http://www.nytimes.com/’,’PAGE’,’Dashboard.aspx’,1,1,1)

Enable Help|Site SOP Guide:

INSERT xsfDashboardMenu([MenuItemKey],[DocTypeKey],[ContainerKey]
,[TipText],[ActionText], [UCModule],[UCFunction]
,1010,23,’Our SOP Guide’,NULL

  • MenuPath and MenuSeq must be as shown above (Help| and 23).
  • The GUID can be anything.
  • The item text can be anything appropriate.
  • The action text can be any URL, but must start either javascript:p or http: or https:
  • The permit can be altered to limit access to certain users (e.g., internal vs external).
  • If limited, it should also be possible to have multiple entries with HELP|23).  Be sure they are sequenced from least restrictive to most restrictive.  The ‘hot‘ action will then be the last entry in the sequence for which the user has permission.

Additional Help Menu ID numbers:

  • 22 — The Overview Guide.  An entry here overrides the Spitfire default.
  • 23 — Site SOP Guide.
  • 24 — Site Defined (Third Party).
  • 25 — Site Defined.
  • 26, 27, 28, 29 — Site Help menu only.

Additional Comments:

  • Choices on the New menu are sensitive to whether or not the Doc type is site active and use the site name in item text (replacing $$DTSN).
  • Choices on the New menu are sensitive to whether or not the currently logged-in user has (non project-specific) permission to create a document of the Doc type.
  • Consider moving Help Menu IDs 23-25 to the new custom site menu entries; see KBA-01543.

KBA-01410; Last updated: June 14, 2020 at 7:48 am;
Keywords:  help menu, file menu, custom Doc type, customizing Help menu, Create Document