Creating a New Group — Form Groups

Step 1 — SQL INSERT Into Atlas_FormCategories

Choose the next available FormCategoryID (consult the reserved ranges table on the Current Form Groups page) and add the category row:

-- File: BizFirstFiV3DB/dbo/Data/AtlasForms/WorkDesk/WorkDesk_Category.data.sql

IF NOT EXISTS (
    SELECT 1 FROM [dbo].[Atlas_FormCategories]
    WHERE [FormCategoryID] = 150
)
BEGIN
    INSERT INTO [dbo].[Atlas_FormCategories]
        ([FormCategoryID], [CategoryName], [OwnerApp],
         [FormIdRangeStart], [FormIdRangeEnd],
         [AiGenerationEnabled], [TenantOverrideable])
    VALUES
        (150, 'WorkDesk', 'BizFirst.Ai.WorkDesk',
         15000, 15099,
         1, 1);
END

Step 2 — TypeScript Group Definition

// src/formGroups/workDeskGroup.ts
import type { FormGroupDefinition } from '@atlas-forms/types-js';

export const workDeskGroup: FormGroupDefinition = {
  formGroupId:         'work-desk',
  label:               'WorkDesk',
  ownerApp:            'BizFirst.Ai.WorkDesk',
  categoryId:          150,
  formIdRange: {
    start: 15000,
    end:   15099,
  },
  aiGenerationEnabled: true,
  tenantOverrideable:  true,
  defaultPrimaryUsage: 'workdesk',
};

// src/index.tsx or src/bootstrap.ts
import { registerFormGroup } from '@atlas-forms/form-group-registry';
import { workDeskGroup }     from './formGroups/workDeskGroup';

registerFormGroup(workDeskGroup);

Step 3 — Create the List Form

Every group must have a list form as its first form. The list form's FormID is always rangeStart + 0:

-- File: BizFirstFiV3DB/dbo/Data/AtlasForms/WorkDesk/Atlas_Forms_15000_WorkDesk_List.data.sql

IF NOT EXISTS (SELECT 1 FROM [dbo].[Atlas_Forms] WHERE [FormID] = 15000)
BEGIN
    INSERT INTO [dbo].[Atlas_Forms]
        ([FormID], [FormCode], [FormCategoryID], [FormTypeID],
         [PrimaryUsage], [NodeUsage], [TenantID], [IsActive], [SchemaJson])
    VALUES
        (15000, 'WorkDesk_List', 150, 1,
         'workdesk', NULL, NULL, 1,
         N'{ "metadata": { "formId": 15000, "title": "WorkDesk Tasks" },
             "controls": [ { "id": "task-grid", "type": "data-grid", "order": 1 } ] }');
END

Step 4 — Create Property Forms

Add detail forms for individual items. FormIDs continue sequentially from rangeStart + 1:

-- File: BizFirstFiV3DB/dbo/Data/AtlasForms/WorkDesk/Atlas_Forms_15001_WorkDesk_Task_Edit.data.sql

IF NOT EXISTS (SELECT 1 FROM [dbo].[Atlas_Forms] WHERE [FormID] = 15001)
BEGIN
    INSERT INTO [dbo].[Atlas_Forms]
        ([FormID], [FormCode], [FormCategoryID], [FormTypeID],
         [PrimaryUsage], [NodeUsage], [TenantID], [IsActive], [SchemaJson])
    VALUES
        (15001, 'WorkDesk_Task_Edit', 150, 2,
         'workdesk', 'workdesk-task-edit', NULL, 1,
         N'{ "metadata": { "formId": 15001, "title": "Edit Task" }, "controls": [ ... ] }');
END

Step 5 — Create the Deploy Script

Create a master deploy script that runs all the individual data files in order. This script is used by the migration pipeline:

-- File: BizFirstFiV3DB/dbo/Data/AtlasForms/WorkDesk/Deploy_WorkDesk_Forms.sql
-- Run all WorkDesk form data scripts in FormID order

:r .\WorkDesk_Category.data.sql
:r .\Atlas_Forms_15000_WorkDesk_List.data.sql
:r .\Atlas_Forms_15001_WorkDesk_Task_Edit.data.sql
:r .\Atlas_Forms_15002_WorkDesk_Task_View.data.sql

Checklist

Step	File or Action	Done?
1	INSERT into `Atlas_FormCategories` with IF NOT EXISTS guard
2	TypeScript `FormGroupDefinition` created and registered at startup
3	List form (`rangeStart + 0`) created with `FormTypeID = 1`
4	Property forms created for each distinct item type
5	Deploy script created running all files in order
—	Naming conventions verified (see next page)
—	Reserved range updated in Current Form Groups documentation

Always Use IF NOT EXISTS Guards Every INSERT into Atlas_Forms and Atlas_FormCategories must be wrapped in an IF NOT EXISTS guard keyed on the primary key. The deploy scripts are run idempotently on every environment refresh — an unguarded INSERT would fail on the second run.

← App Association Next: Naming Conventions →