Skip to main content
AutomationContext provides methods to attach structured annotations to objects, allowing automated analysis and validation workflows to provide meaningful feedback.

​
Object Annotations

Object annotations enable attaching different types of messages (errors, warnings, informational notes, and successes) to specific objects within an automation run. This helps in tracking issues, communicating insights, and guiding decision-making.
Why annotate objects? Annotations allow functions to return structured results, making them actionable in dashboards, reports, and workflows.

​
Example

from speckle_automate import AutomateContext

def automate_function(runCtx: AutomateContext):
    # Example: Structural validation
    runCtx.attach_error_to_objects(
        "Structural Analysis",
        ["obj_id_1", "obj_id_2"],
        "Beam span exceeds maximum allowable length"
    )
    
    runCtx.attach_warning_to_objects(
        "Load Analysis",
        ["obj_id_3"],
        "Load approaching maximum capacity"
    )
    
    runCtx.attach_info_to_objects(
        "Cost Analysis",
        ["obj_id_4", "obj_id_5"],
        "Material cost optimized"
    )

public static void Run(AutomationContext context)
{
    context.AttachErrorToObjects(
        "Structural Analysis",
        new[] { "obj_id_1", "obj_id_2" },
        "Beam span exceeds maximum allowable length"
    );
    
    context.AttachWarningToObjects(
        "Load Analysis",
        new[] { "obj_id_3" },
        "Load approaching maximum capacity"
    );
    
    context.AttachInfoToObjects(
        "Cost Analysis",
        new[] { "obj_id_4", "obj_id_5" },
        "Material cost optimized"
    );
}

​
Annotation Types

TypeMethodUse Case
Errorattach_error_to_objects()Critical issues requiring immediate action
Warningattach_warning_to_objects()Potential concerns needing attention
Infoattach_info_to_objects()General insights and analysis results
Successattach_success_to_objects()Positive outcomes or validation confirmations

​
Metadata and Customisation

Annotations can be enriched with additional metadata to improve interpretability and visualization.
Using Metadata in Annotations: The metadata parameter allows storing arbitrary key-value pairs alongside annotations, making them more descriptive and informative.

​
Example

runCtx.attach_info_to_objects(
    "Cost Analysis",
    ["obj_id_4", "obj_id_5"],
    "Material cost optimized",
    metadata={"currency": "USD", "cost_saved": 5000}
)

​
Gradient Visualization

Certain metadata keys affect how results are displayed in the model viewer:
  • gradient: Bool: Enables gradient-based visualization.
  • gradientValues: List[str]: Specifies values to apply to objects.
Example: 
runCtx.attach_info_to_objects(
    "Gradient Visualization",
    all_object_ids,
    "Values applied to objects in list order",
    metadata={"gradient": True, "gradientValues": gradient_values}
)

​
Best Practices

  • Use the appropriate annotation type to convey severity accurately.
  • Group related annotations into categories for better organization.
  • Provide clear, actionable messages to aid decision-making.
  • Include relevant object IDs to maintain traceability.
  • Leverage metadata for richer annotations and better UI integration.
By leveraging these methods, automation functions can provide structured feedback that enhances decision-making and workflow efficiency.
⌘I