BrandAssignmetnsModule

BrandAssignments API is a versatile service that enables the assignment of specific roles to brands, facilitating granular access control and management of brand-related permissions, much like the UserToRoles functionality.

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:

BrandAssignment Entity

The BrandAssignment entity, is a data model that manages the relationship between users, roles, and brands. It contains information about the user, role, and brand involved in the assignment, as well as the status, grantor, grant date, expiration date, and timestamps for creation and updates. This entity allows the system to handle role assignments for users within specific brands, ensuring proper access control and organization management.

BrandAssignments Service

The BrandAssignmentsService is responsible for managing the assignment of roles to users within the application. It provides methods to create, update, and remove role assignments, as well as to fetch role assignments for a specific user or organization.

BrandAssignments Resolver

The BrandAssignmentsResolver handles the process of mapping and resolving GraphQL queries and mutations related to BrandAssignments. It defines how the API interacts with the underlying data, allowing clients to request or modify BrandAssignment information, such as user-role relationships within a brand.

How to install BrandAssignmentsModule to my app

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

1. Install the required dependencies for BrandAssignmentsModule:

   • Id Module
   • Winston Module
   • Users Module
   • Roles Module
   • Brands Module

2. Create a brand-assignments folder in your project's src/modules directory.

3. Inside the brand-assignments folder, create a brand assignment.entity.ts file and extends BaseBrandAssignment from NestKit with the following code:

   // src/modules/brand-assignments/brand assignment.entity.ts
   
   import { Field, ObjectType } from '@nestjs/graphql';
   import { ChildEntity } from 'typeorm';
   import { Brand } from '../brands/brand.entity';
   import { Role } from '../roles/role.entity';
   import { User } from '../users/user.entity';
   import { BaseBrandAssignment } from '@deeepvision/nest-kit/dist/modules/brand-assignments';
   import { MaybeNull } from '@deeepvision/nest-kit';
   
   @ObjectType()
   @ChildEntity()
   export class BrandAssignment extends BaseBrandAssignment {
     @Field(() => User)
     user!: Promise<User>;
   
     @Field(() => Role)
     role!: Promise<Role>;
   
     @Field(() => Brand)
     brand!: Promise<Brand>;
   
     @Field(() => User)
     grantedBy!: Promise<MaybeNull<User>>;
   }

4. Inside the brand-assignments folder, create a brand-assignments.service.ts file and extends BaseBrandAssignmentsService from NestKit with the following code:

   // src/modules/brand-assignments/brand-assignments.service.ts
   
   import { BaseBrandAssignmentsService } from '@deeepvision/nest-kit/dist/modules/brand-assignments';
   import { InjectRepository } from '@nestjs/typeorm';
   import { Repository } from 'typeorm';
   import { Brand } from '../brands/brand.entity';
   import { Role } from '../roles/role.entity';
   import { User } from '../users/user.entity';
   import { BrandAssignment } from './brand assignment.entity';
   
   export class BrandAssignmentsService extends BaseBrandAssignmentsService<BrandAssignment, User, Role, Brand> {
     constructor(
       @InjectRepository(BrandAssignment) protected readonly brandAssignmentRepository: Repository<BrandAssignment>,
       @InjectRepository(User) protected readonly userRepository: Repository<User>,
       @InjectRepository(Role) protected readonly roleRepository: Repository<Role>,
       @InjectRepository(Brand) protected readonly brandRepository: Repository<Brand>,
     ) {
       super(
         brandAssignmentRepository,
         userRepository,
         roleRepository,
         brandRepository,
       );
     }
   
     // protected generateEntityId() {
     //   return this.idService.generateEntityId('bass', 'hc');
     // }
   }

5. Inside the brand-assignments folder, create a brand-assignments.resolver.ts file and extends BaseBrandAssignmentsResolver with the following code:

   // src/modules/brand-assignments/brand-assignments.resolver.ts
   
   import { BaseBrandAssignmentsResolver } from '@deeepvision/nest-kit/dist/modules/brand-assignments';
   import { Resolver } from '@nestjs/graphql';
   import { Brand } from '../brands/brand.entity';
   import { Role } from '../roles/role.entity';
   import { User } from '../users/user.entity';
   import { BrandAssignment } from './brand assignment.entity';
   import { BrandAssignmentsService } from './brand-assignments.service';
   
   @Resolver(() => BrandAssignment)
   export class BrandAssignmentsResolver extends BaseBrandAssignmentsResolver<BrandAssignment, User, Role, Brand>(BrandAssignment) {
     constructor(
       protected readonly brandsService: BrandAssignmentsService,
     ) {
       super(brandsService);
     }
   }

