OrganizationsModule

The OrganizationsModule is a NestJS module that provides functionality for managing organizations in a web application. It contain services, models, and other supporting files needed to handle CRUD operations for organizations.

Entity Inheritance

NestKit provide base classes that can be inherited and customized with your needs. For entities we use TypeORM TableInheritance.

Key Components

The module provides a set of reusable components that can be easily integrated into a NestJS project:

Organization Entity

The Organization entity is a data model that represents organizations in a NestJS application. It typically includes fields such as a unique identifier (id), an organization display name (title), a logo (logo), and other attributes.

NestJS Organizations Service

A OrganizationsService provides programmatic access to the Organizations API. It typically includes methods for creating, retrieving, updating, and deleting organization entities.

GraphQL Organizations Resolver

The NestJS OrganizationsResolver is a component that handles incoming requests related to organizations and retrieves the relevant data using the OrganizationsService. It defines the GraphQL queries, mutations, and subscriptions for fetching and manipulating organizations data.

How to install OrganizationsModule to my app

To create a OrganizationsModule in NestJS, you can follow these steps:

1. Install the required dependencies for OrganizationsModule:

   • Id Module
   • Winston Module
   • Images Module
   • Organization Groups Module
   • UserToRoles Module
   • Timezones Module

2. Create a organizations folder in your project's src/modules directory.

3. Inside the organizations folder, create a organization.entity.ts file and extends BaseOrganization from NestKit with the following code:

   // src/modules/organizations/organization.entity.ts
   
   import { MaybeNull } from '@deeepvision/nest-kit';
   import { BaseOrganization } from '@deeepvision/nest-kit/dist/modules/organizations';
   import { Field, ObjectType } from '@nestjs/graphql';
   import { ChildEntity, OneToMany } from 'typeorm';
   import { UserToRole } from '../user-to-roles/user-to-role.entity';
   import { Image } from '../images/image.entity';
   import { OrganizationGroup } from '../organization-groups/organization-group.entity';
   import { Role } from '../roles/role.entity';
   import { User } from '../users/user.entity';
   
   @ObjectType()
   @ChildEntity()
   export class Organization extends BaseOrganization {
     @Field(() => User, {
       nullable: true,
     })
     creator!: Promise<MaybeNull<User>>;
   
     @Field(() => OrganizationGroup, {
       nullable: true,
     })
     group!: Promise<OrganizationGroup>;
   
     @Field(() => Image, {
       nullable: true,
       description: 'The organization logo',
     })
     logo!: Promise<MaybeNull<Image>>;
   
     userToRoles!: Promise<UserToRole[]>;
   
     roles!: Promise<Role[]>;
   }

4. Inside the organizations folder, create a organizations.service.ts file and extends BaseOrganizationsService from NestKit with the following code:

   // src/modules/organizations/organizations.service.ts
   import { BaseOrganizationsService } from '@deeepvision/nest-kit/dist/modules/organizations';
   import { Organization } from './organization.entity';
   
   export class OrganizationsService extends BaseOrganizationsService<Organization> {}

5. Inside the organizations folder, create a organizations.resolver.ts file and extends BaseOrganizationsResolver with the following code:

   // src/modules/organizations/organizations.resolver.ts
   
   import { BaseOrganizationsResolver } from '@deeepvision/nest-kit/dist/modules/organizations';
   import { Resolver } from '@nestjs/graphql';
   import { Organization } from './organization.entity';
   
   @Resolver(() => Organization)
   export class OrganizationsResolver extends BaseOrganizationsResolver(Organization) {}

6. Inside the organizations folder, create a organizations.module.ts file with the following code:

   // src/modules/organizations/organizations.module.ts
   
   import { ORGANIZATIONS_SERVICE_TOKEN } from '@deeepvision/nest-kit/dist/modules/organizations';
   import { Module } from '@nestjs/common';
   import { TypeOrmModule } from '@nestjs/typeorm';
   import { ImagesModule } from '../images/images.module';
   import { TimezonesModule } from '../timezones/timezones.module';
   import { UserToRole } from '../user-to-roles/user-to-role.entity';
   
   import { Organization } from './organization.entity';
   import { OrganizationsResolver } from './organizations.resolver';
   import { OrganizationsService } from './organizations.service';
   
   @Module({
     imports: [
       TypeOrmModule.forFeature([Organization, Organization, UserToRole]),
       ImagesModule,
       TimezonesModule,
     ],
     providers: [
       OrganizationsService,
       {
         provide: ORGANIZATIONS_SERVICE_TOKEN,
         useExisting: OrganizationsService,
       },
       OrganizationsResolver,
     ],
     exports: [
       OrganizationsService,
       {
         provide: ORGANIZATIONS_SERVICE_TOKEN,
         useExisting: OrganizationsService,
       },
       TypeOrmModule,
     ],
   })
   export class OrganizationsModule {}

