agent-generator 1.0.2 → 1.0.3

package/Generator_Patterns/Conditional.md

@@ -0,0 +1,84 @@
+# CONDITIONAL Generator — Rule-Based Data Selection
+
+---
+
+## Overview
+
+A **Conditional Generator** selects a data generator based on predefined conditions. It enables dynamic test data generation by evaluating input values or context and branching to different generator logic accordingly.
+
+---
+
+## When to Use
+
+- When the value of a parameter depends on other input values or request context.
+- To implement business rules, feature flags, or scenario-specific data.
+- For fallback/default logic when no condition matches.
+
+---
+
+## Structure
+
+A conditional generator contains:
+- `type`: Must be `"conditional"`
+- `conditions`: List of condition objects, each with:
+	- `when`: The condition to evaluate (key, operator, value)
+	- `then`: The generator or value to use if the condition matches
+- `else`: (optional) The generator or value to use if no conditions match
+
+---
+
+## Example
+
+```json
+{
+	"generators": {
+		"snippet_id": [
+			{
+				"type": "conditional",
+				"conditions": [
+					{
+						"when": {
+							"key": "$.input.query:modules",
+							"equals": "tickets"
+						},
+						"then": {
+							"use": "$generators:#/generators/ticket_id"
+						}
+					},
+					{
+						"when": {
+							"key": "$.input.query:modules",
+							"equals": "contacts"
+						},
+						"then": {
+							"use": "$generators:#/generators/contact_id"
+						}
+					}
+				],
+				"else": "$generators:#/generators/activity_id"
+			}
+		]
+	}
+}
+```
+
+---
+
+## Best Practices
+
+- Use input-based branching: reference request path, query, or body fields in `when`.
+- Reference other generators in `then` using correct relative paths or `$generators:` syntax.
+- Always provide an `else` clause if possible to avoid unexpected nulls.
+- Keep conditions mutually exclusive and clear.
+- Avoid deeply nested or overly complex chains for readability.
+
+---
+
+## Validation Checklist
+
+- Ensure all referenced generators exist.
+- Test each condition path for expected output.
+
+---
+
+*Last Updated: 17 February 2026*

package/Generator_Patterns/Dynamic.md

@@ -0,0 +1,129 @@
+
+# Rule: Referencing Single-Entity Dynamic Generator Dependencies
+
+When a dynamic generator is used as a dependency for another generator (e.g., createTicket), always reference the dependency in params as $<generatorname>.value, regardless of the dataPath used in the dependency generator. This ensures the correct value is passed even if the dataPath returns an array or a single value.
+
+**Example:**
+
+Dependency generator:
+```json
+{
+  "type": "dynamic",
+  "name": "departments",
+  "generatorOperationId": "support.Department.getDepartments",
+  "dataPath": "$.response.body:$.data[*].id"
+}
+```
+
+Dependent generator:
+```json
+{
+  "type": "dynamic",
+  "name": "ticket",
+  "generatorOperationId": "support.Ticket.createTicket",
+  "params": {
+    "departmentId": "$departments.value"
+  }
+}
+```
+
+## What It Does
+A DYNAMIC Generator fetches data from real API responses.
+
+---
+
+## When to Use DYNAMIC
+- When you need real system data that changes frequently (e.g., active agent IDs, current ticket IDs).
+- When there is an API available to fetch the required data.
+  
+---
+
+## Required Properties
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `type` | string | Must be `"dynamic"` |
+| `generatorOperationId` | string | Which API operation to call |
+| `dataPath` | string | Where to extract data from response |
+
+## Optional Properties
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `params` | object | Filter parameters: `{"status": "ACTIVE"}` |
+| `name` | string | Generator identifier (unique label for referencing in params) |
+
+---
+
+## DataPath Format
+
+**Pattern:** `$.response.body:$.path.to.data`
+
+**Examples:**
+- `$.response.body:$.data[0].id` - First item ID
+- `$.response.body:$.data[*].id` - All item IDs
+- `$.response.body:$.items[0].manager.id` - Nested field
+
+---
+
+## Examples
+
+### Single Result
+Fetch the first matching record:
+```json
+{
+  "type": "dynamic",
+  "generatorOperationId": "support.Agent.getAgents",
+  "dataPath": "$.response.body:$.data[0].id"
+}
+```
+### With Filter Parameters
+Find specific records:
+```json
+{
+  "type": "dynamic",
+  "generatorOperationId": "support.Agent.getAgents",
+  "dataPath": "$.response.body:$.data[*].id",
+  "params": {"status": "ACTIVE"}
+}
+```
+### Nested Field
+Extract from object hierarchy:
+```json
+{
+  "type": "dynamic",
+  "generatorOperationId": "support.Department.getDepartment",
+  "dataPath": "$.response.body:$.manager.id"
+}
+```
+---
+
+## Best Practices
+
+**Do:**
+- Use params to filter for specific scenarios
+- Give descriptive names showing the filter/status
+- Verify operationId exists in OpenAPI specification
+  
+**Avoid:**
+- Assuming first result is always valid
+- Generic names like "id"
+- Forgetting `[*]` on array parameters
+- Hardcoding fallback without DYNAMIC
+  
+---
+
+## Check
+- operationId is spelled correctly
+- dataPath matches actual response structure
+- params filter isn't too strict
+
+## Reference
+- **Fetch Method:** API operations
+- **Data Type:** Real system data
+- **Scope:** Cross-entity references possible
+- **Updates:** Auto-syncs with system data
+
+---
+
+*Last Updated: 17 February 2026*

