Send Custom Event

Send Custom Event Mutation

Audience: Programmer

Sends a custom event to the pyck event system for processing by workflows and external integrations. The mutation now returns information about any workflows that were triggered by the event.

Arguments

Name	Type	Description
input	SendCustomEventInput!	Input data for the custom event

Return Type

SendCustomEventResponse - Confirmation of the event submission and triggered workflows.

Input Fields

SendCustomEventInput:

Field	Type	Description
type	String!	The type/category of the event
operation	String!	The operation being performed
payload	CustomEventPayloadInput!	Structured payload with entity ID and optional data

CustomEventPayloadInput:

Field	Type	Description
id	ID!	The identifier of the entity this event relates to
data	Map	Optional additional data and context information

Return Fields

SendCustomEventResponse:

Field	Type	Description
success	Boolean!	Whether the event was successfully submitted
workflows	[TemporalWorkflow!]!	List of workflows triggered by this event

The workflows field returns TemporalWorkflow objects containing:

• type: The workflow type name

• id: Unique identifier for the workflow instance

• runID: Unique identifier for the specific workflow run

Usage Example

mutation {
  sendCustomEvent(
    input: {
      type: "inventory"
      operation: "low_stock_alert"
      payload: {
        id: "item_123456789"
        data: {
          "itemName": "iPhone 13 Pro",
          "currentStock": 5,
          "minimumThreshold": 10,
          "locationId": "warehouse_main",
          "urgency": "high",
          "suggestedReorderQuantity": 50,
          "estimatedRunoutDate": "2024-02-15T10:00:00Z"
        }
      }
    }
  ) {
    success
    workflows {
      type
      id
      runID
    }
  }
}

mutation {
  # Send customer lifecycle event
  sendCustomEvent(
    input: {
      type: "customer"
      operation: "milestone_reached"
      payload: {
        id: "cust_987654321"
        data: {
          "customerName": "ACME Corp",
          "milestone": "first_anniversary",
          "totalOrderValue": 125000.00,
          "orderCount": 87,
          "loyaltyPoints": 12500,
          "accountManager": "[email protected]",
          "celebrationCampaign": "anniversary_rewards",
          "discountEligible": true
        }
      }
    }
  ) {
    success
    workflows {
      type
      id
      runID
    }
  }
}

mutation {
  # Send quality control event
  sendCustomEvent(
    input: {
      type: "quality"
      operation: "inspection_failed"
      payload: {
        id: "qc_20240131_001"
        data: {
          "itemId": "item_456789123",
          "batchNumber": "BATCH-2024-015",
          "inspectorId": "user_inspector_01",
          "failureReason": "dimension_out_of_tolerance",
          "measurements": {
            "length": 10.5,
            "expectedLength": 10.0,
            "tolerance": 0.2
          },
          "severity": "major",
          "quarantineRequired": true,
          "supplierNotificationRequired": true
        }
      }
    }
  ) {
    success
    workflows {
      type
      id
      runID
    }
  }
}

Event Types and Operations

Common Event Types

Inventory Events

• Type: "inventory"

• Operations:

  • "low_stock_alert" - Stock levels below threshold

  • "reorder_point_reached" - Time to reorder inventory

  • "excess_stock_detected" - Overstock situation

  • "item_expired" - Perishable items approaching expiration

Customer Events

• Type: "customer"

• Operations:

  • "milestone_reached" - Customer loyalty milestones

  • "payment_overdue" - Late payment notifications

  • "preference_updated" - Customer preference changes

  • "complaint_received" - Customer service issues

Order Events

• Type: "order"

• Operations:

  • "rush_order_received" - Expedited order processing

  • "bulk_order_discount" - Large order special handling

  • "order_modification" - Changes to existing orders

  • "delivery_delay" - Shipping delays and notifications

Quality Events

• Type: "quality"

• Operations:

  • "inspection_failed" - Quality control failures

  • "compliance_violation" - Regulatory compliance issues

  • "supplier_rating_changed" - Supplier performance updates

  • "recall_initiated" - Product recall procedures

Workflow Events

• Type: "workflow"

• Operations:

  • "manual_approval_required" - Human intervention needed

  • "process_exception" - Workflow exception handling

  • "sla_breach" - Service level agreement violations

  • "escalation_triggered" - Process escalation events

JavaScript Example

