Skip to main content

Introduction

Protrak Programs​

Programs let you add custom C# logic to Protrak configuration for a customer-specific process.

A program is a C# class that implements one of the program interfaces provided by the Protrak toolkit SDK. Protrak executes the program at a configured extension point, such as before an instance is created, after two instances are connected, during a promote action, from a scheduler, or through the common-program execution API.

Use programs for business rules, validations, calculated values, relationship automation, notifications, integrations, reusable helper logic, and other controlled customization scenarios.

When to Use Programs​

Prefer Protrak configuration first. Use a program when the required behavior cannot be expressed clearly with standard configuration, expressions, lifecycle settings, dynamic forms, notifications, or schema rules.

Typical program use cases include:

  • Validating an operation with customer-specific rules.
  • Calculating or updating attribute values from related data.
  • Creating, connecting, disconnecting, or deleting related instances.
  • Sending notifications based on process-specific conditions.
  • Calling external systems or internal services.
  • Running scheduled checks and background process automation.
  • Reusing shared logic across multiple triggers through common programs.
  • Dynamically deciding lifecycle promote behavior.

Avoid programs for simple configuration that the platform already supports. Custom code increases maintenance, test, and upgrade responsibility, so keep each program focused and well documented.

Program Execution Model​

Programs run inside the Protrak runtime and can use injected Protrak services through public properties. The exact input object, transaction behavior, and result handling depend on the program type.

In general:

  • Pre triggers run before the platform operation completes. They are commonly used for validation or for changing input data before Protrak saves it.
  • Post triggers run after the platform operation. They are commonly used for follow-up work such as notifications, relationship updates, or integration calls.
  • Promote action programs participate in lifecycle transitions.
  • Promote action command programs run as commands attached to lifecycle promote actions.
  • Scheduler programs run on configured schedules for recurring automation.
  • Report programs support custom report generation.
  • Common programs expose reusable logic that can be called from other programs or through the common-program API.

Many program interfaces have asynchronous versions, such as IPreCreateTriggerProgramAsync or ICommonProgramAsync. Prefer the async interfaces and RunAsync methods when a program calls services, performs I/O, or may need to scale with platform async APIs.

Program Result and Error Handling​

Trigger programs commonly return a ProgramResult.

  • Return success when the program completed and the platform operation should continue.
  • Return failure with clear error messages when the operation must be blocked.
  • Validate input objects defensively, especially in pre triggers where platform validation may not have run yet.
  • Do not assume optional attributes, related instances, users, files, or form values are always present.
  • Avoid irreversible side effects in pre triggers. For example, do not send an external email before a transaction can still roll back.

Use user-friendly error messages for failures that can appear in the UI or API response. Keep technical diagnostics in logs.

Service Injection​

Protrak services are injected into program classes as public properties. A program can use these services to read or update instances, relationships, users, roles, files, notifications, cache entries, project management data, and other platform resources.

Example:

public class MyPostCreateProgram : IPostCreateTriggerProgramAsync
{
public IInstanceService InstanceService { get; set; }
public INotificationService NotificationService { get; set; }

public async Task<ProgramResult> RunAsync(Instance instance)
{
// Program logic here.
return new ProgramResult { IsSuccess = true };
}
}

Program Categories​

Program categoryPurpose
Pre create, update, delete, get, import, upload, connect, disconnect, and relation triggersValidate or modify an operation before Protrak completes it.
Post create, update, get, upload, connect, disconnect, and relation triggersRun follow-up logic after Protrak completes an operation.
Promote actionCustomize lifecycle transition behavior, including dynamic target-state selection.
Promote action commandRun business logic as part of a lifecycle transition command.
SchedulerExecute recurring automation on a configured schedule.
ReportGenerate custom report output.
Common programShare reusable logic across programs or expose custom logic through the execution API.
  1. Confirm that the behavior cannot be implemented through configuration alone.
  2. Choose the narrowest program type and trigger timing for the requirement.
  3. Prefer the async program interface when services or I/O are involved.
  4. Validate all inputs and return clear failure messages for blocked operations.
  5. Keep irreversible side effects out of transactional pre triggers.
  6. Use common programs for genuinely shared logic.
  7. Test success, failure, missing-data, and permission scenarios before publishing the customization.

Child Pages​