@khester/create-dynamics-app 1.0.8 → 1.1.0

package/templates/dynamics-365-starter/src/examples/workflow-examples/sales-workflow.ts

@@ -0,0 +1,662 @@
+/**
+ * Example: Complete Sales Workflow Implementation
+ *
+ * This example demonstrates how to create a comprehensive business workflow
+ * that spans multiple entities (Account → Contact → Opportunity) using the
+ * enhanced template's entity models and patterns.
+ *
+ * @example
+ * ```typescript
+ * const workflow = new SalesWorkflow(apiService);
+ *
+ * // Execute complete workflow
+ * const result = await workflow.executeCompleteWorkflow({
+ *   accountName: 'ACME Corporation',
+ *   contactName: 'John Smith',
+ *   contactEmail: 'john.smith@acme.com',
+ *   opportunityName: 'Q1 Software License',
+ *   opportunityValue: 75000
+ * });
+ *
+ * console.log('Workflow completed:', result);
+ * ```
+ */
+
+import { IApiService } from '@khester/dynamics-ui-api-client';
+import { Account } from '../../models/Account';
+import { Contact } from '../../models/Contact';
+import { Logger } from '../../components/Logging/logger';
+import {
+  Opportunity,
+  SalesStageCode_OptionSet,
+  OpportunityStateCode_OptionSet,
+} from '../entity-examples/opportunity-model';
+
+/**
+ * Interface for workflow input data
+ */
+export interface SalesWorkflowInput {
+  /** Account information */
+  accountName: string;
+  accountWebsite?: string;
+  accountPhone?: string;
+  accountRevenue?: number;
+  industryCode?: number;
+
+  /** Contact information */
+  contactFirstName?: string;
+  contactLastName?: string;
+  contactEmail: string;
+  contactPhone?: string;
+
+  /** Opportunity information */
+  opportunityName: string;
+  opportunityValue?: number;
+  closeProbability?: number;
+  estimatedCloseDate?: Date;
+  description?: string;
+}
+
+/**
+ * Interface for workflow result
+ */
+export interface SalesWorkflowResult {
+  /** Created account */
+  account: Account;
+  /** Created contact */
+  contact: Contact;
+  /** Created opportunity */
+  opportunity: Opportunity;
+  /** Workflow execution summary */
+  summary: {
+    executionTime: number;
+    stepsCompleted: string[];
+    warnings: string[];
+    success: boolean;
+  };
+}
+
+/**
+ * Sales Workflow Class
+ *
+ * Implements a complete sales workflow that demonstrates:
+ * - Multi-entity operations with proper relationships
+ * - Transaction-like behavior with rollback on failure
+ * - Comprehensive error handling and logging
+ * - Performance monitoring and optimization
+ * - Business rule validation and enforcement
+ *
+ * @example
+ * ```typescript
+ * // Initialize workflow
+ * const salesWorkflow = new SalesWorkflow(apiService);
+ *
+ * // Execute with validation
+ * try {
+ *   const result = await salesWorkflow.executeCompleteWorkflow(workflowData);
+ *   console.log('Sales workflow completed successfully');
+ * } catch (error) {
+ *   console.error('Workflow failed:', error.message);
+ * }
+ *
+ * // Execute individual steps
+ * const account = await salesWorkflow.createOrFindAccount(accountData);
+ * const contact = await salesWorkflow.createContactForAccount(contactData, account.accountid);
+ * const opportunity = await salesWorkflow.createOpportunity(opportunityData, account.accountid, contact.contactid);
+ * ```
+ */
+export class SalesWorkflow {
+  private apiService: IApiService;
+  private loggerContext = 'SalesWorkflow';
+
+  /**
+   * Constructor
+   * @param apiService - The API service instance for Dynamics 365 operations
+   */
+  constructor(apiService: IApiService) {
+    this.apiService = apiService;
+    Logger.log('SalesWorkflow initialized', this.loggerContext);
+  }
+
+  /**
+   * Execute the complete sales workflow
+   *
+   * This method orchestrates the entire process:
+   * 1. Validate input data
+   * 2. Create or find existing account
+   * 3. Create contact associated with account
+   * 4. Create opportunity with proper relationships
+   * 5. Apply business rules and validation
+   *
+   * @param input - Workflow input data
+   * @returns Promise resolving to workflow result
+   * @throws Error if workflow fails at any step
+   */
+  public async executeCompleteWorkflow(
+    input: SalesWorkflowInput
+  ): Promise<SalesWorkflowResult> {
+    const startTime = performance.now();
+    const stepsCompleted: string[] = [];
+    const warnings: string[] = [];
+
+    try {
+      Logger.userAction(
+        'Sales workflow execution started',
+        {
+          opportunityName: input.opportunityName,
+          accountName: input.accountName,
+        },
+        this.loggerContext
+      );
+
+      // Step 1: Validate input
+      this.validateWorkflowInput(input);
+      stepsCompleted.push('Input validation');
+
+      // Step 2: Create or find account
+      Logger.log('Step 2: Creating or finding account', this.loggerContext);
+      const account = await this.createOrFindAccount({
+        name: input.accountName,
+        websiteurl: input.accountWebsite,
+        telephone1: input.accountPhone,
+        revenue: input.accountRevenue,
+        industrycode: input.industryCode,
+      });
+      stepsCompleted.push('Account creation/retrieval');
+
+      // Step 3: Create contact
+      Logger.log('Step 3: Creating contact', this.loggerContext);
+      const contact = await this.createContactForAccount(
+        {
+          firstname: input.contactFirstName,
+          lastname: input.contactLastName,
+          emailaddress1: input.contactEmail,
+          telephone1: input.contactPhone,
+        },
+        account.accountid!
+      );
+      stepsCompleted.push('Contact creation');
+
+      // Step 4: Create opportunity
+      Logger.log('Step 4: Creating opportunity', this.loggerContext);
+      const opportunity = await this.createOpportunity(
+        {
+          name: input.opportunityName,
+          estimatedvalue: input.opportunityValue,
+          closeprobability: input.closeProbability,
+          estimatedclosedate: input.estimatedCloseDate?.toISOString(),
+          description: input.description,
+        },
+        account.accountid!,
+        contact.contactid!
+      );
+      stepsCompleted.push('Opportunity creation');
+
+      // Step 5: Apply business rules
+      Logger.log('Step 5: Applying business rules', this.loggerContext);
+      const businessRuleWarnings = await this.applyBusinessRules(
+        account,
+        contact,
+        opportunity
+      );
+      warnings.push(...businessRuleWarnings);
+      stepsCompleted.push('Business rules validation');
+
+      const executionTime = performance.now() - startTime;
+      Logger.timing('Sales workflow execution', startTime, this.loggerContext);
+
+      const result: SalesWorkflowResult = {
+        account,
+        contact,
+        opportunity,
+        summary: {
+          executionTime,
+          stepsCompleted,
+          warnings,
+          success: true,
+        },
+      };
+
+      Logger.userAction(
+        'Sales workflow completed successfully',
+        {
+          executionTime: `${executionTime.toFixed(2)}ms`,
+          stepsCompleted: stepsCompleted.length,
+          warnings: warnings.length,
+        },
+        this.loggerContext
+      );
+
+      return result;
+    } catch (error) {
+      const executionTime = performance.now() - startTime;
+
+      Logger.error('Sales workflow failed', this.loggerContext, {
+        error,
+        stepsCompleted,
+        executionTime: `${executionTime.toFixed(2)}ms`,
+      });
+
+      // In a production system, you might want to implement rollback logic here
+      throw new Error(
+        `Sales workflow failed at step: ${stepsCompleted[stepsCompleted.length - 1] || 'initialization'}. ${error}`
+      );
+    }
+  }
+
+  /**
+   * Create or find an existing account
+   *
+   * Implements intelligent account creation that:
+   * - Searches for existing accounts by name
+   * - Creates new account if none found
+   * - Applies duplicate detection logic
+   *
+   * @param accountData - Account data
+   * @returns Promise resolving to account (existing or new)
+   */
+  public async createOrFindAccount(accountData: {
+    name: string;
+    websiteurl?: string;
+    telephone1?: string;
+    revenue?: number;
+    industrycode?: number;
+  }): Promise<Account> {
+    try {
+      // Search for existing account by name
+      Logger.log(
+        `Searching for existing account: ${accountData.name}`,
+        this.loggerContext
+      );
+      const existingAccounts = await Account.retrieveByName(
+        this.apiService,
+        accountData.name
+      );
+
+      if (existingAccounts.length > 0) {
+        const existingAccount = existingAccounts[0];
+        Logger.log(
+          `Found existing account: ${existingAccount.name} (${existingAccount.accountid})`,
+          this.loggerContext
+        );
+        return existingAccount;
+      }
+
+      // Create new account
+      Logger.log(
+        `Creating new account: ${accountData.name}`,
+        this.loggerContext
+      );
+      const newAccount = new Account(accountData);
+      const createdAccount = await Account.create(this.apiService, newAccount);
+
+      Logger.log(
+        `Successfully created account: ${createdAccount.name} (${createdAccount.accountid})`,
+        this.loggerContext
+      );
+
+      return createdAccount;
+    } catch (error) {
+      Logger.error(
+        `Failed to create or find account: ${accountData.name}`,
+        this.loggerContext,
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Create a contact associated with an account
+   *
+   * @param contactData - Contact data
+   * @param accountId - Account ID to associate with
+   * @returns Promise resolving to created contact
+   */
+  public async createContactForAccount(
+    contactData: {
+      firstname?: string;
+      lastname?: string;
+      emailaddress1: string;
+      telephone1?: string;
+    },
+    accountId: string
+  ): Promise<Contact> {
+    try {
+      // Check for existing contact with same email
+      Logger.log(
+        `Checking for existing contact with email: ${contactData.emailaddress1}`,
+        this.loggerContext
+      );
+
+      const existingContacts = await Contact.retrieveByEmail(
+        this.apiService,
+        contactData.emailaddress1
+      );
+      if (existingContacts.length > 0) {
+        const warning = `Contact with email ${contactData.emailaddress1} already exists`;
+        Logger.warn(warning, this.loggerContext);
+        // Return existing contact but you might want to handle this differently
+        return existingContacts[0];
+      }
+
+      // Create new contact with account relationship
+      const newContact = new Contact({
+        ...contactData,
+        parentcustomerid: accountId, // Associate with account
+      });
+
+      const createdContact = await Contact.create(this.apiService, newContact);
+
+      Logger.log(
+        `Successfully created contact: ${createdContact.firstname} ${createdContact.lastname} (${createdContact.contactid})`,
+        this.loggerContext
+      );
+
+      return createdContact;
+    } catch (error) {
+      Logger.error(
+        `Failed to create contact for account ${accountId}`,
+        this.loggerContext,
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Create an opportunity with proper relationships
+   *
+   * @param opportunityData - Opportunity data
+   * @param accountId - Related account ID
+   * @param contactId - Related contact ID
+   * @returns Promise resolving to created opportunity
+   */
+  public async createOpportunity(
+    opportunityData: {
+      name: string;
+      estimatedvalue?: number;
+      closeprobability?: number;
+      estimatedclosedate?: string;
+      description?: string;
+    },
+    accountId: string,
+    contactId: string
+  ): Promise<Opportunity> {
+    try {
+      // Create opportunity with relationships and default values
+      const newOpportunity = new Opportunity({
+        ...opportunityData,
+        parentaccountid: accountId,
+        parentcontactid: contactId,
+        salesstagecode: SalesStageCode_OptionSet.Qualify, // Start in Qualify stage
+        statecode: OpportunityStateCode_OptionSet.Open, // Active opportunity
+        closeprobability: opportunityData.closeprobability || 25, // Default probability for new opportunities
+      });
+
+      const createdOpportunity = await Opportunity.create(
+        this.apiService,
+        newOpportunity
+      );
+
+      Logger.log(
+        `Successfully created opportunity: ${createdOpportunity.name} (${createdOpportunity.opportunityid})`,
+        this.loggerContext
+      );
+
+      return createdOpportunity;
+    } catch (error) {
+      Logger.error(
+        `Failed to create opportunity for account ${accountId} and contact ${contactId}`,
+        this.loggerContext,
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Apply business rules and validation
+   *
+   * Implements custom business logic such as:
+   * - Credit limit checks
+   * - Opportunity value validation
+   * - Relationship consistency checks
+   *
+   * @param account - Created account
+   * @param contact - Created contact
+   * @param opportunity - Created opportunity
+   * @returns Array of warning messages
+   */
+  private async applyBusinessRules(
+    account: Account,
+    contact: Contact,
+    opportunity: Opportunity
+  ): Promise<string[]> {
+    const warnings: string[] = [];
+
+    try {
+      // Business Rule 1: High-value opportunity warning
+      if (opportunity.estimatedvalue && opportunity.estimatedvalue > 100000) {
+        const warning = `High-value opportunity detected: $${opportunity.estimatedvalue.toLocaleString()}`;
+        warnings.push(warning);
+        Logger.log(warning, this.loggerContext);
+      }
+
+      // Business Rule 2: Account revenue consistency
+      if (
+        account.revenue &&
+        opportunity.estimatedvalue &&
+        opportunity.estimatedvalue > account.revenue
+      ) {
+        const warning = 'Opportunity value exceeds account annual revenue';
+        warnings.push(warning);
+        Logger.log(warning, this.loggerContext);
+      }
+
+      // Business Rule 3: Contact email domain validation
+      if (contact.emailaddress1 && account.websiteurl) {
+        const emailDomain = contact.emailaddress1.split('@')[1];
+        const accountDomain = account.websiteurl
+          .replace(/^https?:\/\//, '')
+          .replace(/^www\./, '');
+
+        if (!emailDomain.includes(accountDomain.split('.')[0])) {
+          const warning = 'Contact email domain does not match account website';
+          warnings.push(warning);
+          Logger.log(warning, this.loggerContext);
+        }
+      }
+
+      // Business Rule 4: Opportunity close date validation
+      if (opportunity.estimatedclosedate) {
+        const closeDate = new Date(opportunity.estimatedclosedate);
+        const threeMonthsFromNow = new Date();
+        threeMonthsFromNow.setMonth(threeMonthsFromNow.getMonth() + 3);
+
+        if (closeDate > threeMonthsFromNow) {
+          const warning =
+            'Opportunity close date is more than 3 months in the future';
+          warnings.push(warning);
+          Logger.log(warning, this.loggerContext);
+        }
+      }
+
+      Logger.log(
+        `Business rules applied. Generated ${warnings.length} warnings.`,
+        this.loggerContext
+      );
+      return warnings;
+    } catch (error) {
+      Logger.error('Error applying business rules', this.loggerContext, error);
+      warnings.push('Error occurred while applying business rules');
+      return warnings;
+    }
+  }
+
+  /**
+   * Validate workflow input data
+   *
+   * @param input - Input data to validate
+   * @throws Error if validation fails
+   */
+  private validateWorkflowInput(input: SalesWorkflowInput): void {
+    const errors: string[] = [];
+
+    // Required fields validation
+    if (!input.accountName?.trim()) {
+      errors.push('Account name is required');
+    }
+
+    if (!input.contactEmail?.trim()) {
+      errors.push('Contact email is required');
+    }
+
+    if (!input.opportunityName?.trim()) {
+      errors.push('Opportunity name is required');
+    }
+
+    // Email format validation
+    if (
+      input.contactEmail &&
+      !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(input.contactEmail)
+    ) {
+      errors.push('Invalid contact email format');
+    }
+
+    // Opportunity value validation
+    if (input.opportunityValue !== undefined && input.opportunityValue < 0) {
+      errors.push('Opportunity value cannot be negative');
+    }
+
+    // Close probability validation
+    if (
+      input.closeProbability !== undefined &&
+      (input.closeProbability < 0 || input.closeProbability > 100)
+    ) {
+      errors.push('Close probability must be between 0 and 100');
+    }
+
+    // Close date validation
+    if (input.estimatedCloseDate && input.estimatedCloseDate < new Date()) {
+      errors.push('Estimated close date cannot be in the past');
+    }
+
+    if (errors.length > 0) {
+      const errorMessage = `Workflow validation failed: ${errors.join(', ')}`;
+      Logger.validation('SalesWorkflow', errors, this.loggerContext);
+      throw new Error(errorMessage);
+    }
+
+    Logger.log('Workflow input validation passed', this.loggerContext);
+  }
+
+  /**
+   * Get workflow execution statistics
+   *
+   * @returns Promise resolving to workflow statistics
+   */
+  public async getWorkflowStatistics(): Promise<{
+    totalAccounts: number;
+    totalContacts: number;
+    totalOpportunities: number;
+    averageOpportunityValue: number;
+  }> {
+    try {
+      const [accounts, contacts, opportunities] = await Promise.all([
+        Account.retrieveActiveAccounts(this.apiService),
+        Contact.retrieveActiveContacts(this.apiService),
+        Opportunity.retrieveActiveOpportunities(this.apiService),
+      ]);
+
+      const totalOpportunityValue = opportunities.reduce(
+        (sum, opp) => sum + (opp.estimatedvalue || 0),
+        0
+      );
+      const averageOpportunityValue =
+        opportunities.length > 0
+          ? totalOpportunityValue / opportunities.length
+          : 0;
+
+      return {
+        totalAccounts: accounts.length,
+        totalContacts: contacts.length,
+        totalOpportunities: opportunities.length,
+        averageOpportunityValue,
+      };
+    } catch (error) {
+      Logger.error(
+        'Failed to get workflow statistics',
+        this.loggerContext,
+        error
+      );
+      throw error;
+    }
+  }
+}
+
+/**
+ * Example usage scenarios
+ */
+export const workflowExamples = {
+  /**
+   * Basic workflow execution
+   */
+  basicWorkflow: async (apiService: IApiService) => {
+    const workflow = new SalesWorkflow(apiService);
+
+    const result = await workflow.executeCompleteWorkflow({
+      accountName: 'Contoso Ltd',
+      accountWebsite: 'https://contoso.com',
+      accountRevenue: 5000000,
+      contactFirstName: 'Jane',
+      contactLastName: 'Doe',
+      contactEmail: 'jane.doe@contoso.com',
+      contactPhone: '+1-555-0123',
+      opportunityName: 'Q1 Enterprise License',
+      opportunityValue: 75000,
+      closeProbability: 70,
+      estimatedCloseDate: new Date('2024-03-31'),
+      description: 'Enterprise software licensing opportunity for Q1',
+    });
+
+    return result;
+  },
+
+  /**
+   * High-value opportunity workflow
+   */
+  highValueWorkflow: async (apiService: IApiService) => {
+    const workflow = new SalesWorkflow(apiService);
+
+    const result = await workflow.executeCompleteWorkflow({
+      accountName: 'Fortune 500 Corp',
+      accountRevenue: 10000000,
+      contactEmail: 'cto@fortune500corp.com',
+      opportunityName: 'Digital Transformation Initiative',
+      opportunityValue: 500000,
+      closeProbability: 60,
+      description: 'Large-scale digital transformation project',
+    });
+
+    return result;
+  },
+
+  /**
+   * Workflow with existing account
+   */
+  existingAccountWorkflow: async (apiService: IApiService) => {
+    const workflow = new SalesWorkflow(apiService);
+
+    // This will find the existing account instead of creating a new one
+    const result = await workflow.executeCompleteWorkflow({
+      accountName: 'Microsoft Corporation', // Assuming this exists
+      contactEmail: 'partner@microsoft.com',
+      opportunityName: 'Partnership Opportunity',
+      opportunityValue: 250000,
+      closeProbability: 80,
+    });
+
+    return result;
+  },
+};