Codeunit 4316 Agent Task Message Builder, source in 28

// ------------------------------------------------------------------------------------------------
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License. See License.txt in the project root for license information.
// ------------------------------------------------------------------------------------------------

namespace System.Agents;

using System.Environment;

/// <summary>
/// This codeunit is used to create an agent task message.
/// </summary>
codeunit 4316 "Agent Task Message Builder"
{
    InherentEntitlements = X;
    InherentPermissions = X;

    var
        AgentTaskMsgBuilderImpl: Codeunit "Agent Task Msg. Builder Impl.";
        FeatureAccessManagement: Codeunit "Feature Access Management";

    /// <summary>
    /// Initialize the agent task message builder with the mandatory parameter.
    /// From value will be set to the current user.
    /// </summary>
    /// <param name="MessageText">The text of the message.</param>
    /// <returns>This instance of the Agent Task Message Builder.</returns>
    procedure Initialize(MessageText: Text): codeunit "Agent Task Message Builder"
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        AgentTaskMsgBuilderImpl.Initialize(MessageText);
        exit(this);
    end;

    /// <summary>
    /// Initialize the agent task message builder with the mandatory parameters.
    /// </summary>
    /// <param name="From">Text indicating the sender of the message.</param>
    /// <param name="MessageText">The text of the message.</param>
    /// <returns>This instance of the Agent Task Message Builder.</returns>
    procedure Initialize(From: Text[250]; MessageText: Text): codeunit "Agent Task Message Builder"
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        AgentTaskMsgBuilderImpl.Initialize(From, MessageText);
        exit(this);
    end;

    /// <summary>
    /// Set the external ID of the task.    
    /// </summary>
    /// <param name="RequiresReview">Specifies if the user needs to review and approve message before agent starts processing the task. The default value is true.</param>
    /// <returns>This instance of the Agent Task Message Builder.</returns>
    procedure SetRequiresReview(RequiresReview: Boolean): codeunit "Agent Task Message Builder"
    begin
        AgentTaskMsgBuilderImpl.SetRequiresReview(RequiresReview);
        exit(this);
    end;

    /// <summary>
    /// Set whether to ignore attachments for the message.
    /// When set to true, attachments will be marked as ignored and will not be processed by the agent.
    /// The default value is false.
    /// </summary>
    /// <param name="IgnoreAttachment">Specifies if attachments should be ignored.</param>
    procedure SetIgnoreAttachment(IgnoreAttachment: Boolean): codeunit "Agent Task Message Builder"
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        AgentTaskMsgBuilderImpl.SetIgnoreAttachment(IgnoreAttachment);
        exit(this);
    end;

    /// <summary>
    /// Set whether to sanitize the message text.
    /// When set to false, message sanitization will be bypassed.
    /// The default value is true.
    /// </summary>
    /// <param name="SkipSanitizeMessage">Specifies if the message sanitization should be skipped.</param>
    /// <returns>This instance of the Agent Task Message Builder.</returns>
    [Scope('OnPrem')]
    procedure SetSkipMessageSanitization(SkipSanitizeMessage: Boolean): codeunit "Agent Task Message Builder"
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        AgentTaskMsgBuilderImpl.SetSkipMessageSanitization(SkipSanitizeMessage);
        exit(this);
    end;

    /// <summary>
    /// Set the external ID of the task.
    /// </summary>
    /// <param name="ExternalId">The external ID of the task. This field is used to connect to external systems, like Message ID for emails.</param>
    /// <returns>This instance of the Agent Task Message Builder.</returns>
    procedure SetMessageExternalID(ExternalId: Text[2048]): codeunit "Agent Task Message Builder"
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        AgentTaskMsgBuilderImpl.SetMessageExternalID(ExternalId);
        exit(this);
    end;

    /// <summary>
    /// Set the agent task for which to create the message.
    /// </summary>
    /// <param name="ParentAgentTask">The agent task to set the message to.</param>
    /// <returns>This instance of the Agent Task Message Builder.</returns>
    procedure SetAgentTask(ParentAgentTask: Record "Agent Task"): codeunit "Agent Task Message Builder"
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        AgentTaskMsgBuilderImpl.SetAgentTask(ParentAgentTask);
        exit(this);
    end;

    /// <summary>
    /// Set the agent task for which to create the message.
    /// </summary>
    /// <param name="ParentAgentTaskID">The ID of the agent task to set the message to.</param>
    /// <returns>This instance of the Agent Task Message Builder.</returns>
    procedure SetAgentTask(ParentAgentTaskID: BigInteger): codeunit "Agent Task Message Builder"
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        AgentTaskMsgBuilderImpl.SetAgentTask(ParentAgentTaskID);
        exit(this);
    end;

    /// <summary>
    /// Creates the task message.
    /// Task will be marked as ready and be picked up for processing after message is created.
    /// </summary>
    /// <returns>
    /// The created task message.
    /// </returns>
    /// <remarks>
    /// The builder keeps the state, do not reuse the same instance of the builder to create multiple tasks. 
    /// </remarks>
    procedure Create(): Record "Agent Task Message"
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        exit(AgentTaskMsgBuilderImpl.Create());
    end;

    /// <summary>
    /// Creates the task message.
    /// </summary>
    /// <param name="SetTaskStatusToReady">Specifies if the task should be marked as ready for processing after the message is created.
    /// If set to false, the task will not be marked as ready and will not be picked up for processing. 
    /// </param>
    /// <returns>
    /// The created task message.
    /// </returns>
    /// <remarks>
    /// The builder keeps the state, do not reuse the same instance of the builder to create multiple tasks. 
    /// </remarks>
    procedure Create(SetTaskStatusToReady: Boolean): Record "Agent Task Message"
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        exit(AgentTaskMsgBuilderImpl.Create(SetTaskStatusToReady));
    end;

    /// <summary>
    /// Get the agent task message record.
    /// </summary>
    /// <returns>
    /// The agent task message that was created.
    /// </returns>
    procedure GetAgentTaskMessage(): Record "Agent Task Message"
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        exit(AgentTaskMsgBuilderImpl.GetAgentTaskMessage());
    end;

    /// <summary>
    /// Attach a file to the task message.
    /// The file will be attached when the message is created.
    /// It is possible to attach multiple files to the message.
    /// </summary>
    /// <param name="FileName">The name of the file to attach.</param>
    /// <param name="FileMIMEType">The MIME type of the file to attach.</param>
    /// <param name="InStream">The stream of the file to attach.</param>
    /// <returns>This instance of the Agent Task Message Builder.</returns>
    procedure AddAttachment(FileName: Text[250]; FileMIMEType: Text[100]; InStream: InStream): codeunit "Agent Task Message Builder"
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        AgentTaskMsgBuilderImpl.AddAttachment(FileName, FileMIMEType, InStream);
        exit(this);
    end;

    /// <summary>
    /// Attach a file to the task message.
    /// The file will be attached when the message is created.
    /// It is possible to attach multiple files to the message.
    /// </summary>
    /// <param name="FileName">The name of the file to attach.</param>
    /// <param name="FileMIMEType">The MIME type of the file to attach.</param>
    /// <param name="InStream">The stream of the file to attach.</param>
    /// <param name="Ignored">Specifies if the attachment should be marked as ignored, so that it is not processed by agent.</param>
    /// <returns>This instance of the Agent Task Message Builder.</returns>
    procedure AddAttachment(FileName: Text[250]; FileMIMEType: Text[100]; InStream: InStream; Ignored: Boolean): codeunit "Agent Task Message Builder"
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        AgentTaskMsgBuilderImpl.AddAttachment(FileName, FileMIMEType, InStream, Ignored);
        exit(this);
    end;

    /// <summary>
    /// Attach a file to the task message.
    /// The file will be attached when the message is created.
    /// It is possible to attach multiple files to the message.
    /// </summary>
    /// <param name="FileName">The name of the file to attach.</param>
    /// <param name="FileMIMEType">The MIME type of the file to attach.</param>
    /// <param name="InStream">The stream of the file to attach.</param>
    /// <param name="Ignored">Specifies if the attachment should be marked as ignored, so that it is not processed by agent.</param>
    /// <param name="IgnoredReason">Specifies why the attachment was ignored.</param>
    /// <returns>This instance of the Agent Task Message Builder.</returns>
    procedure AddAttachment(FileName: Text[250]; FileMIMEType: Text[100]; InStream: InStream; Ignored: Boolean; IgnoredReason: Text[250]): codeunit "Agent Task Message Builder"
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        AgentTaskMsgBuilderImpl.AddAttachment(FileName, FileMIMEType, InStream, Ignored, IgnoredReason);
        exit(this);
    end;

    /// <summary>
    /// Attach a file to the task message.
    /// The file will be attached when the message is created.
    /// It is possible to attach multiple files to the message.
    /// </summary>
    /// <param name="AgentTaskFile">The file to attach.</param>
    /// <returns>This instance of the Agent Task Message Builder.</returns>
#if not CLEAN28
#pragma warning disable AS0078
#endif
    procedure AddAttachment(var AgentTaskFile: Record "Agent Task File"): codeunit "Agent Task Message Builder"
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        AgentTaskMsgBuilderImpl.AddAttachment(AgentTaskFile);
        exit(this);
    end;
#if not CLEAN28
#pragma warning restore AS0078
#endif
    /// <summary>
    /// Uploads a file to the task message.
    /// The file will be attached when the message is created.
    /// It is possible to attach multiple files to the message.
    /// </summary>
    /// <returns>True if the attachment was uploaded, false otherwise.</returns>
    procedure UploadAttachment(): Boolean
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        exit(AgentTaskMsgBuilderImpl.UploadAttachment());
    end;

    /// <summary>
    /// Get the last attachment that was added to the task message.
    /// </summary>
    /// <returns>
    /// The last attachment that was added to the task message.
    /// </returns>
    procedure GetLastAttachment(): Record "Agent Task File"
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        exit(AgentTaskMsgBuilderImpl.GetLastAttachment());
    end;

    /// <summary>
    /// Get the last attachment that was added to the task message.
    /// </summary>
    /// <returns>
    /// True if any attachments exist for the task message, false otherwise.
    /// </returns>
    procedure GetAttachments(var TempAttachments: Record "Agent Task File" temporary): Boolean
    begin
        FeatureAccessManagement.AgentTaskManagementPreviewEnabled(true);
        exit(AgentTaskMsgBuilderImpl.GetAttachments(TempAttachments));
    end;
}