7. Finally, import the OrganizationsModule into your main AppModule or another module:

   // src/modules/app.module.ts
   
   import { Module } from '@nestjs/common';
   import { OrganizationsModule } from './modules/organizations/organizations.module.ts';
   
   @Module({
     imports: [OrganizationsModule],
   })
   export class AppModule {}

   In this code, we are importing the OrganizationsModule and adding it to the imports array of our AppModule.

   Overall, creating a OrganizationsModule in NestJS is a simple process that involves extending an entity, resolver and service class and then importing the module into your main AppModule.

How to create new organization

Call the create of OrganizationsService and pass in an object of CreateOrganizationOptions:

const organization = await this.organizationsService.create({
    title: 'Acme Corp',
    code: 'ACME',
    timezoneName: 'America/New_York',
    groupId: 'hcgrp:corps', // optional
    logoId: 'https://example.com/logo.png', // optional
    uploadRegion: UploadRegion.US,
    embedRegion: EmbedRegion.US,
    modules: ['core'],
    addresses: [
      {
        street: '123 Main St',
        city: 'Anytown',
        state: 'NY',
        zip: '12345',
        country: 'US',
      },
    ],
    phoneNumbers: ['555-123-4567', '555-987-6543'],
    emails: ['[email protected]'],
    websites: ['https://www.acmecorp.com'],
    leaders: [
      {
        name: 'John Doe',
        title: 'CEO',
      },
    ],
    otherContacts: 'Jane Smith',
  });

The create method returns a Promise that resolves to the newly created organization object.

Create new organization with GraphQL

Here's an example GraphQL mutation to create a new organization.

How to get organization by ID

Use the getOne() method from your OrganizationsService to get a organization by id in other parts of your application.

const organization = await this.organizationsService.getOne('hcorg:xxxxxxxxxxx');

Use the getOneOrFail() method to retrieve a organization by id or throw an error if the organization is not found.

const organization = await this.organizationsService.getOneOrFail('hcorg:xxxxxxxxxxx', ctx);

Fetch organization by id with GraphQL

Here's an example GraphQL query to fetch organization by id.

How to get organization by code

Use the getOneByCode() method in other parts of your application to retrieve a organization by their unique code.

const organization = await this.organizationsService.getOneByCode('ACME');

Use the getOneByCodeOrFail() method to retrieve a organization by their code or throw an error if the organization is not found.

const organization = await this.organizationsService.getOneByCodeOrFail('ACME', ctx);

Fetch organization by code with GraphQL

Here's an example GraphQL query to fetch organization by unique code.

How to get organizations list

Use the getMany() method in other parts of your application to retrieve a list of organizations.

const [organizations, meta] = await this.organizationsService.getMany({
  filter: {
    ...
  },
  orderBy: OrganizationsOrderBy.title_ASC,
});

See OrganizationsFilter and OrganizationsOrderBy for more information on how to filter and order organizations.

Fetch organization list with GraphQL

Here's an example GraphQL query to fetch organizations.

How to update organization

Call the update method of the OrganizationsService and pass in an object of UpdateOrganizationOptions:

const updatedOrg = await this.organizationsService.update({
    id: 'hcorg:jg9204j67fdn',
    code: 'ACME',
    modules: ['core', 'mam'],
    addresses: [
      {
        street: '123 Main St',
        city: 'Anytown',
        state: 'NY',
        zip: '12345',
        country: 'US',
      },
    ],
    phoneNumbers: ['555-123-4567', '555-987-6543'],
    emails: ['[email protected]'],
    websites: ['https://www.acmecorp.com'], 
    leaders: [
      {
        name: 'John Doe',
        title: 'CEO',
      },
    ],
    otherContacts: 'Jane Smith',
  });

All fields in the upate input are optional except for the id field.

The update method returns a Promise that resolves to the updated organization object.

Update organization with GraphQL

Here's an example GraphQL mutation to update organization.

How to delete organization

Call the delete method of the OrganizationsService and pass in the id of the organization you want to delete:

await this.organizationsService.delete('hcorg:xxxxxxxxxxx');

In this example, we are deleting an organization with an id of hcorg:xxxxxxxxxxx.

Delete organization with GraphQL

Here's an example GraphQL mutation to delete organization.

OrganizationsService uses Soft-Delete feature

Soft delete is a feature in NestKit that allows you to mark a record as "deleted" instead of physically deleting it from the database. When you use soft delete, the record is not actually removed from the database, but a status sets to DELETED to indicate that the record has been "soft-deleted". This allows you to retain the data and history associated with the record, while still hiding it from normal queries.