Bliss RPA Execution Framework

A comprehensive RPA (Robotic Process Automation) execution framework built with TypeScript, Playwright, and AWS CDK for automated web scraping and data processing.

Installation

pnpm install

API Reference

Core Execution Classes

Execution

Main execution class that manages browser context and page execution.

import { Execution } from "./src";

const execution = new Execution(browser, fieldList, options);
const pageExecution = await execution.pageExecution();

Constructor Parameters:

• browser: Browser - Playwright browser instance
• fieldList: Edge.InsurerEdgeFields[] - List of insurer fields
• options?: ExecutionOptions - Optional execution configuration

Methods:

• pageExecution(createNewPage?: boolean): Promise<PageExecution> - Creates a new page execution context
• setCanonicalContext(value: DispatchOrderEvent): void - Sets the canonical context
• canonicalContext(): DispatchOrderEvent | undefined - Retrieves the canonical context
• addContext<T>(key: string, value: T): void - Adds a context value
• getContext<T>(key: string): T | undefined - Retrieves a context value
• getOptions(): ExecutionOptions - Returns execution options
• finish(): Promise<void> - Finishes execution and stops tracing

ExecutionContext<T>

Generic context management class for storing key-value pairs during execution.

import { ExecutionContext } from "./src";

const context = new ExecutionContext<unknown>(fieldList);

Methods:

• set(key: string, value: T): void - Sets a value
• get(key: string): T | undefined - Retrieves a value
• add(value: T): void - Adds a value with auto-generated key
• getAll(): Map<string, T> - Returns all entries
• clear(): void - Clears all entries
• delete(key: string): boolean - Deletes an entry
• has(key: string): boolean - Checks if key exists
• size(): number - Returns number of entries
• keys(): IterableIterator<string> - Returns all keys
• values(): IterableIterator<T> - Returns all values
• entries(): IterableIterator<[string, T]> - Returns all entries
• getTranslatedValue(key: string, value: string, type: Edge.InsurerEdgeFieldOptionType): string - Translates values

PageExecution

Handles page-level execution with Playwright page object.

import { PageExecution } from "./src";

const pageExecution = new PageExecution(page, context, execution);

Methods:

• execute(fn: PageExecutionFunction): Promise<void> - Executes a function
• execute(sequence: Sequence): Promise<void> - Executes a sequence
• goAndExecute(url: string, fn: PageExecutionFunction): Promise<void> - Navigates and executes
• getExecution(): Execution - Returns execution instance
• getPage(): Page - Returns Playwright page

Error Classes

FieldErrorRule

Custom error class for field validation errors.

import { FieldErrorRule } from "./src";

throw new FieldErrorRule(
  "Error message",
  "fieldName",
  "validation rule",
  cause
);

Properties:

• fieldName: string | undefined - Name of the field with error
• rule: string | undefined - Validation rule that failed
• cause: Error | undefined - Original error cause

FieldNotFound

Error class for when a field is not found on the page.

import { FieldNotFound } from "./src";

throw new FieldNotFound("Field not found", "fieldName", cause);

Properties:

• fieldName: string | undefined - Name of the missing field
• cause: Error | undefined - Original error cause

Stack Classes (AWS CDK)

RPAStack

Main AWS CDK stack for RPA infrastructure.

import { RPAStack, RPAStackProps } from "./src";

const stack = new RPAStack(app, "RPAStack", props);

Properties:

• taskDefinition: ecs.TaskDefinition - ECS task definition
• container: ecs.ContainerDefinition - ECS container definition
• cluster: ecs.Cluster - ECS cluster
• rpaBucket: IBucket - S3 bucket for RPA processing

TaskTriggerRPAStack

Extended RPA stack with task triggering capabilities.

import { TaskTriggerRPAStack } from "./src";

const stack = new TaskTriggerRPAStack(app, "TaskTriggerStack", props);

RPAMonitoring

Monitoring stack for RPA infrastructure.

import { RPAMonitoring } from "./src";

const monitoring = new RPAMonitoring(cluster, props);

Event Handling

DispatchEvent

Handles event dispatching to SNS topics.

import { DispatchEvent } from "./src";

const dispatchEvent = new DispatchEvent(snsArn, snsClient);
await dispatchEvent.callback({
  correlationId: "id",
  processingStatus: "SUCCESS",
  errorReason: "error",
  metadata: {},
});

Utilities

Callback

Utility for making callback API requests.

import { Callback } from "./src";

await Callback.success({ eventId: "id" });
await Callback.error({ eventId: "id", errorReason: "error" });

Field Utilities

Collection of utility functions for field manipulation.

import {
  formatToUSDate,
  getMonthsDifference,
  fill,
  validateError,
  fillAndValidate,
} from "./src";

// Format date to US format
const usDate = formatToUSDate("25/12/2023", "-"); // '2023-12-25'

// Calculate months difference
const monthsDiff = getMonthsDifference("2023-01-01"); // number

// Fill a field with validation
await fillAndValidate(locator, "value", "fieldName", ".error-selector", {
  clear: true,
});

File Operations

Utilities for file download and manipulation.

