PreUpdateRelation Trigger

• PreUpdateRelation Trigger programs are executed while updating existing Relationship Instance.
• They are used to validate or manipulate the instances based on business requirements.
• They are executed synchronously, i.e. in the same transaction as the relationship instance updation.
• They are executed before standard validations are executed by the platform code.

Coding guidelines

• PreUpdateRelation Trigger program is a class that must implement the interface IPreUpdateRelationTriggerProgramAsync

  public interface IPreUpdateRelationTriggerProgramAsync
  {
    Task<ProgramResult> RunAsync(Relation relation);
  }

  NOTE: Implement IPreUpdateRelationTriggerProgramAsync 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 Relation object having information about the instances being linked to the trigger.

  • RelationId: The Guid that uniquely identifies the relationship instance.
  • RelationTypeName: The Relation Type name in Protrak schema using which the instances are being connected
  • Direction: Enum of type Enum.RelationDirection having value "From" indicating the direction.
  • SourceInstanceId: The "From type" instance id. If the direction is "From", the "To type" instance id as per the relation type definition.
  • DestinationInstanceId: The "To type" instance id.
  • RelationAttributes: Attribute[] having the relation attribute values.

• 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 PreUpdateRelation Trigger

• Validate the instances being linked where some business logic is involved.
• Manipulate the relationship instances based on business requirements.

Anti-patterns or when not to use PreUpdateRelation Trigger

• Do not use PreUpdateRelation trigger to make changes that are not reversible, like sending an email. If the connect process fails, the transaction will be rolled back, but the email would have been sent already! #Sample Code

public class ProjectPreUpdateRelationshipInstanceProgram : IPreUpdateRelationTriggerProgram
{
    public ProgramResult Run(Relation relation)
    {
        var errorMessages = ValidateProject(relation);
        if (errorMessages.Length == 0)
        {
            return new ProgramResult() { IsSuccess = true, Errors = null };
        }
        else
        {
            return new ProgramResult() { IsSuccess = false, Errors = errorMessages };
        }
    }

    private string[] ValidateProject(Relation relation)
    {
        //validation code here 
        return new string[] {};
    }
}

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