MS Startup ‐ Pre‐Fill Database with Seed File - PROCEED-Labs/proceed GitHub Wiki

This page describes the database seed file used by the Management System (MS) at startup to pre-populate the database with initial users and organizations.

The seed file is located at the following path within the MS source code: src/management-system-v2/seed-db-with-spaces.config.ts

Structure

The seed file is a TypeScript file exporting a constant object named seedDbConfig, which has the DBSeed type. This object contains two arrays:

users: An array of objects, each defining a user.
organizations: An array of objects, each defining an organization, including its members, administrators, and roles.

Relationships between users and organizations (like ownership, membership, and roles) are established by referencing usernames defined in the users array within the organizations array.

Each user and organization must have an UUID, this is used to identify them in the database and to avoid conflicts if the seed file is used multiple times.

Example

Here is an example of the seedDbConfig structure:

import { DBSeed } from './lib/db-seed';

export const seedDbConfig: DBSeed = {
  users: [
    {
      id: 'f74f98eb-241c-438f-a49c-d56f0882600b',
      firstName: 'John',
      lastName: 'Doe',
      username: 'john_the_doe',
      email: '[email protected]',
      initialPassword: '#JohnDoe123',
    },
    {
      id: 'c6121e46-f948-4ce1-ab1e-60a7e401ce32',
      firstName: 'Jane',
      lastName: 'Doe',
      username: 'jane_the_doe',
      email: '[email protected]',
      initialPassword: '#JaneDoe123',
    },
  ],
  organizations: [
    {
      id: 'd2f16af1-8646-41ca-b923-eb24af24c9fc',
      name: "John Doe's Organization",
      description: "This is John Doe's organization",
      owner: 'john_the_doe', // This username has to match one defined in the users array
      members: [
        // These usernames have to match one defined in the users array
        'john_the_doe',
        'jane_the_doe',
      ],
      admins: [
        'john_the_doe', // This username has to match one defined in the users array
      ],
      contactPhoneNumber: '+49 123456789',
      contactEmail: '[email protected]',
      roles: [
        {
          name: 'Project Manager',
          members: ['jane_the_doe'],
          permissions: {
            Setting: ['view', 'update'],
            Folder: ['view', 'update'],
            Process: ['view', 'update'],
          },
        },
      ],
    },
  ],
};

Update strategy

Changes are written to the database only if the seed version is newer (i.e., has a later date) than the current version in the database, or if the database is empty.

However, the changes made to the database only create new users, organizations, or roles, they do not update existing ones. This means that if a user or organization already exists in the database, it will not be modified by changes made to the seed file. The MS determines whether a user, organization, or role already exists by checking the UUIDs defined in the seed file.

Here is a list of changes that are applied when the seed file is updated:

creating new users, organizations
adding new members to an organization
adding admins to an organization
adding roles to an organization
adding new members to a role

Seed Structure

DBSeed

The DBSeed type defines the expected structure of the seed configuration object. Below is a detailed breakdown of the types involved, presented using Markdown tables.

Property	Type	Description	Required
version	`string`	Date string in ISO format.	Yes
users	`UserSeed[]`	An array of user definitions.	Yes
organizations	`OrganizationSeed[]`	An array of organization definitions.	Yes

`UserSeed'

Defines the properties for creating a user.

Property	Type	Description	Required
id	`string`	A unique identifier (UUID) for the user.	Yes
firstName	`string`	The user's first name.	Yes
lastName	`string`	The user's last name.	Yes
username	`string`	A unique username for the user. Used for references.	Yes
initialPassword	`string`	The initial password for the user.	Yes
phoneNumber	`string`	The user's phone number.	Yes
email	`string`	The user's email address.	Yes

`OrganizationSeed`

Property	Type	Description	Required
id	`string`	A unique identifier (UUID) for the organization.	Yes
name	`string`	The name of the organization.	Yes
description	`string`	A description of the organization.	Yes
contactPhoneNumber	`string`	A contact phone number (only german phone numbers are allowed.
contactEmail	`string`	A contact E-Mail address.
spaceLogo	`string`	The path to an image in the public folder (Needs to start with "public/").
owner	`string`	The username of owner of the organization.	Yes
members	`string[]`	List of usernames that will be part of the organization	Yes
admins	`string[]`	List of usernames that will be administrators of the organization.	Yes
roles	`Role[]`

`Role`

Property	Type	Description	Required
id	`string`	A unique identifier (UUID) for the role.	Yes
name	`string`	Name of the role.	Yes
description	`string`	Description for the role.
note	`string`	Note for the role, this is displayed to users who can edit the role. The note cannot be changed after it has been set.
expiration	`string`	Iso string of the date on which the role expires. After this date the role's permissions will be removed, however, the role will not be deleted.
members	`string[]`	A list of usernames that will be part of this role.	Yes
permissions	`Permissions`	Permissions for the role.	Yes

`Permissions`

Property	Type	Description
Process	`Action[]`	Permissions for Process resources.
Project	`Action[]`	Permissions for Project resources.
Template	`Action[]`	Permissions for Template resources.
Task	`Action[]`	Permissions for Task resources.
Machine	`Action[]`	Permissions for Machine resources.
Execution	`Action[]`	Permissions for Execution resources.
Role	`Action[]`	Permissions for managing Roles within the organization.
User	`Action[]`	Permissions for managing Users within the organization.
Setting	`Action[]`	Permissions for organization settings.

`Action`

Action is an enum with the following values:

Value	Description
'none'	No permissions.
'view'	Allows a user to view the resource.
'update'	Allows a user to update the resource.
'create'	Allows a user to create instances of the resource.
'delete'	Allows a user to delete resource instances.
'manage'	Combination of 'update', 'create', and 'delete' permissions.
'admin'	Allows any action on the resource.