Codeunit 4307 Agent Message, source in 29

// ------------------------------------------------------------------------------------------------
// 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;

codeunit 4307 "Agent Message"
{
    InherentEntitlements = X;
    InherentPermissions = X;

    var
        FeatureAccessManagement: Codeunit "Feature Access Management";

    /// <summary>
    /// Get the message text for the given agent task message.
    /// </summary>
    /// <param name="TaskID">The task ID of the message.</param>
    /// <param name="MessageID">The unique identifier of the message.</param>
    /// <returns>The body of the agent task message.</returns>
    procedure GetText(TaskID: BigInteger; MessageID: Guid): Text
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        exit(AgentMessageImpl.GetText(TaskID, MessageID));
    end;

    /// <summary>
    /// Get the message text for the given agent task message.
    /// The record is not retrieved again; the caller must ensure the record is up to date.
    /// </summary>
    /// <param name="AgentTaskMessage">Agent task message.</param>
    /// <returns>The body of the agent task message.</returns>
    procedure GetText(var AgentTaskMessage: Record "Agent Task Message"): Text
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        exit(AgentMessageImpl.GetText(AgentTaskMessage));
    end;

    /// <summary>
    /// Updates the message text.
    /// </summary>
    /// <param name="TaskID">The task ID of the message.</param>
    /// <param name="MessageID">The unique identifier of the message.</param>
    /// <param name="NewMessageText">New message text to set.</param>
    procedure UpdateText(TaskID: BigInteger; MessageID: Guid; NewMessageText: Text)
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        AgentMessageImpl.UpdateText(TaskID, MessageID, NewMessageText);
    end;

#if not CLEAN29
    /// <summary>
    /// Updates the message text.
    /// </summary>
    /// <param name="AgentTaskMessage">The message record to update.</param>
    /// <param name="NewMessageText">New message text to set.</param>
    [Obsolete('Use the overload that takes TaskID and MessageID instead.', '29.0')]
    procedure UpdateText(var AgentTaskMessage: Record "Agent Task Message"; NewMessageText: Text)
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        AgentMessageImpl.UpdateText(AgentTaskMessage, NewMessageText);
    end;
#endif

    /// <summary>
    /// Check if it is possible to edit the message.
    /// </summary>
    /// <param name="TaskID">The task ID of the message.</param>
    /// <param name="MessageID">The unique identifier of the message.</param>
    /// <returns>If it is possible to change the message.</returns>
    procedure IsEditable(TaskID: BigInteger; MessageID: Guid): Boolean
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        exit(AgentMessageImpl.IsEditable(TaskID, MessageID));
    end;

    /// <summary>
    /// Check if it is possible to edit the message.
    /// The record is not retrieved again; the caller must ensure the record is up to date.
    /// </summary>
    /// <param name="AgentTaskMessage">Agent task message to verify.</param>
    /// <returns>If it is possible to change the message.</returns>
    procedure IsEditable(var AgentTaskMessage: Record "Agent Task Message"): Boolean
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        exit(AgentMessageImpl.IsEditable(AgentTaskMessage));
    end;

    /// <summary>
    /// Sets the message status to sent.
    /// </summary>
    /// <param name="TaskID">The task ID of the message.</param>
    /// <param name="MessageID">The unique identifier of the message.</param>
    procedure SetStatusToSent(TaskID: BigInteger; MessageID: Guid)
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        AgentMessageImpl.SetStatusToSent(TaskID, MessageID);
    end;

#if not CLEAN29
    /// <summary>
    /// Sets the message status to sent.
    /// </summary>
    /// <param name="AgentTaskMessage">Agent task message to update status.</param>
    [Obsolete('Use the overload that takes TaskID and MessageID instead.', '29.0')]
    procedure SetStatusToSent(var AgentTaskMessage: Record "Agent Task Message")
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        AgentMessageImpl.SetStatusToSent(AgentTaskMessage);
    end;
#endif

    /// <summary>
    /// Sets the message status to failed, to indicate that delivery of the output message failed terminally.
    /// Only a reviewed output message, or one that already failed, can be set to failed.
    /// </summary>
    /// <param name="TaskID">The task ID of the message.</param>
    /// <param name="MessageID">The unique identifier of the message.</param>
    /// <param name="StatusReason">The reason the message could not be delivered. It is shown to the user and recorded on the agent task log entry.</param>
    procedure SetStatusToFailed(TaskID: BigInteger; MessageID: Guid; StatusReason: Text[250])
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        AgentMessageImpl.SetStatusToFailed(TaskID, MessageID, StatusReason);
    end;

    /// <summary>
    /// Sets the message status back to reviewed, so that delivery of a failed output message can be attempted again.
    /// The status reason of the previous failure is cleared.
    /// </summary>
    /// <param name="TaskID">The task ID of the message.</param>
    /// <param name="MessageID">The unique identifier of the message.</param>
    procedure SetStatusToReviewed(TaskID: BigInteger; MessageID: Guid)
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        AgentMessageImpl.SetStatusToReviewed(TaskID, MessageID);
    end;

    /// <summary>
    /// Add an attachment to the task message.
    /// </summary>
    /// <param name="FileName">The name of the file to be attached.</param>
    /// <param name="FileMIMEType">The MIME type of the file to be attached.</param>
    /// <param name="Attachment">The attachment stream.</param>
    [Scope('OnPrem')]
    procedure AddAttachment(var AgentTaskMessage: Record "Agent Task Message"; FileName: Text[250]; FileMIMEType: Text[100]; Attachment: InStream)
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        AgentMessageImpl.AddAttachment(AgentTaskMessage, FileName, FileMIMEType, Attachment);
    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">If true, attachments will be marked as ignored when added to a message.</param>
    procedure SetIgnoreAttachment(IgnoreAttachment: Boolean)
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        AgentMessageImpl.SetIgnoreAttachment(IgnoreAttachment);
    end;

    /// <summary>
    /// Downloads the attachments for a specific message.
    /// </summary>
    /// <param name="AgentTaskMessage">Message to download attachments for.</param>
    procedure DownloadAttachments(var AgentTaskMessage: Record "Agent Task Message")
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        AgentMessageImpl.DownloadAttachments(AgentTaskMessage);
    end;

    /// <summary>
    /// Shows the attachments for a specific message. If file is not supported to be shown, it will be downloaded.
    /// </summary>
    /// <param name="TaskID">Task ID to download attachments for.</param>
    /// <param name="FileID">File ID to download.</param>
    procedure ShowAttachment(TaskID: BigInteger; FileID: BigInteger)
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        AgentMessageImpl.ShowOrDownloadAttachment(TaskId, FileID, false);
    end;

    /// <summary>
    /// Shows the attachments for a specific message. If file is not supported to be shown, it will be downloaded.
    /// </summary>
    /// <param name="AgentTaskFile">Agent file to display.</param>
    procedure ShowAttachment(var AgentTaskFile: Record "Agent Task File")
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        AgentMessageImpl.ShowOrDownloadAttachment(AgentTaskFile, false);
    end;

    /// <summary>
    /// Loads the attachments for a specific message to the temporary buffer.
    /// </summary>  
    /// <param name="TaskID">Task ID to download attachments for.</param>
    /// <param name="MessageID">Message ID to download attachments for.</param>
    /// <param name="TempAgentTaskFile">Temporary buffer to load the attachments.</param>
    procedure GetAttachments(TaskID: BigInteger; MessageID: Guid; var TempAgentTaskFile: Record "Agent Task File" temporary)
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        AgentMessageImpl.GetAttachments(TaskID, MessageID, TempAgentTaskFile);
    end;

    /// <summary>
    /// Get the display text for the file size. 
    /// </summary>
    /// <param name="SizeInBytes">The size in bytes.</param>
    /// <returns>The display text for the file size.</returns>
    procedure GetFileSizeDisplayText(SizeInBytes: Decimal): Text
    var
        AgentMessageImpl: Codeunit "Agent Message Impl.";
    begin
        FeatureAccessManagement.AgentManagementAllowed(true);
        exit(AgentMessageImpl.GetFileSizeDisplayText(SizeInBytes));
    end;
}