import { downloadFileToBuffer, downloadFile, downloadFileToDisk } from "./src";

// Download file to buffer
const buffer = await downloadFileToBuffer(url);

// Download file to disk
await downloadFileToDisk(url, "/path/to/file");

// Download file with metadata
const result = await downloadFile(url);

Insurer Fields

Function to retrieve insurer field data.

import { getInsurerFields } from "./src";

const fields = await getInsurerFields("insurerId");

Environment Utilities

Environment detection utilities.

import { environment, isLambda, isEcs, isLocal } from "./src";

if (isLocal) {
  // Local development logic
}

Decorators

FieldErrorHandler

Decorator for automatic error handling in methods.

import { FieldErrorHandler } from "./src";

class MyClass {
  @FieldErrorHandler()
  async myMethod() {
    // Method implementation
  }
}

Data Classes

DataField<T>

Generic data field class for type-safe field management.

import { DataField } from "./src";

const field = new DataField(String, "name", 256);
console.log(field.getType()); // 'String'
console.log(field.getFieldName()); // 'name'
console.log(field.getFieldSize()); // 256

Types

Execution Types

interface ExecutionOptions {
  debug?: boolean;
  locale?: string;
  timezone?: string;
  timeout?: number;
}

Page Execution Types

type Sequence = Record<string, SequenceExecution>;

interface SequenceExecution {
  name?: string;
  go?: string;
  page?: PageExecutionFunction;
  actions?: Action[];
  fields?: Field[];
}

interface SubAction {
  type: string;
  value?: string;
  label?: string;
}

interface Action {
  name: string;
  locator?: string;
  action: string | SubAction;
  value?: string;
  meta?: Record<string, unknown>;
}

interface Field {
  name: string;
}

interface PageExecutionFunctionProps {
  page: Page;
  context: ExecutionContext<unknown>;
  pageExecution: PageExecution;
  execution: Execution;
}

type PageExecutionFunction = (
  props: PageExecutionFunctionProps
) => Promise<void> | void;

File Types

interface FileInfo {
  mime: string | undefined | null;
  size: number;
  name: string;
  path?: string;
  buffer?: ArrayBuffer;
}

interface DownloadFileResponse {
  fileUrl?: string;
  fileInfo: FileInfo;
}

Field Utility Types

interface FillOptions {
  clear?: boolean;
}

Stack Types

interface RPAStackProps extends StackProps {
  readonly insurer: string;
  readonly vpcId: string;
  readonly privateSubnetIds: string[];
  readonly securityGroup: string[];
  readonly docker: {
    build: boolean;
    dockerfilePath: string;
  };
  readonly trigger: {
    path: string;
    handler: string;
  };
  readonly secrets: {
    create: boolean;
  };
  readonly npmToken: string;
  readonly stage: string;
  readonly bucket: {
    name: string;
  };
  readonly snsTopicArn: string;
  readonly callback: {
    url?: string;
    apiKey?: string;
    snsTopicArn?: string;
  };
  readonly unleash: {
    baseUrl: string;
    apiToken: string;
  };
  readonly insurerEdge: {
    url: string;
    apiKey: string;
  };
  readonly auth?: {
    username?: string;
    password?: string;
    meta?: Record<string, string>;
  };
  readonly infosSecretId: string;
}

Build

Docker

Build docker container image

Amazon Linux 2

docker buildx build --build-arg NPM_TOKEN=$BLISS_NPM_TOKEN --platform linux/amd64 --provenance=false -t bliss-porto-rpa-playwright:latest .

Ubuntu

docker buildx build --build-arg NPM_TOKEN=$BLISS_NPM_TOKEN -t bliss-porto-rpa-playwright:latest .

docker build -t bliss-porto-rpa-playwright:latest .

Run container

docker run -p 9000:8080 bliss-porto-rpa-playwright:latest

Invoke function

curl -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'

Deployment

aws cloudformation delete-stack --stack-name CDKToolkit --profile bliss-sb

pnpm cdk synth --debug --profile bliss-sb
cdk bootstrap --profile bliss-sb
pnpm cdk deploy --debug --profile bliss-sb

cdk deploy --all --require-approval never --profile bliss-sb

pnpm aws:deploy --force
pnpm ts-node src/function/handler.ts

Useful Links

• CloudWatch Logs
• SQS Console
• ECS Console

Testing

Inside that directory, you can run several commands:

pnpm exec playwright test

Runs the end-to-end tests.

pnpm exec playwright test --ui

Starts the interactive UI mode.

pnpm exec playwright test --project=chromium

Runs the tests only on Desktop Chrome.

pnpm exec playwright test example

Runs the tests in a specific file.

pnpm exec playwright test --debug

Runs the tests in debug mode.

pnpm exec playwright codegen

Auto generate tests with Codegen.

We suggest that you begin by typing:

pnpm exec playwright test

And check out the following files:

• ./tests/example.spec.ts - Example end-to-end test
• ./tests-examples/demo-todo-app.spec.ts - Demo Todo App end-to-end tests
• ./playwright.config.ts - Playwright Test configuration

Visit https://playwright.dev/docs/intro for more information. ✨

Happy hacking! 🎭