Skip to main content

Tutorial: Material Availability Check

Learn how to create a GUARD rule that prevents work orders from being released to production when required materials are not available in inventory. This tutorial demonstrates condition building, action configuration, and testing.

Scenario​

Problem: Work orders are sometimes released to the shop floor before all required materials are available, causing production delays and resource waste.

Solution: Create a business rule that checks material availability and blocks the status change if materials are not ready.

Rule Behavior:

  • IF work order status is changing to "RELEASED"
  • AND materials are not available
  • THEN block the status change and show an error message

Prerequisites​

  • Access to Business Rules module with business_rules.rules.create permission
  • Familiarity with work order workflow in your system
  • Understanding of your material availability field structure

Step 1: Navigate to Rules Page​

  1. Open the Open Mercato admin interface
  2. Navigate to Business Rules > Rules in the main menu
  3. Click the Create Rule button in the top-right corner

The rule creation form will open.

Step 2: Fill Basic Information​

Configure the rule's core properties.

Rule ID:

BLOCK_WO_RELEASE_WITHOUT_MATERIALS

Rule Name:

Block Work Order Release Without Materials

Description:

Prevents work orders from being released to production when required
materials are not available in inventory. This ensures production
schedulers have visibility into material constraints before committing
resources to the work order.

Rule Type: Select GUARD

💡 GUARD rules are designed to block or allow operations. They're perfect for this use case.

Rule Category:

Material Planning

Entity Type:

WorkOrder

Event Type:

onStatusChange

ℹī¸ The onStatusChange event triggers when the work order status field changes. This is more specific than beforeUpdate which fires on any field change.

Step 3: Set Metadata​

Configure execution settings.

Priority: 800

💡 High priority (500-1000) ensures this guard rule executes before other validation or action rules.

Enabled: ✅ Checked

Version: 1

Effective From: Leave empty (active immediately)

Effective To: Leave empty (no expiration)

Step 4: Build Conditions​

Define when the rule should block the operation.

Understanding the Logic​

We want to block when:

  1. The new status is "RELEASED" (user is trying to release the work order)
  2. Materials are NOT available

Click Add First Condition to begin.

Condition 1: Check New Status​

Field: newStatus

Operator: = (equals)

Value: "RELEASED"

ℹī¸ The newStatus field represents the status the user is trying to change to. This field is provided by the onStatusChange event.

Condition 2: Check Material Availability​

Click Add Condition to add a second condition to the AND group.

Field: materialsAvailable

Operator: = (equals)

Value: false

ℹī¸ This assumes your work order entity has a materialsAvailable boolean field. Adjust the field path based on your data model. You might use materials.available, materialStatus, or a calculated field.

Alternative: Check Material Quantity​

If you don't have a boolean flag, you can check quantities:

AND Group:
  - newStatus = "RELEASED"
  - requiredQuantity > availableQuantity

Or check for zero inventory:

AND Group:
  - newStatus = "RELEASED"
  - availableQuantity <= 0

Final Condition Structure​

Your condition builder should show:

AND Group (2 rules):
  - newStatus = "RELEASED"
  - materialsAvailable = false

This reads as: "Block when new status is RELEASED and materials are not available."

Step 5: Configure Actions​

Set up what happens when conditions match.

Understanding Success vs. Failure Actions​

For GUARD rules:

  • Success actions execute when conditions are FALSE (operation is allowed)
  • Failure actions execute when conditions are TRUE (operation is blocked)

This might seem counterintuitive at first! Think of it as:

  • Conditions define when to BLOCK
  • When conditions are true → failure → block
  • When conditions are false → success → allow

Add Failure Actions​

These execute when we want to block the release.

Navigate to the Failure Actions section and click Add Action.

Action 1: Block the Transition​

Type: Select BLOCK_TRANSITION

Configuration: No configuration needed

💡 This action prevents the status change from occurring.

Action 2: Show Error Message​

Click Add Action again.

Type: Select SHOW_ERROR

Message:

Cannot release work order. Required materials are not available in inventory. Please verify material availability and try again.

💡 Clear, actionable error messages help users understand what went wrong and how to fix it.

Action 3: Notify Material Planner​

Click Add Action again.

Type: Select NOTIFY

Recipients:

material.planner@company.com, production.supervisor@company.com

ℹī¸ Replace with actual email addresses or user IDs from your system.

Message:

Work order {{workOrderId}} cannot be released due to material unavailability. Status: {{status}}, Required materials: {{requiredMaterials}}

💡 Use {{field}} syntax to include dynamic data in notification messages.

Action 4: Log the Block​

Click Add Action once more.

Type: Select LOG

Level: Select warn

Message:

Blocked work order {{workOrderId}} release due to material unavailability. Requested by {{user.email}}

Success Actions​

Leave the Success Actions section empty.

When materials ARE available (conditions are false), the rule succeeds and allows the operation without taking any action.

Step 6: Save the Rule​

  1. Review all sections to ensure configuration is correct
  2. Click Create Rule at the bottom of the form
  3. You'll be redirected to the rule detail page

The rule is now active and will begin evaluating work order status changes immediately.

Step 7: Test the Rule​

Test the rule to ensure it works as expected.

Test Case 1: Materials NOT Available (Should Block)​

Using the API:

