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 category | Purpose |
|---|---|
| Pre create, update, delete, get, import, upload, connect, disconnect, and relation triggers | Validate or modify an operation before Protrak completes it. |
| Post create, update, get, upload, connect, disconnect, and relation triggers | Run follow-up logic after Protrak completes an operation. |
| Promote action | Customize lifecycle transition behavior, including dynamic target-state selection. |
| Promote action command | Run business logic as part of a lifecycle transition command. |
| Scheduler | Execute recurring automation on a configured schedule. |
| Report | Generate custom report output. |
| Common program | Share reusable logic across programs or expose custom logic through the execution API. |
Recommended Authoring Flow
- Confirm that the behavior cannot be implemented through configuration alone.
- Choose the narrowest program type and trigger timing for the requirement.
- Prefer the async program interface when services or I/O are involved.
- Validate all inputs and return clear failure messages for blocked operations.
- Keep irreversible side effects out of transactional pre triggers.
- Use common programs for genuinely shared logic.
- Test success, failure, missing-data, and permission scenarios before publishing the customization.
Child Pages
- PreCreate Trigger
- PostCreate Trigger
- PreConnect Trigger
- PostConnect Trigger
- PreDisconnect Trigger
- PostDisconnect Trigger
- PreUpdateRelation Trigger
- PostUpdateRelation Trigger
- PreUpdate Trigger
- PostUpdate Trigger
- PreGet Trigger
- PostGet Trigger
- PreDelete Trigger
- Promote Action
- Promote Action Command
- Schedular
- Report
- Common Program
- PreUploadInstanceAttachment Trigger
- PostUploadInstanceAttachment Trigger
- PreDeleteInstanceAttachment Trigger
- PostDeleteInstanceAttachment Trigger
- PreImport Trigger