package/Generator_Patterns/PathConfig.properties

@@ -0,0 +1,4 @@
+
+# Path configurations for generator framework (using source folder)
+GENERATOR_CONFIG_PATH=../source/api-data-generators/support/
+OAS_FILE_PATH=../source/openapi-specifications/v1.0/support/

package/Generator_Patterns/README.md

@@ -0,0 +1,118 @@
+# Data Generation Framework
+
+## What is this?
+
+This framework helps you generate test data for APIs defined in OpenAPI (OAS) files.
+
+In simple words:
+- You define generators in JSON.
+- Generators call APIs, reuse values, and build input data.
+- You can chain generators when one value depends on another.
+
+## What is a generator?
+
+A generator is a small JSON step that produces data.
+
+Examples:
+- Fetch `departmentId` from an API response
+- Reuse a value from request input
+- Set a fixed value like `priority = "high"`
+
+All generators must be inside the `generators` object.
+
+Basic format:
+
+```json
+{
+  "generators": {
+    "generator_name": [
+      {
+        "type": "..."
+      }
+    ]
+  }
+}
+```
+
+## About the Generator Agent
+
+The Generator Agent helps developers create generator files faster and correctly.
+
+The agent does the following:
+- Reads the target operation from OAS
+- Finds required dependencies from related operations
+- Creates generator steps in the correct dependency order
+- Uses only fields that exist in OAS (no invented params)
+- Produces output in the required `generators` JSON structure
+
+## Where to find paths
+
+Use `PathConfig.properties` as the source of truth:
+- `GENERATOR_CONFIG_PATH` for generator file locations
+- `OAS_FILE_PATH` for OpenAPI specification locations
+
+Always use these configured paths instead of hardcoding paths.
+
+## Generator types
+
+Use the right type based on your need:
+
+| Type | Purpose | Documentation |
+| --- | --- | --- |
+| Dynamic | Get values from API operations | [Dynamic](./Dynamic.md) |
+| Remote | Get values from system/remote helpers | [Remote](./Remote.md) |
+| Static | Use fixed constant values | [Static](./Static.md) |
+| Reference | Reuse existing values from input/other generators | [Reference](./Reference.md) |
+| Conditional | Choose values based on conditions | [Conditional](./Conditional.md) |
+
+## JSONPath quick guide
+
+Common response mapping format:
+
+`$.location:$.path`
+
+Examples:
+- `$.data[*].id` → all ids in an array
+- `$.data[0].id` → first id
+- `$.manager.id` → nested value
+- `$.users[?(@.active == true)].id` → filtered values
+
+## Developer workflow (quick)
+
+1. Identify the target API operation.
+2. Read the target operation in OAS.
+3. Identify dependency operations and required values.
+4. Choose proper generator types.
+5. Create a new generator file in the correct folder.
+6. Keep dependencies in order inside the same generator array.
+7. Validate all params and paths against OAS.
+
+## Important rules
+
+- Use snake_case generator names.
+- Keep names meaningful and short.
+- Use singular for single value, plural for list values.
+- Do not add fields that are not present in OAS.
+- Do not modify existing generators unless explicitly requested.
+
+## Reference Syntax
+
+```
+$<generatorname>.value                    // Generator reference
+$.input.body:$.fieldName                  // Request body
+$.input.query:$.paramName                 // Query parameter
+$.input.path:$.pathParam                  // URL path
+$.input.header:$.HeaderName               // HTTP header
+```
+
+## DataPath Format
+
+```
+$.response.body:$.data[0].id              // First item ID
+$.response.body:$.data[*].id              // All item IDs
+$.response.body:$.id                      // Direct ID field
+$.response.body:$.manager.id              // Nested field
+$.response.body:$.items[?(@.status == 'active')].id  // Filtered values
+```
+
+Last updated: 23 February 2026

