PSA/docs/workflow/automation-hub-workflow-guide.md

# Automation Hub: Creating TypeScript Workflows

## Introduction

The Automation Hub provides a powerful interface for creating, managing, and monitoring TypeScript-based workflows. This guide will walk you through the practical steps of using the Automation Hub to create and manage your workflows.

## Table of Contents

1. [Automation Hub Overview](#automation-hub-overview)
2. [Creating a New Workflow](#creating-a-new-workflow)
3. [Using the Workflow Editor](#using-the-workflow-editor)
4. [Testing and Validating Workflows](#testing-and-validating-workflows)
5. [Managing Workflow Versions](#managing-workflow-versions)
6. [Attaching Workflows to Events](#attaching-workflows-to-events)
7. [Monitoring Workflow Executions](#monitoring-workflow-executions)
8. [Using Workflow Templates](#using-workflow-templates)
9. [Best Practices](#best-practices)

## Automation Hub Overview

The Automation Hub consists of four main sections:

1. **Template Library**: Browse and use predefined workflow templates
2. **Workflows**: Create, edit, and manage your custom workflows
3. **Events Catalog**: Configure event triggers for your workflows
4. **Logs & History**: Monitor workflow executions and troubleshoot issues

To access the Automation Hub, navigate to the main menu and select "Automation Hub".

## Creating a New Workflow

### Step 1: Navigate to the Workflows Section

1. Open the Automation Hub
2. Click on the "Workflows" tab in the navigation menu

### Step 2: Create a New Workflow

1. Click the "Create Workflow" button in the top-right corner
2. You'll be taken to the workflow editor page

### Step 3: Fill in Workflow Metadata

Complete the following fields in the metadata section:

- **Workflow Name**: Enter a descriptive name for your workflow
- **Description**: Provide a clear description of what the workflow does
- **Version**: Set the initial version (default is 1.0.0)
- **Tags**: Add relevant tags to categorize your workflow
- **Active**: Toggle to set whether the workflow is active or inactive

## Using the Workflow Editor

The workflow editor provides a TypeScript code editor with specialized features for workflow development.

### Editor Features

- **Syntax Highlighting**: TypeScript syntax is highlighted for readability
- **Code Completion**: Intelligent suggestions for workflow context methods and properties
- **Error Checking**: Real-time validation of your TypeScript code
- **Code Snippets**: Pre-built snippets for common workflow patterns

### Using Code Snippets

1. Type a keyword or press Ctrl+Space to see available snippets
2. Select a snippet from the dropdown menu
3. The snippet will be inserted with placeholders for customization

Available snippets include:
- Basic Workflow Structure
- Process Trigger Event
- Execute Action
- Parallel Actions
- Conditional Logic
- Error Handling

### Workflow Structure

Every workflow must follow this basic structure:

```typescript
async function workflow(context: WorkflowContext): Promise<void> {
  const { actions, data, events, logger } = context;
  
  // Initial state
  context.setState('initial');
  
  // Workflow implementation
  
  // Final state
  context.setState('completed');
}

```

### Key Components to Include

1. **State Management**: Always set and update workflow states
   ```typescript
   context.setState('initial');
   // Later
   context.setState('processing');
   // Finally
   context.setState('completed');
   ```

2. **Event Handling**: Process the trigger event that started the workflow
   ```typescript
   const triggerEvent = context.input.triggerEvent;
   ```

3. **Action Execution**: Perform actions to interact with systems
   ```typescript
   const result = await actions.someAction({ param: 'value' });
   ```

4. **Error Handling**: Include try/catch blocks for robustness
   ```typescript
   try {
     await actions.riskyOperation();
   } catch (error) {
     logger.error('Operation failed', error);
   }
   ```

5. **Logging**: Add logs for monitoring and debugging
   ```typescript
   logger.info('Workflow started');
   logger.debug('Processing data', someData);
   logger.error('Error occurred', error);
   ```

## Testing and Validating Workflows

### Using the Test Button

1. Click the "Test" button in the editor toolbar
2. The system will validate your workflow code
3. Results will be displayed, including:
   - Syntax errors
   - Structure validation
   - Security warnings
   - Best practice recommendations

### Understanding Validation Results

- **Success**: Your workflow code is valid and can be saved
- **Warnings**: Potential issues that should be reviewed but won't prevent saving
- **Errors**: Critical issues that must be fixed before saving

### Common Validation Warnings

- Missing error handling (try/catch blocks)
- Not using context.setState to track workflow state
- Security concerns like accessing process.env or using eval()

## Managing Workflow Versions

### Creating a New Version

1. Open an existing workflow
2. Make your changes
3. Update the version number in the metadata section
4. Click "Save Workflow"
5. A new version will be created while preserving the previous versions

### Using the Versions Dialog

1. Click the "Versions" button in the workflow editor
2. A dialog will open showing all versions of the workflow
3. For each version, you can see:
   - Version number
   - Creation date
   - Created by
   - Whether it's the current active version

### Setting the Active Version

1. Open the Versions dialog
2. Find the version you want to activate
3. Click "Set as Active"
4. The selected version will become the active one used for new workflow executions

## Attaching Workflows to Events

### Step 1: Navigate to the Events Catalog

1. Open the Automation Hub
2. Click on the "Events Catalog" tab

### Step 2: Find an Event

Browse or search for the event you want to attach a workflow to.

### Step 3: Attach a Workflow

1. Click the "Attach Workflow" button next to the event
2. Select a workflow from the dropdown menu
3. Configure parameter mapping if needed
4. Click "Save" to create the attachment

### Parameter Mapping

When attaching a workflow to an event, you can map event data to workflow parameters:

1. Select an event field from the dropdown
2. Select the corresponding workflow parameter
3. Add any transformation logic if needed
4. Repeat for all required parameters

## Monitoring Workflow Executions

### Step 1: Navigate to Logs & History

1. Open the Automation Hub
2. Click on the "Logs & History" tab

### Step 2: Browse Workflow Executions

The Logs & History section shows all workflow executions with:
- Workflow name
- Trigger event
- Execution status
- Start and end times
- Duration

### Step 3: View Execution Details

1. Click on a workflow execution to see details
2. The details view includes:
   - State transitions
   - Action executions and results
   - Events received and emitted
   - Log messages
   - Error information (if any)

### Using the Workflow Visualizer

1. Click the "Visualize" button for a workflow execution
2. A visual representation of the workflow will be displayed
3. The visualization shows:
   - States and transitions
   - Actions and their status
   - Events and their flow
   - Current state (for active workflows)

## Using Workflow Templates

### Step 1: Browse the Template Library

1. Open the Automation Hub
2. Click on the "Template Library" tab
3. Browse available templates by category or use the search function

### Step 2: Preview a Template

1. Click the "Preview" button on a template
2. Review the template code and description

### Step 3: Create a Workflow from a Template

1. Click "Create Workflow from Template"
2. You'll be taken to the workflow editor with the template code pre-loaded
3. Customize the workflow as needed
4. Save the workflow with your changes

### Available Template Categories

- Approval Workflows
- Request and Fulfillment Workflows
- Review and Feedback Workflows
- Onboarding and Provisioning Workflows
- Incident Management Workflows

## Best Practices

### Workflow Design

1. **Start Simple**: Begin with a clear, focused workflow
2. **Use Descriptive Names**: Name workflows, states, and variables clearly
3. **Include Comments**: Document complex logic and decisions
4. **Handle Errors**: Always include error handling
5. **Test Thoroughly**: Validate your workflow before deploying

### Performance Optimization

1. **Use Parallel Execution**: Run independent actions in parallel
2. **Minimize Data Storage**: Store only necessary data
3. **Optimize State Transitions**: Use meaningful states but don't overdo it
4. **Consider Workflow Size**: Break complex workflows into smaller ones

### Security Considerations

1. **Avoid Unsafe Patterns**: Don't use eval(), Function(), or access process.env
2. **Validate Inputs**: Check input data before processing
3. **Limit Scope**: Keep workflows focused on their specific purpose
4. **Follow Least Privilege**: Only request necessary permissions

### Maintenance Tips

1. **Version Properly**: Use semantic versioning (MAJOR.MINOR.PATCH)
2. **Document Changes**: Add comments explaining version changes
3. **Test Before Activating**: Always test new versions before setting them active
4. **Monitor Executions**: Regularly check the Logs & History section

## Conclusion

The Automation Hub provides a powerful environment for creating and managing TypeScript-based workflows. By following this guide, you can effectively create, test, and monitor workflows that automate your business processes.

For more detailed information on TypeScript workflow development, refer to the [TypeScript Workflow Creation Guide](typescript-workflow-creation.md).