const SEND_CUSTOM_EVENT = gql`
  mutation SendCustomEvent($input: SendCustomEventInput!) {
    sendCustomEvent(input: $input) {
      success
      workflows {
        type
        id
        runID
      }
    }
  }
`;

// Using the mutation
const [sendCustomEvent] = useMutation(SEND_CUSTOM_EVENT);

const handleLowStockAlert = async (item) => {
  try {
    const { data } = await sendCustomEvent({
      variables: {
        input: {
          type: "inventory",
          operation: "low_stock_alert",
          payload: {
            id: item.id,
            data: {
              itemName: item.name,
              currentStock: item.stockLevel,
              minimumThreshold: item.minThreshold,
              locationId: item.locationId,
              urgency: item.stockLevel <= item.criticalThreshold ? "critical" : "high"
            }
          }
        }
      }
    });

    if (data.sendCustomEvent.success) {
      console.log('Low stock alert sent successfully');

      // Track triggered workflows
      if (data.sendCustomEvent.workflows.length > 0) {
        console.log('Triggered workflows:', data.sendCustomEvent.workflows);
        data.sendCustomEvent.workflows.forEach(workflow => {
          console.log(`Workflow ${workflow.type} started with ID: ${workflow.id}`);
        });
      }
    }
  } catch (error) {
    console.error('Error sending custom event:', error);
  }
};

Event Processing

Workflow Integration

Custom events can trigger Temporal workflows:

• Inventory Management: Automatic reordering workflows

• Customer Service: Support ticket creation and routing

• Quality Control: Inspection and compliance workflows

• Notification Systems: Email, SMS, and push notifications

External System Integration

Events can be consumed by external systems:

• ERP Systems: Business process automation

• CRM Platforms: Customer relationship management

• Analytics Tools: Business intelligence and reporting

• Monitoring Systems: Alerting and dashboard updates

Event Routing

Events are routed based on:

• Event Type: Different handlers for different event categories

• Operation: Specific processing logic for each operation

• Payload Content: Conditional routing based on event data

• Tenant Configuration: Organization-specific event handling

Payload Guidelines

Required Fields

While the payload is flexible, consider including:

• Entity IDs: Reference to related entities (customer, item, order, etc.)

• Timestamp: When the event occurred

• Source: System or user that generated the event

• Priority/Urgency: Event importance level

• Context: Additional information for processing

Data Types

The payload Map supports:

• Strings: Text data and identifiers

• Numbers: Quantities, amounts, measurements

• Booleans: Flags and status indicators

• Objects: Nested data structures

• Arrays: Lists of related items

Best Practices

1. Consistent Naming: Use consistent field names across similar events

2. Complete Context: Include all necessary information for processing

3. Avoid Sensitive Data: Don't include passwords or API keys

4. Structured Data: Use nested objects for complex information

5. Documentation: Document payload structure for each event type

Error Handling

Events may fail to process due to:

• Invalid Type/Operation: Unknown event type or operation

• Malformed Payload: Invalid or missing required data

• System Overload: Event queue at capacity

• Permission Issues: Insufficient rights to send certain events

• Configuration Problems: Event routing or processing configuration errors

Monitoring and Observability

Event Tracking

Monitor custom events through:

• Event Logs: Detailed logs of all event processing

• Metrics Dashboards: Event volume and processing times

• Error Rates: Failed event processing statistics

• Workflow Triggers: Events that successfully triggered workflows

Performance Considerations

• Event Volume: Monitor event throughput and system capacity

• Processing Latency: Time from event submission to processing

• Queue Depth: Backlog of pending events

• Resource Usage: CPU and memory consumption during event processing

Breaking Changes

Breaking Change (2025-01): The SendCustomEventInput.payload field type has changed from Map! to CustomEventPayloadInput!.

Migration required:

Before:

payload: {
  "itemId": "123",
  "itemName": "Widget"
}

After:

payload: {
  id: "123"
  data: {
    "itemName": "Widget"
  }
}

The entity ID must now be provided in the structured id field, while additional context data goes in the optional data field.

New Feature (2025-01): The SendCustomEventResponse now includes a workflows field that returns information about any Temporal workflows triggered by the event. This enables callers to track workflow executions.

Notes

• Events are processed asynchronously - success indicates submission, not completion

• The workflows array shows which workflows were triggered by the event

• Event types and operations should be coordinated across teams

• Consider implementing event versioning for backwards compatibility

• Use meaningful, descriptive event types and operations

• Test event processing in development environments before production use