package/Generator_Patterns/Reference.md

@@ -0,0 +1,98 @@
+# REFERENCE Generator - Use Request Input Data
+
+## What It Does
+
+Passes data directly from incoming request to response without modification. Extracts values from request body, query parameters, path parameters, or headers.
+
+---
+
+## When to Use REFERENCE
+
+Use REFERENCE when:
+A Reference Generator extracts data from previous API responses.- Using data from request body
+- Getting values from query parameters
+- Using path parameters
+- Using header values
+- Data comes directly from request
+
+**Common Scenarios:**
+- Pass ticket ID from request to response
+- Use query parameters in operations
+- Extract URL path parameters
+- Forward authorization headers
+- Use nested request objects
+
+---
+
+## Required Properties
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `type` | string | Must be `"reference"` |
+| `ref` | string | Path to request data |
+
+## Reference Path Format
+
+**Pattern:** `$.input.{location}:$.{jsonPath}`
+
+### Location Types
+
+| Location | Source | Example |
+|----------|--------|---------|
+| `$.input.body` | Request body JSON | `$.input.body:$.ticketId` |
+| `$.input.query` | Query parameters | `$.input.query:$.departmentId` |
+| `$.input.path` | URL path parameters | `$.input.path:$.ticketId` |
+| `$.input.header` | HTTP headers | `$.input.header:$.Authorization` |
+
+### Path Selector Examples
+
+| Reference | Extracts |
+|-----------|----------|
+| `$.input.body:$.fieldName` | Simple field from body |
+| `$.input.body:$.parent.child.fieldName` | Nested field |
+| `$.input.body:$.items[*].id` | All array IDs |
+| `$.input.body:$.items[0].id` | First array ID |
+| `$.input.query:$.parameterName` | Query parameter |
+| `$.input.path:$.pathParamName` | Path parameter |
+| `$.input.header:$.HeaderName` | Header value |
+
+---
+
+## Best Practices
+
+**Do:**
+- Verify request contains the fields you reference
+- Use exact field names (case-sensitive)
+- Use clear generator names matching source
+
+**Avoid:**
+- Referencing fields that don't exist
+- Assuming request structure without docs
+- Using REFERENCE for static values
+- Ignoring case sensitivity
+
+---
+
+## When to Use REFERENCE
+
+| Scenario | Use REFERENCE |
+|----------|---|
+| Pass-through from request | Yes |
+| Get data from request | Yes |
+| Fetch from database | No |
+| Fixed constant | No |
+| System timestamp | No |
+| Logic-based value | No |
+
+---
+
+## Reference
+
+- **Fetch Method:** Request fields
+- **Data Type:** Request data (pass-through)
+- **Scope:** Single request scope
+- **Updates:** From request content
+
+---
+
+*Last Updated: 17 February 2026*

