# Migration Guide: labeling-scenario → labeling (workflow)

## Overview

This guide covers the migration from the old `labeling-scenario` implementation in `@things-factory/integration-label-studio` to the new `@things-factory/labeling` package with `workflow` terminology.

## What Changed

### 1. Package Structure

**Before:**
```
packages/integration-label-studio/
  server/
    types/scenario-types.ts
    service/labeling-scenario-service.ts
```

**After:**
```
packages/labeling/                    # NEW PACKAGE
  server/
    types/workflow-types.ts           # Renamed from scenario-types
    service/labeling-workflow-service.ts  # Renamed from labeling-scenario-service
```

### 2. Terminology Changes

All `Scenario` terms have been renamed to `Workflow`:

| Old Term | New Term |
|----------|----------|
| `LabelingScenario` | `LabelingWorkflow` |
| `ScenarioStep` | `WorkflowStep` |
| `ScenarioStepType` | `WorkflowStepType` |
| `ScenarioStatus` | `WorkflowStatus` |
| `ScenarioExecution` | `WorkflowExecution` |
| `ScenarioExecutionStep` | `WorkflowExecutionStep` |
| `CreateScenarioRequest` | `CreateWorkflowRequest` |
| `ExecuteScenarioRequest` | `ExecuteWorkflowRequest` |
| `LabelingScenarioList` | `LabelingWorkflowList` |
| `ScenarioExecutionList` | `WorkflowExecutionList` |
| `LabelingScenarioService` | `LabelingWorkflowService` |

### 3. GraphQL API Changes

#### Mutations

| Old Mutation | New Mutation |
|-------------|-------------|
| `createLabelingScenario` | `createLabelingWorkflow` |
| `executeScenario` | `executeLabelingWorkflow` |
| `pauseScenario` | `pauseLabelingWorkflow` |
| `resumeScenario` | `resumeLabelingWorkflow` |

#### Queries

| Old Query | New Query |
|-----------|-----------|
| `labelingScenario` | `labelingWorkflow` |
| `labelingScenarios` | `labelingWorkflows` |
| `scenarioExecution` | `workflowExecution` |
| `scenarioExecutions` | `workflowExecutions` |

#### Arguments

| Old Argument | New Argument |
|-------------|-------------|
| `scenarioId` | `workflowId` |

## Migration Steps

### For Backend Code

1. **Update package dependencies** in your `package.json`:

   ```json
   {
     "dependencies": {
       "@things-factory/labeling": "^9.1.0"
     }
   }
   ```

2. **Update imports**:

   **Before:**
   ```typescript
   import {
     LabelingScenario,
     ScenarioStep,
     CreateScenarioRequest
   } from '@things-factory/integration-label-studio/dist-server/types/scenario-types.js'
   ```

   **After:**
   ```typescript
   import {
     LabelingWorkflow,
     WorkflowStep,
     CreateWorkflowRequest
   } from '@things-factory/labeling/dist-server/types/workflow-types.js'
   ```

3. **Update type references** in your code:

   ```typescript
   // Replace all occurrences
   LabelingScenario → LabelingWorkflow
   ScenarioStep → WorkflowStep
   ScenarioStatus → WorkflowStatus
   // etc.
   ```

### For GraphQL Queries/Mutations

1. **Update mutation calls**:

   **Before:**
   ```graphql
   mutation {
     createLabelingScenario(input: {
       name: "My Scenario"
       projectId: 123
       steps: [...]
     }) {
       id
       name
     }
   }
   ```

   **After:**
   ```graphql
   mutation {
     createLabelingWorkflow(input: {
       name: "My Workflow"
       projectId: 123
       steps: [...]
     }) {
       id
       name
     }
   }
   ```

2. **Update query calls**:

   **Before:**
   ```graphql
   query {
     labelingScenarios(projectId: 123) {
       items {
         id
         name
       }
     }
   }
   ```

   **After:**
   ```graphql
   query {
     labelingWorkflows(projectId: 123) {
       items {
         id
         name
       }
     }
   }
   ```

3. **Update execution calls**:

   **Before:**
   ```graphql
   mutation {
     executeScenario(input: {
       scenarioId: "uuid"
     }) {
       executionId
     }
   }
   ```

   **After:**
   ```graphql
   mutation {
     executeLabelingWorkflow(input: {
       workflowId: "uuid"
     }) {
       executionId
     }
   }
   ```

### For Frontend Code

1. **Update GraphQL query strings** in your components:

   ```typescript
   // Before
   const GET_SCENARIOS = gql`
     query {
       labelingScenarios {
         items {
           id
           name
         }
       }
     }
   `

   // After
   const GET_WORKFLOWS = gql`
     query {
       labelingWorkflows {
         items {
           id
           name
         }
       }
     }
   `
   ```

2. **Update component props and state**:

   ```typescript
   // Before
   interface Props {
     scenario: LabelingScenario
   }

   // After
   interface Props {
     workflow: LabelingWorkflow
   }
   ```

## Breaking Changes

### 1. GraphQL Schema

All GraphQL operations have new names. Old operations will not work and must be updated.

### 2. Package Location

The service is no longer in `@things-factory/integration-label-studio`. You must add `@things-factory/labeling` as a dependency.

### 3. Privilege Categories

The privilege category has changed from `"label-studio"` to `"labeling"`:

**Before:**
```typescript
@Directive('@privilege(category: "label-studio", privilege: "mutation")')
```

**After:**
```typescript
@Directive('@privilege(category: "labeling", privilege: "mutation")')
```

You may need to update your user roles and permissions accordingly.

## Backward Compatibility

**There is NO backward compatibility.** This is a breaking change that requires:

1. Updating all code references
2. Updating all GraphQL queries/mutations
3. Migrating any stored scenario data (if applicable)

The old files have been marked as `.deprecated` in `integration-label-studio` and will be removed in a future version.

## Data Migration

If you have existing scenario data stored in a database or configuration:

1. Export existing scenario definitions
2. Transform field names: `scenarioId` → `workflowId`, etc.
3. Update GraphQL type names in JSON configs
4. Re-import using the new workflow API

## Testing Checklist

- [ ] All imports updated to use `@things-factory/labeling`
- [ ] All type references changed from `Scenario*` to `Workflow*`
- [ ] All GraphQL queries/mutations updated
- [ ] Privilege categories updated to `"labeling"`
- [ ] Frontend components updated
- [ ] Integration tests passing
- [ ] End-to-end workflow execution verified

## Support

If you encounter issues during migration, please:

1. Check this guide for common problems
2. Review the [README.md](./README.md) for usage examples
3. Contact the Things-Factory team

## Timeline

- **Current Version**: `9.1.0` - New `@things-factory/labeling` package introduced
- **Deprecation**: Old scenario files marked as `.deprecated`
- **Future Version**: Old files will be removed entirely

Please migrate as soon as possible to avoid disruption.