Skip to main content

Promote Action Command

Promote Action Command Programs in Protrak are C# classes that implement the IPromoteActionCommandProgramAsync interface. They are used to execute custom business logic when a lifecycle state transition (promote action) occurs on an instance. These programs are invoked by the platform during the promote action, allowing you to perform validations, trigger side effects, or update instance data as part of the transition.

Coding guidelines​

  • A Promote Action Command program is a class that must implement the interface IPromoteActionCommandProgramAsync

    public interface IPromoteActionCommandProgramAsync
    {
      Task<ProgramResult> RunAsync(Instance instance, string fromState, string toState, string actionName);
    }

    NOTE: Implement IPromoteActionCommandProgramAsync with the RunAsync method to enable asynchronous, scalable trigger logic. Most internal service methods are now async, and their synchronous versions are deprecated and will be removed. Use RunAsync to ensure compatibility with these changes.

  • The method receives:

    • The Instance being promoted (with all current attribute values and references).
    • The fromState and toState names (workflow state transition).
    • The actionName (the promote action being executed).

  • The program can:

    • Validate the transition and block it by returning a failed ProgramResult (with error messages).
    • Update instance attributes or references before the transition completes.
    • Trigger side effects (e.g., send notifications, call external APIs, log audit events).

  • Always return a ProgramResult:

    • If IsSuccess is true, the promote action proceeds.
    • If IsSuccess is false, the transition is blocked and errors are shown to the user.

  • Avoid long-running or blocking operations, as promote actions are synchronous unless configured to run asynchronously.

  • Do not assume all attributes are populated; always check for nulls and handle missing data.

Typical use cases​

  • Enforcing business rules or validations on workflow transitions (e.g., cannot move to "Approved" unless all required fields are filled).
  • Automatically updating or calculating attribute values when a state changes.
  • Sending notifications or emails when a transition occurs.
  • Integrating with external systems (e.g., updating a ticket in a third-party system).
  • Logging or auditing workflow state transitions for compliance.

Anti-patterns​

  • Avoid duplicating validations that can be handled by workflow configuration or attribute-level rules.
  • Do not perform irreversible side effects (e.g., sending emails) unless you are certain the transition will not be rolled back.
  • Avoid complex, deeply nested logic that is hard to maintain or debug.
  • Do not assume the instance is in a valid or complete state; always validate required data.

Sample Code​

public class ValidateApprovalBeforePromoteCommand : IPromoteActionCommandProgram
{
    public ProgramResult Run(Instance instance, string fromState, string toState, string actionName)
    {
        // Example: Block promotion to "Approved" if required fields are missing
        if (toState == "Approved")
        {
            var requiredAttr = instance.Attributes.FirstOrDefault(a => a.Name == "ApprovalComment");
            if (requiredAttr == null || string.IsNullOrWhiteSpace(requiredAttr.TextValue))
            {
                return new ProgramResult
                {
                    IsSuccess = false,
                    Errors = new[] { "Approval comment is required before approving." }
                };
            }
        }
        // Optionally update instance attributes or trigger side effects here
        return new ProgramResult { IsSuccess = true };
    }
}

Note: The Run method (from IPromoteActionCommandProgram) should only be used if the trigger logic is fully synchronous, does not involve any service/API calls, and consists only lightweight in-memory operations.

Summary:
Promote Action Command Programs are the recommended way to implement custom business logic on workflow transitions in Protrak. They provide a powerful extension point for enforcing rules, updating data, and integrating with external systems as part of your workflow automation.