Skip to main content

InstanceService.PromoteInstance

Reference​

Prorigo.Protrak.API.Contracts.Instance PromoteInstance(Guid instanceId, string actionName, string comments = null)

Use PromoteInstance to move a Protrak instance from its current state to the next state, as defined by the lifecycle and allowed promote actions. This API executes all configured validations, triggers, and promote action command programs for the transition.

Parameters​

  • instanceId: The unique identifier of the instance to be promoted.
  • actionName: The name of the promote action to execute (must be one of the allowed actions for the current state).
  • comments: (Optional) Comments to record with the promote action. These may be stored in the instance history or audit log.

Returns​

Prorigo.Protrak.API.Contracts.Instance:

  • Updated instance contract after the promote action is executed.
  • Includes new lifecycle state, updated attributes, allowed operations, allowed actions, and audit history.

Error Handling & Caveats​

  • If the instance does not exist or the user does not have permission, an exception is thrown.
  • If the promote action is not allowed for the current state, an error is returned.
  • If required validations or triggers fail, the promote action is blocked and errors are returned.
  • If promote action command programs return errors, the transition is blocked and error messages are shown to the user.
  • If the instance is already in a terminal state (e.g., "Closed"), further promote actions are not allowed.
  • Comments, if provided, are stored in the instance history and may be visible to users.
  • All attribute and reference updates configured for the transition are applied atomically with the promote action.

Usage​

try {
    var promotedInstance = InstanceService.PromoteInstance(instanceId, "Approve", "Approved by manager");
    var newState = promotedInstance.State;
    // Check promotedInstance.Attributes for any changes made during the transition
} catch (AccessDeniedException ex) {
    // Handle permission errors
} catch (ValidationException ex) {
    // Handle validation or business rule errors
} catch (Exception ex) {
    // Handle other errors (e.g., invalid action name, instance not found)
}

Example: Promoting an Invoice to "Paid"​

try {
    var promotedInvoice = InstanceService.PromoteInstance(invoiceId, "MarkAsPaid", "Payment received on 2025-07-18");
    Console.WriteLine($"Invoice state after promotion: {promotedInvoice.State}");
} catch (Exception ex) {
    // Handle errors (e.g., not allowed, missing required attributes)
}

Troubleshooting​

  • If the promote action is not available, check the instance's current state and allowed actions.
  • If validations fail, review error messages and ensure all required attributes and references are set.
  • If the instance is not updated as expected, verify that promote action command programs and triggers are not blocking the transition.
  • For batch/scheduler programs, always log errors and consider retry logic for transient failures.