PreUploadInstanceAttachment Trigger

• PreUploadInstanceAttachment Trigger programs are executed while an Attachment is created/ updated, before the platform code for Attachment creation/ updation executes.
• They are used to validate or manipulate the attachment linked with the instance or instance details based on business requirements.
• They are executed synchronously, i.e. in the same transaction as the attachment creation/ updation.

Coding guidelines

• PreUploadInstanceAttachment Trigger program is a class that must implement the interface IPreUploadInstanceAttachmentTriggerAsync

  public interface IPreUploadInstanceAttachmentTriggerAsync
  {
    Task<ProgramResult> RunAsync(Guid instanceId, InstanceFile instanceFile);
  }

  NOTE: Implement IPreUploadInstanceAttachmentTriggerAsync 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.

• Protrak runtime passes InstanceId and InstanceFile object having information about the instanceFile/ attachment being created/ updated to the trigger. This object can be modified by the program code (pass by reference).

• Program should return a ProgramResult object:

  • If IsSuccess is true, then the trigger execution is considered as successful.
  • If IsSuccess is false, then the trigger is considered as failed, subsequent code is not executed, and the DB transaction is rolled back.
  • If IsSuccess is false, ideally the string[] Errors should be populated with proper error messages which will be returned in API response, which can be displayed to end user.

Typical use cases for PreUploadInstanceAttachment Trigger

• Validate the instanceFile being created/ updated where some complex business logic is involved.
• Calculate and save an attribute value on the instance for which instanceFile is created/ updated using complex business logic. Use program trigger when the computation is not possible using expression attribute or using an expression attribute is not possible for some reason.
• If any validations or calculations need to use a third-party service or integration.

Anti-patterns or when not to use PreUploadInstanceAttachment Trigger

• Prefer configuration over customization. Avoid using a program when configurable validations or computations are possible, for example. using expressions in sequence code or using expression attributes.
• Do not use PreUploadInstanceAttachment trigger to make changes that are not reversible, like sending an email. If the create/ update process fails, the transaction will be rolled back, instance will not be visible but the email would have been sent already!

Sample Code

public class ProjectPreUploadInstanceAttachmentProgram : IPreUploadInstanceAttachmentAsync
{
    public Task<ProgramResult> RunAsync(Guid instanceId, InstanceFile instanceFile)
    {
        var instance = await InstanceService.GetInstanceAsync(instanceId, new string[]{});
        var errorMessages = ValidateProject(instance, instanceFile);
        if (errorMessages.Length == 0)
        {
            return new ProgramResult() { IsSuccess = true, Errors = null };
        }
        else
        {
            return new ProgramResult() { IsSuccess = false, Errors = errorMessages };
        }
    }

    private string[] ValidateProject(Instance instance, InstanceFile instanceFile)
    {
        //validation code here 
        return new string[] {};
    }
}

Note: The Run method (from IPreUploadInstanceAttachmentTrigger) 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.