curl -X POST "$BASE_URL/api/business_rules/execute" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "WorkOrder",
    "entityId": "wo-test-001",
    "eventType": "onStatusChange",
    "data": {
      "workOrderId": "wo-test-001",
      "oldStatus": "PENDING",
      "newStatus": "RELEASED",
      "materialsAvailable": false,
      "requiredMaterials": "Steel plates, bolts"
    },
    "dryRun": true
  }'

Expected Response:

{
  "allowed": false,
  "executedRules": [
    {
      "ruleId": "BLOCK_WO_RELEASE_WITHOUT_MATERIALS",
      "result": "FAILURE",
      "conditionResult": true,
      "message": "Cannot release work order. Required materials are not available..."
    }
  ]
}

✅ Success: The rule blocked the operation as expected.

Test Case 2: Materials Available (Should Allow)​

curl -X POST "$BASE_URL/api/business_rules/execute" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "WorkOrder",
    "entityId": "wo-test-002",
    "eventType": "onStatusChange",
    "data": {
      "workOrderId": "wo-test-002",
      "oldStatus": "PENDING",
      "newStatus": "RELEASED",
      "materialsAvailable": true
    },
    "dryRun": true
  }'

Expected Response:

{
  "allowed": true,
  "executedRules": [
    {
      "ruleId": "BLOCK_WO_RELEASE_WITHOUT_MATERIALS",
      "result": "SUCCESS",
      "conditionResult": false
    }
  ]
}

✅ Success: The rule allowed the operation when materials are available.

Test Case 3: Different Status Change (Should Ignore)​

curl -X POST "$BASE_URL/api/business_rules/execute" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type": application/json" \
  -d '{
    "entityType": "WorkOrder",
    "entityId": "wo-test-003",
    "eventType": "onStatusChange",
    "data": {
      "workOrderId": "wo-test-003",
      "oldStatus": "PENDING",
      "newStatus": "IN_PROGRESS",
      "materialsAvailable": false
    },
    "dryRun": true
  }'

Expected Response:

{
  "allowed": true,
  "executedRules": [
    {
      "ruleId": "BLOCK_WO_RELEASE_WITHOUT_MATERIALS",
      "result": "SUCCESS",
      "conditionResult": false
    }
  ]
}

✅ Success: The rule didn't block because the status is not "RELEASED".

Step 8: Monitor Execution Logs​

After testing, check the execution logs:

  1. Navigate to Business Rules > Execution Logs
  2. Filter by ruleId: BLOCK_WO_RELEASE_WITHOUT_MATERIALS
  3. Review the log entries

You should see three log entries from your tests showing:

  • Timestamp
  • Result (SUCCESS or FAILURE)
  • Execution time
  • Input context (your test data)

Variations and Extensions​

Variation 1: Check Specific Material Items​

Instead of a boolean flag, check individual material items:

AND Group:
  - newStatus = "RELEASED"
  OR Group:
    - materials[0].quantity < materials[0].required
    - materials[1].quantity < materials[1].required

Variation 2: Allow Partial Release with Warning​

Use SHOW_WARNING instead of BLOCK_TRANSITION:

Failure Actions:
  - SHOW_WARNING: "Some materials are below minimum quantity"
  - LOG: warn, "Partial material availability for {{workOrderId}}"

Variation 3: Check Material Lead Time​

Add condition for lead time:

AND Group:
  - newStatus = "RELEASED"
  OR Group:
    - materialsAvailable = false
    - materialLeadTime > daysUntilRequired

Variation 4: Set Approval Flag​

Set a flag requiring manager approval when materials are short:

Failure Actions:
  - SET_FIELD: approvalRequired = true
  - SET_FIELD: approvalReason = "Material shortage"
  - NOTIFY: manager@company.com, "Approval needed for {{workOrderId}}"
  - ALLOW_TRANSITION  (allow but flag for review)

Troubleshooting​

Rule Not Executing​

Check:

  • Rule is enabled
  • Entity type matches exactly ("WorkOrder" vs "Work Order")
  • Event type matches ("onStatusChange")
  • No effective date restrictions

Rule Allowing When It Should Block​

Check:

  • Condition logic (AND vs OR)
  • Field paths are correct (materialsAvailable vs materials.available)
  • Values match data types (false vs "false")
  • Test data includes all required fields

Error Messages Not Showing​

Check:

  • SHOW_ERROR action is in Failure Actions (not Success Actions)
  • Action is properly configured with message
  • UI is listening for business rule errors

Notifications Not Sending​

Check:

  • NOTIFY action configuration
  • Recipient email addresses are valid
  • Email service is configured
  • Check system logs for delivery errors

Next Steps​

Now that you've built your first GUARD rule:

  1. Creating Rules - Step-by-step rule builder walkthrough
  2. Conditions Guide - Deep dive into condition logic
  3. Rule Sets - Organize related rules
  4. Execution Logs - Monitor and troubleshoot runs

Summary​

You've successfully created a GUARD rule that:

✅ Prevents work order release when materials are unavailable ✅ Shows clear error messages to users ✅ Notifies the material planning team ✅ Logs all blocked attempts for audit trail ✅ Allows release when materials are ready

This rule helps prevent production delays by ensuring material availability before committing resources to work orders.