Using @jss-rule-engine/workflow in a Next.js App

Overview

The @jss-rule-engine/workflow package provides workflow automation, database utilities, and integration points for Sitecore JSS Next.js applications. It is used for:

• Running workflows in response to API requests.
• Initializing and managing workflow-related databases.
• Handling scheduled tasks and Sitecore publish events.

1. Database Initialization

File: scripts/init-workflow-db.ts

This script initializes the workflow database using environment variables.

Example:

import { DatabaseService, getDatabaseServiceOptions } from '@jss-rule-engine/workflow';
import * as dotenv from 'dotenv';

dotenv.config({ override: true }); // Load environment variables

const dbServiceOptions = getDatabaseServiceOptions(process.env);
const databaseService = new DatabaseService(dbServiceOptions);

databaseService.init().then(() => {
  console.log('Database initialized successfully');
}).catch((error) => {
  console.error('Error initializing database:', error);
});

• Purpose: Run this script to set up the workflow database before using workflow features.

2. Running Workflows via API

File: src/pages/api/contact/submit.ts

This API route uses handleWorkflowRun to process workflow logic for contact form submissions.

Example:

import { handleWorkflowRun } from '@jss-rule-engine/workflow';

const runResult = await handleWorkflowRun({
  message,
  visitorId,
  workflowId
});

• Purpose: Processes a workflow run and returns the result to the client.

3. Handling Sitecore Publish Events

File: src/pages/api/sitecore/publish.ts

This API route uses ragItemsIndexingHandler to handle Sitecore publish webhooks and trigger indexing.

Example:

import { ragItemsIndexingHandler } from '@jss-rule-engine/workflow';

const runResult = await ragItemsIndexingHandler({ itemId: rootItemId });

• Purpose: Responds to Sitecore publish events and triggers workflow-based indexing.

4. Scheduled Tasks

File: src/pages/api/schedule/run.ts

This API route uses handleScheduledTasks to execute scheduled workflow tasks.

Example:

import { handleScheduledTasks } from '@jss-rule-engine/workflow';

const runResult = await handleScheduledTasks();

• Purpose: Runs scheduled tasks and returns execution results.

5. Environment Variables

• The workflow database and handlers rely on environment variables for configuration (e.g., database connection strings, secrets).

Summary

• Database: Use DatabaseService and getDatabaseServiceOptions to initialize and manage workflow databases.
• API Workflows: Use handleWorkflowRun to process workflow logic in API routes.
• Sitecore Events: Use ragItemsIndexingHandler to respond to Sitecore publish webhooks.
• Scheduled Tasks: Use handleScheduledTasks to run scheduled jobs.