package/Generator_Patterns/Remote.md

@@ -0,0 +1,259 @@
+# REMOTE Generator - Call System Functions
+
+## What It Does
+
+Calls built-in system functions for timestamps, enumerations, and configuration data. Generates system-level values instead of fetching from APIs.
+
+---
+
+## When to Use REMOTE
+
+Use REMOTE when you need:
+- Current, future, or past timestamps
+- Enumeration values from system
+- System configuration data
+- Dynamic field schemas
+- Generated vs. real data
+
+**Common Scenarios:**
+- Generate timestamps (created, modified, due dates)
+- Get enumeration values from system
+- Retrieve custom field schemas
+- Access system configurations
+
+---
+
+## Required Properties
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `type` | string | Must be `"remote"` |
+| `generatorMethod` | string | System function to call |
+| `inputs` | object | Function parameters |
+
+
+---
+
+## System Methods Reference
+
+| Method | Purpose | Use Case |
+|--------|---------|----------|
+| `getDateTime` | Generate timestamps | Created, modified, due dates |
+| `getDynamicEnumValues` | Get enumeration values | Status, priority, type fields |
+| `getCustomFieldSchema` | Get field structure | Custom field metadata |
+
+### Full Method Paths
+
+Complete method paths use:
+```
+applicationDriver.rpc.desk.DynamicDataProvider.methodName
+```
+
+Examples:
+- `applicationDriver.rpc.desk.DynamicDataProvider.getDateTime`
+- `applicationDriver.rpc.desk.DynamicDataProvider.getDynamicEnumValues`
+- `applicationDriver.rpc.desk.DynamicDataProvider.getCustomFieldSchema`
+
+---
+
+## Examples
+
+### Current Timestamp
+For "now" timestamps:
+```json
+{
+  "type": "remote",
+  "generatorMethod": "applicationDriver.rpc.desk.DynamicDataProvider.getDateTime",
+  "inputs": {
+    "timeLine": "current",
+    "format": "yyyy-MM-dd'T'HH:mm:ss'Z'"
+  }
+}
+```pport.Department.getDepartments",
+                "dataPath": "$.response.body:$.data[*].id"
+
+### Future Date
+For deadlines and expiry dates:
+```json
+{
+  "type": "remote",
+  "generatorMethod": "applicationDriver.rpc.desk.DynamicDataProvider.getDateTime",
+  "inputs": {
+    "timeLine": "future",
+    "format": "yyyy-MM-dd'T'HH:mm:ss'Z'"
+  }
+}
+```
+
+### Enumeration Values
+Get system enums:
+```json
+{
+  "type": "remote",
+  "generatorMethod": "applicationDriver.rpc.desk.DynamicDataProvider.getDynamicEnumValues",
+  "inputs": {
+    "fieldName": "priority",
+    "moduleName": "Ticket",
+    "orgId": "123"
+  }
+}
+```
+
+---
+
+## Timestamp Formats
+
+### Format Strings (Java SimpleDateFormat)
+
+| Format | Example | Use Case |
+|--------|---------|----------|
+| `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` | 2026-02-11T14:30:45.123Z | APIs with milliseconds |
+| `yyyy-MM-dd'T'HH:mm:ss'Z'` | 2026-02-11T14:30:45Z | ISO 8601 (recommended) |
+| `yyyy-MM-dd HH:mm:ss` | 2026-02-11 14:30:45 | Database format |
+| `yyyy-MM-dd` | 2026-02-11 | Date only |
+
+### Format Components
+
+| Symbol | Meaning | Example |
+|--------|---------|---------|
+| `yyyy` | 4-digit year | 2026 |
+| `MM` | 2-digit month | 02 (01-12) |
+| `dd` | 2-digit day | 11 (01-31) |
+| `HH` | 2-digit hour | 14 (00-23) |
+| `mm` | 2-digit minute | 30 (00-59) |
+| `ss` | 2-digit second | 45 (00-59) |
+| `SSS` | 3-digit milliseconds | 123 (000-999) |
+| `'Z'` | UTC timezone (quoted) | Z |
+
+---
+
+## Timeline Values
+
+| Value | Generates | Use Case | Example |
+|-------|-----------|----------|---------|
+| `current` | Now (today) | Creation timestamps | `createdAt: "2026-02-11T14:30:45Z"` |
+| `future` | Later date | Deadlines, expiry | `dueDate: "2026-03-15T23:59:59Z"` |
+| `past` | Earlier date | Historical data | `modifiedAt: "2026-01-10T08:00:00Z"` |
+
+---
+
+## Common Patterns
+
+### Multiple Timestamps
+Different generators for different timestamp meanings:
+```json
+"generators": {
+  "created_timestamp": [{
+    "type": "remote",
+    "generatorMethod": "applicationDriver.rpc.desk.DynamicDataProvider.getDateTime",
+    "inputs": {
+      "timeLine": "past",
+      "format": "yyyy-MM-dd'T'HH:mm:ss'Z'"
+    }
+  }],
+  "modified_timestamp": [{
+    "type": "remote",
+    "generatorMethod": "applicationDriver.rpc.desk.DynamicDataProvider.getDateTime",
+    "inputs": {
+      "timeLine": "current",
+      "format": "yyyy-MM-dd'T'HH:mm:ss'Z'"
+    }
+  }],
+  "due_date": [{
+    "type": "remote",
+    "generatorMethod": "applicationDriver.rpc.desk.DynamicDataProvider.getDateTime",
+    "inputs": {
+      "timeLine": "future",
+      "format": "yyyy-MM-dd'T'HH:mm:ss'Z'"
+    }
+  }]
+}
+```
+
+### Status Enumerations
+Different enums per field:
+```json
+"generators": {
+  "status": [{
+    "type": "remote",
+    "generatorMethod": "applicationDriver.rpc.desk.DynamicDataProvider.getDynamicEnumValues",
+    "inputs": {
+      "fieldName": "status",
+      "moduleName": "Ticket"
+    }
+  }],
+  "priority": [{
+    "type": "remote",
+    "generatorMethod": "applicationDriver.rpc.desk.DynamicDataProvider.getDynamicEnumValues",
+    "inputs": {
+      "fieldName": "priority",
+      "moduleName": "Ticket"
+    }
+  }]
+}
+```
+
+### Mixed Timestamps & Enums
+Combine both in one configuration:
+```json
+"generators": {
+  "status": [{...enum generator...}],
+  "priority": [{...enum generator...}],
+  "created_at": [{...current timestamp...}],
+  "due_at": [{...future timestamp...}]
+}
+```
+
+---
+
+## Best Practices
+
+**Do:**
+- Always include format for timestamps
+- Use consistent format across similar fields
+- Select appropriate timeline (current, future, past)
+- Verify enum field names against OpenAPI spec
+- Use UTC timezone (Z suffix)
+
+**Avoid:**
+- Mixing different timestamp formats per entity
+- Assuming enum values without verifying
+- Using hardcoded timestamps when REMOTE available
+- Forgetting to quote timezone literals like `'Z'`
+
+---
+
+## Troubleshooting
+
+### Timestamps in Wrong Format
+**Check:**
+- Format string is case-sensitive
+- Single quotes around literals: `'Z'` not `Z`
+- No extra characters in format
+- Example: `yyyy-MM-dd'T'HH:mm:ss'Z'`
+
+### Empty Enumeration Values
+**Verify:**
+- Field name is correct
+- Module name is correct
+- orgId matches your system
+- Field exists in that module
+
+### System Doesn't Recognize Method
+**Check:**
+- Full path: `applicationDriver.rpc.desk.DynamicDataProvider.methodName`
+- Method name spelled correctly
+- No typos in inputs
+
+---
+
+## Reference
+
+- **Fetch Method:** System functions
+- **Data Type:** Generated values
+- **Scope:** System-wide functions
+- **Updates:** Generated fresh each time
+
+---
+
+*Last Updated: 11 February 2026*