docs: v2 workflows and disable on prefill booking fields (#22445)

* wip

* docs: booking fields prefilling

* docs: wofklows

* fix: guests docs

apps/api/v2/src/modules/organizations/teams/workflows/controllers/org-team-workflows.controller.ts

@@ -93,7 +93,7 @@ export class OrganizationTeamWorkflowsController {
 
   @Patch("/:workflowId")
   @UseGuards(IsWorkflowInTeam)
-  @ApiOperation({ summary: "Update workflow" })
+  @ApiOperation({ summary: "Update organization team workflow" })
   @Roles("TEAM_ADMIN")
   @PlatformPlan("SCALE")
   async updateWorkflow(

apps/api/v2/src/modules/workflows/inputs/create-workflow.input.ts

@@ -1,4 +1,4 @@
-import { ApiProperty, ApiPropertyOptional, getSchemaPath } from "@nestjs/swagger";
+import { ApiExtraModels, ApiProperty, ApiPropertyOptional, getSchemaPath } from "@nestjs/swagger";
 import { Type } from "class-transformer";
 import {
   IsBoolean,
@@ -74,6 +74,24 @@ export type TriggerDtoType =
   | OnCancelTriggerDto
   | OnAfterCalVideoGuestsNoShowTriggerDto
   | OnAfterCalVideoHostsNoShowTriggerDto;
+
+@ApiExtraModels(
+  OnBeforeEventTriggerDto,
+  OnAfterEventTriggerDto,
+  OnCancelTriggerDto,
+  OnCreationTriggerDto,
+  OnRescheduleTriggerDto,
+  OnAfterCalVideoGuestsNoShowTriggerDto,
+  OnAfterCalVideoHostsNoShowTriggerDto,
+  WorkflowEmailAddressStepDto,
+  WorkflowEmailAttendeeStepDto,
+  WorkflowEmailHostStepDto,
+  WorkflowPhoneWhatsAppAttendeeStepDto,
+  WorkflowPhoneWhatsAppNumberStepDto,
+  WorkflowPhoneNumberStepDto,
+  WorkflowPhoneAttendeeStepDto,
+  BaseWorkflowTriggerDto
+)
 export class CreateWorkflowDto {
   @ApiProperty({ description: "Name of the workflow", example: "Platform Test Workflow" })
   @IsString()
@@ -86,17 +104,15 @@ export class CreateWorkflowDto {
 
   @ApiProperty({
     description: "Trigger configuration for the workflow",
-    items: {
-      oneOf: [
-        { $ref: getSchemaPath(OnBeforeEventTriggerDto) },
-        { $ref: getSchemaPath(OnAfterEventTriggerDto) },
-        { $ref: getSchemaPath(OnCancelTriggerDto) },
-        { $ref: getSchemaPath(OnCreationTriggerDto) },
-        { $ref: getSchemaPath(OnRescheduleTriggerDto) },
-        { $ref: getSchemaPath(OnAfterCalVideoGuestsNoShowTriggerDto) },
-        { $ref: getSchemaPath(OnAfterCalVideoHostsNoShowTriggerDto) },
-      ],
-    },
+    oneOf: [
+      { $ref: getSchemaPath(OnBeforeEventTriggerDto) },
+      { $ref: getSchemaPath(OnAfterEventTriggerDto) },
+      { $ref: getSchemaPath(OnCancelTriggerDto) },
+      { $ref: getSchemaPath(OnCreationTriggerDto) },
+      { $ref: getSchemaPath(OnRescheduleTriggerDto) },
+      { $ref: getSchemaPath(OnAfterCalVideoGuestsNoShowTriggerDto) },
+      { $ref: getSchemaPath(OnAfterCalVideoHostsNoShowTriggerDto) },
+    ],
   })
   @ValidateNested()
   @Type(() => BaseWorkflowTriggerDto, {
@@ -124,17 +140,16 @@ export class CreateWorkflowDto {
 
   @ApiProperty({
     description: "Steps to execute as part of the workflow",
-    items: {
-      oneOf: [
-        { $ref: getSchemaPath(WorkflowEmailAddressStepDto) },
-        { $ref: getSchemaPath(WorkflowEmailAttendeeStepDto) },
-        { $ref: getSchemaPath(WorkflowEmailHostStepDto) },
-        { $ref: getSchemaPath(WorkflowPhoneWhatsAppAttendeeStepDto) },
-        { $ref: getSchemaPath(WorkflowPhoneWhatsAppNumberStepDto) },
-        { $ref: getSchemaPath(WorkflowPhoneNumberStepDto) },
-        { $ref: getSchemaPath(WorkflowPhoneAttendeeStepDto) },
-      ],
-    },
+    oneOf: [
+      { $ref: getSchemaPath(WorkflowEmailAddressStepDto) },
+      { $ref: getSchemaPath(WorkflowEmailAttendeeStepDto) },
+      { $ref: getSchemaPath(WorkflowEmailHostStepDto) },
+      { $ref: getSchemaPath(WorkflowPhoneWhatsAppAttendeeStepDto) },
+      { $ref: getSchemaPath(WorkflowPhoneWhatsAppNumberStepDto) },
+      { $ref: getSchemaPath(WorkflowPhoneNumberStepDto) },
+      { $ref: getSchemaPath(WorkflowPhoneAttendeeStepDto) },
+    ],
+    type: "array",
   })
   @ValidateNested({ each: true })
   @ArrayMinSize(1, { message: "Your workflow must contain at least one step." })

apps/api/v2/src/modules/workflows/inputs/update-workflow.input.ts

@@ -1,4 +1,4 @@
-import { ApiProperty, ApiPropertyOptional, getSchemaPath } from "@nestjs/swagger";
+import { ApiExtraModels, ApiProperty, ApiPropertyOptional, getSchemaPath } from "@nestjs/swagger";
 import { Type } from "class-transformer";
 import { IsNumber, IsString, IsOptional, ValidateNested, ArrayMinSize } from "class-validator";
 
@@ -113,6 +113,23 @@ export class UpdateWhatsAppAttendeePhoneWorkflowStepDto extends WorkflowPhoneWha
   id?: number;
 }
 
+@ApiExtraModels(
+  OnBeforeEventTriggerDto,
+  OnAfterEventTriggerDto,
+  OnCancelTriggerDto,
+  OnCreationTriggerDto,
+  OnRescheduleTriggerDto,
+  OnAfterCalVideoGuestsNoShowTriggerDto,
+  OnAfterCalVideoHostsNoShowTriggerDto,
+  UpdateEmailAddressWorkflowStepDto,
+  UpdateEmailAttendeeWorkflowStepDto,
+  UpdateEmailHostWorkflowStepDto,
+  UpdatePhoneAttendeeWorkflowStepDto,
+  UpdatePhoneWhatsAppNumberWorkflowStepDto,
+  UpdateWhatsAppAttendeePhoneWorkflowStepDto,
+  UpdatePhoneNumberWorkflowStepDto,
+  BaseWorkflowTriggerDto
+)
 export class UpdateWorkflowDto {
   @ApiPropertyOptional({ description: "Name of the workflow", example: "Platform Test Workflow" })
   @IsString()
@@ -128,6 +145,20 @@ export class UpdateWorkflowDto {
   @IsOptional()
   activation?: WorkflowActivationDto;
 
+  @ApiPropertyOptional({
+    description: "Trigger configuration for the workflow",
+    oneOf: [
+      { $ref: getSchemaPath(OnBeforeEventTriggerDto) },
+      { $ref: getSchemaPath(OnAfterEventTriggerDto) },
+      { $ref: getSchemaPath(OnCancelTriggerDto) },
+      { $ref: getSchemaPath(OnCreationTriggerDto) },
+      { $ref: getSchemaPath(OnRescheduleTriggerDto) },
+      { $ref: getSchemaPath(OnAfterCalVideoGuestsNoShowTriggerDto) },
+      { $ref: getSchemaPath(OnAfterCalVideoHostsNoShowTriggerDto) },
+    ],
+  })
+  @IsOptional()
+  @ValidateNested()
   @Type(() => BaseWorkflowTriggerDto, {
     discriminator: {
       property: "type",
@@ -142,7 +173,7 @@ export class UpdateWorkflowDto {
       ],
     },
   })
-  trigger!:
+  trigger?:
     | OnAfterEventTriggerDto
     | OnBeforeEventTriggerDto
     | OnCreationTriggerDto
@@ -150,19 +181,19 @@ export class UpdateWorkflowDto {
     | OnCancelTriggerDto
     | OnAfterCalVideoGuestsNoShowTriggerDto
     | OnAfterCalVideoHostsNoShowTriggerDto;
+
   @ApiPropertyOptional({
     description: "Steps to execute as part of the workflow",
-    items: {
-      oneOf: [
-        { $ref: getSchemaPath(UpdateEmailAddressWorkflowStepDto) },
-        { $ref: getSchemaPath(UpdateEmailAttendeeWorkflowStepDto) },
-        { $ref: getSchemaPath(UpdateEmailHostWorkflowStepDto) },
-        { $ref: getSchemaPath(UpdatePhoneAttendeeWorkflowStepDto) },
-        { $ref: getSchemaPath(UpdatePhoneWhatsAppNumberWorkflowStepDto) },
-        { $ref: getSchemaPath(UpdateWhatsAppAttendeePhoneWorkflowStepDto) },
-        { $ref: getSchemaPath(UpdatePhoneNumberWorkflowStepDto) },
-      ],
-    },
+    oneOf: [
+      { $ref: getSchemaPath(UpdateEmailAddressWorkflowStepDto) },
+      { $ref: getSchemaPath(UpdateEmailAttendeeWorkflowStepDto) },
+      { $ref: getSchemaPath(UpdateEmailHostWorkflowStepDto) },
+      { $ref: getSchemaPath(UpdatePhoneAttendeeWorkflowStepDto) },
+      { $ref: getSchemaPath(UpdatePhoneWhatsAppNumberWorkflowStepDto) },
+      { $ref: getSchemaPath(UpdateWhatsAppAttendeePhoneWorkflowStepDto) },
+      { $ref: getSchemaPath(UpdatePhoneNumberWorkflowStepDto) },
+    ],
+    type: "array",
   })
   @ValidateNested({ each: true })
   @ArrayMinSize(1, { message: "Your workflow must contain at least one step." })

packages/platform/types/event-types/event-types_2024_06_14/inputs/booking-fields.input.ts

@@ -50,7 +50,7 @@ export class NameDefaultFieldInput_2024_06_14 {
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
       For example, if URL contains query parameter `&name=bob`,\
-      the name field will be prefilled with this value and disabled.",
+      the name field will be prefilled with this value and disabled. In case of Booker atom need to pass 'name' to defaultFormValues prop with the desired value e.g. `defaultFormValues={{name: 'bob'}}`. See guide https://cal.com/docs/platform/guides/booking-fields",
   })
   disableOnPrefill?: boolean;
 }
@@ -96,7 +96,7 @@ export class SplitNameDefaultFieldInput_2024_06_14 {
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
       For example, if URL contains query parameter `&firstName=bob&lastName=jones`,\
-      the first name and last name fields will be prefilled with this value and disabled. In case of Booker atom need to pass firstName and lastName to defaultFormValues prop or pass name prop but as a string containing name and surname.",
+      the first name and last name fields will be prefilled with this value and disabled. In case of Booker atom need to pass 'firstName' and 'lastName' to defaultFormValues prop e.g. `defaultFormValues={{firstName: 'bob', lastName: 'doe'}}` or pass 'name' prop but as a string containing name and surname e.g. `defaultFormValues={{name: 'bob doe'}}`.  See guide https://cal.com/docs/platform/guides/booking-fields",
   })
   disableOnPrefill?: boolean;
 }
@@ -144,7 +144,7 @@ export class EmailDefaultFieldInput_2024_06_14 {
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
       For example, if URL contains query parameter `&email=bob@gmail.com`,\
-      the email field will be prefilled with this value and disabled.",
+      the email field will be prefilled with this value and disabled. In case of Booker atom need to pass 'email' to defaultFormValues prop with the desired value e.g. `defaultFormValues={{email: 'bob@gmail.com'}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 }
@@ -184,7 +184,7 @@ export class TitleDefaultFieldInput_2024_06_14 {
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
       For example, if URL contains query parameter `&title=journey`,\
-      the title field will be prefilled with this value and disabled.",
+      the title field will be prefilled with this value and disabled. In case of Booker atom need to pass 'title' to defaultFormValues prop with the desired value e.g. `defaultFormValues={{title: 'very important meeting'}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 }
@@ -239,7 +239,7 @@ export class NotesDefaultFieldInput_2024_06_14 {
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
       For example, if URL contains query parameter `&notes=journey`,\
-      the notes field will be prefilled with this value and disabled.",
+      the notes field will be prefilled with this value and disabled. In case of Booker atom need to pass 'notes' to defaultFormValues prop with the desired value e.g. `defaultFormValues={{notes: 'bring notebook and paper'}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 }
@@ -279,7 +279,7 @@ export class GuestsDefaultFieldInput_2024_06_14 {
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
       For example, if URL contains query parameter `&guests=bob@cal.com`,\
-      the guests field will be prefilled with this value and disabled.",
+      the guests field will be prefilled with this value and disabled. In case of Booker atom need to pass 'guests' to defaultFormValues prop with the desired value e.g. `defaultFormValues={{guests: ['bob@gmail.com', 'alice@gmail.com']}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 }
@@ -322,7 +322,7 @@ export class RescheduleReasonDefaultFieldInput_2024_06_14 {
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
       For example, if URL contains query parameter `&rescheduleReason=travel`,\
-      the rescheduleReason field will be prefilled with this value and disabled.",
+      the rescheduleReason field will be prefilled with this value and disabled. In case of Booker atom need to pass 'rescheduleReason' to defaultFormValues prop with the desired value e.g. `defaultFormValues={{rescheduleReason: 'bob'}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 }
@@ -360,7 +360,7 @@ export class PhoneFieldInput_2024_06_14 {
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
       For example, if the slug is `phone` and the URL contains query parameter `&phone=1234567890`,\
-      the phone field will be prefilled with this value and disabled.",
+      the phone field will be prefilled with this value and disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{phone: '+37122222222'}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 
@@ -407,7 +407,7 @@ export class AddressFieldInput_2024_06_14 {
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
       For example, if the slug is `address` and the URL contains query parameter `&address=1234 Main St, London`,\
-      the address field will be prefilled with this value and disabled.",
+      the address field will be prefilled with this value and disabled.  In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{address: 'mainstreat 10, new york'}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 
@@ -453,8 +453,8 @@ export class TextFieldInput_2024_06_14 {
     type: Boolean,
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
-      For example, if the slug is `who-referred-you` and the URL contains query parameter `&who-referred-you=bob`,\
-      the text field will be prefilled with this value and disabled.",
+      For example, if the slug is `friend` and the URL contains query parameter `&friend=bob`,\
+      the text field will be prefilled with this value and disabled.  In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value e.g. `defaultFormValues={{friend: 'bob'}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 
@@ -500,7 +500,8 @@ export class UrlFieldInput_2024_06_14 {
     type: Boolean,
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
-      For example, if the slug is `video-url` and the URL contains query parameter `&video-url=https://youtube.com/abc`the url field will be prefilled with this value and disabled.",
+      For example, if the slug is `videourl` and the URL contains query parameter `&videourl=https://youtube.com/abc`the url field will be prefilled with this value and disabled. \
+      In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value  e.g. `defaultFormValues={{videourl: 'https://caltube.com/123'}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 
@@ -546,8 +547,8 @@ export class NumberFieldInput_2024_06_14 {
     type: Boolean,
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
-      For example, if the slug is `calories-per-day` and the URL contains query parameter `&calories-per-day=3000`,\
-      the number field will be prefilled with this value and disabled.",
+      For example, if the slug is `calories` and the URL contains query parameter `&calories=3000`,\
+      the number field will be prefilled with this value and disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value  e.g. `defaultFormValues={{calories: 3000}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 
@@ -593,8 +594,8 @@ export class TextAreaFieldInput_2024_06_14 {
     type: Boolean,
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
-      For example, if the slug is `dear-diary` and the URL contains query parameter `&dear-diary=Today I shipped a feature`,\
-      the text area will be prefilled with this value and disabled.",
+      For example, if the slug is `reflection` and the URL contains query parameter `&reflection=Today I shipped a feature`,\
+      the text area will be prefilled with this value and disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value  e.g. `defaultFormValues={{reflection: 'Today i shipped a feature'}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 
@@ -645,7 +646,7 @@ export class SelectFieldInput_2024_06_14 {
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
       For example, if the slug is `language` and options of this select field are ['english', 'italian'] and the URL contains query parameter `&language=italian`,\
-      the 'italian' will be selected and the select field will be disabled.",
+      the 'italian' will be selected and the select field will be disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value  e.g. `defaultFormValues={{language: 'italian'}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 
@@ -689,8 +690,8 @@ export class MultiSelectFieldInput_2024_06_14 {
     type: Boolean,
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
-      For example, if the slug is `consultants` and the URL contains query parameter `&consultants=en&language=it`,\
-      the 'en' and 'it' will be selected and the select field will be disabled.",
+      For example, if the slug is `language` and the URL contains query parameter `&language=en&language=it`,\
+      the 'en' and 'it' will be selected and the select field will be disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value  e.g. `defaultFormValues={{language: ['en', 'it']}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 
@@ -737,7 +738,7 @@ export class MultiEmailFieldInput_2024_06_14 {
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
       For example, if the slug is `consultants` and the URL contains query parameter `&consultants=alice@gmail.com&consultants=bob@gmail.com`,\
-      the these emails will be added and none more can be added.",
+      the these emails will be added and none more can be added. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value  e.g. `defaultFormValues={{consultants: ['alice@gmail.com', 'bob@gmail.com']}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 
@@ -781,8 +782,8 @@ export class CheckboxGroupFieldInput_2024_06_14 {
     type: Boolean,
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
-      For example, if the slug is `notify-me` and the URL contains query parameter `&notify-me=true`,\
-      the checkbox will be selected and the checkbox field will be disabled.",
+      For example, if the slug is `notify` and the URL contains query parameter `&notify=true`,\
+      the checkbox will be selected and the checkbox field will be disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value  e.g. `defaultFormValues={{notify: true}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 
@@ -827,7 +828,7 @@ export class RadioGroupFieldInput_2024_06_14 {
     description:
       "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
       For example, if the slug is `language` and options of this select field are ['english', 'italian'] and the URL contains query parameter `&language=italian`,\
-      the 'italian' radio button will be selected and the select field will be disabled.",
+      the 'italian' radio button will be selected and the select field will be disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value  e.g. `defaultFormValues={{language: 'italian'}}`. See guide https://cal.com/docs/platform/guides/booking-field",
   })
   disableOnPrefill?: boolean;
 
@@ -863,7 +864,13 @@ export class BooleanFieldInput_2024_06_14 {
 
   @IsBoolean()
   @IsOptional()
-  @DocsPropertyOptional({ type: Boolean })
+  @DocsPropertyOptional({
+    type: Boolean,
+    description:
+      "Disable this booking field if the URL contains query parameter with key equal to the slug and prefill it with the provided value.\
+      For example, if the slug is `notify` and the URL contains query parameter `&notify=true`,\
+      the checkbox will be selected and the checkbox field will be disabled. In case of Booker atom need to pass slug you used for this booking field to defaultFormValues prop with the desired value  e.g. `defaultFormValues={{notify: true}}`. See guide https://cal.com/docs/platform/guides/booking-field",
+  })
   disableOnPrefill?: boolean;
 
   @IsBoolean()