6. Inside the brand-assignments folder, create a brand-assignments.module.ts file with the following code:

   // src/modules/brand-assignments/brand-assignments.module.ts
   
   import { Module } from '@nestjs/common';
   import { TypeOrmModule } from '@nestjs/typeorm';
   import { Brand } from '../brands/brand.entity';
   import { Role } from '../roles/role.entity';
   import { User } from '../users/user.entity';
   import { BrandAssignment } from './brand-assignment.entity';
   import { BrandAssignmentsResolver } from './brand-assignments.resolver';
   import { BrandAssignmentsService } from './brand-assignments.service';
   import { BRAND_ASSIGNMENTS_SERVICE_TOKEN } from '@deeepvision/nest-kit/dist/modules/brand-assignments';
   
   @Module({
     imports: [
       TypeOrmModule.forFeature([
         BrandAssignment,
         User,
         Role,
         Brand,
       ]),
     ],
     providers: [
       BrandAssignmentsService,
       {
         provide: BRAND_ASSIGNMENTS_SERVICE_TOKEN,
         useExisting: BrandAssignmentsService,
       },
       BrandAssignmentsResolver,
     ],
     exports: [
       BrandAssignmentsService,
       {
         provide: BRAND_ASSIGNMENTS_SERVICE_TOKEN,
         useExisting: BrandAssignmentsService,
       },
     ],
   })
   export class BrandAssignmentsModule {}

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

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

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

How to assign a role to a user in brand

Here's an example of how to call BrandAssignmentsService.create with an object literal based on CreateBrandAssignmentOptions:

const brandAssignment = await this.brandAssignmentsService.create({
  userId: 'hcu:2jg8592oknjw',
  roleId: 'hcrol:producer',
  brandId: 'hcb:k39294ihlnb',
  grantedById: 'hcu:91485bgmvdk',
  expireAt: new Date('2023-12-31T23:59:59Z'),
});

In this example, the create method of the BrandAssignmentsService is called with an object containing the necessary data to assign a role to a user in brand. The role with ID hcrol:producer will be assigned to the user with ID hcu:2jg8592oknjw, within the brand with ID hcb:k39294ihlnb. The user with ID hcu:2jg8592oknjw has granted the role, and the role assignment will expire at the end of December 31, 2023.

Create new brand assignment with GraphQL

Here's an example GraphQL mutation to create a brand assignment.

How to get brand assignment by ID

Use the getOne() method from your BrandAssignmentsService to get a brand assignment by id in other parts of your application.

const brandAssignment = await this.brandAssignmentsService.getOne('hcbass:xxxxxxxxxxx');

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

const brandAssignment = await this.brandAssignmentsService.getOneOrFail('hcbass:xxxxxxxxxxx', ctx);

const role = await brandAssignment.role;
const user = await brandAssignment.user;
const brand = await brandAssignment.brand;

console.log(`User "${user.fullName}" was assigned to "${role.title}" role in "${brand.id}" brand.`)

How to get user brand assignments list

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

const [brandAssignments, meta] = await this.brandAssignmentsService.getMany({
  filter: {
    ...
  },
  orderBy: BrandAssignmentsOrderBy.createdAt_ASC,
});

See BrandAssignmentsFilter and BrandAssignmentsOrderBy for more information on how to filter and order user roles.

Fetch brand assignments list with GraphQL

Here's an example GraphQL query to fetch brand assignments.

How to create a brand assignment request

If a user wants to gain special access to a brand, they can create a brand assignment request. This action will create a BrandAssignment with a pending status in the system. If an admin approves the request, the brand assignment status will change to ACTIVE, and the user will gain additional permissions for the brand. If the admin rejects the request, the brand assignment status will be set to REJECTED.

Here's an example GraphQL mutation to create a request for obtaining a brand role.

How to delete brand assignment

Call the delete method of the BrandAssignmentsService and pass in the id of the role you want to delete:

await this.brandAssignmentsService.delete('hcbass:xxxxxxxxxxx');

In this example, we are deleting a brand assignment with an id of hcbass:xxxxxxxxxxx.

Delete brand assignments with GraphQL

Here's an example GraphQL mutation to delete brand assignment.