Attach a Document to an Item, Assembly or Kit (Document Links)

// Attach a file to an item's Document Links tab, the way the P21 client does it.
// An assembly or kit is an item: its Assembly Maintenance Document Links tab and
// its pick tickets use the same link, through the link's display areas.
// 1. Upload the file into Item Maintenance's document upload folder (file handler).
// 2. Add the link in the Item window's "Add Item Maintenance Link" dialog (Interactive),
//    on the dialog's default display areas plus the ones named in Areas, or on every
//    area when Areas is { "ALL" }.
// 3. Save the Item window -- the dialog's OK alone writes nothing.
// 4. Read the link and its display areas back over OData.
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

// ---- EDIT THESE -----------------------------------------------------------
const string BaseUrl = "https://play.example.com";   // your P21 server
const string Username = "apiuser";
const string Password = "your-password";
const string ItemId = "WIDGET-001";                   // the item to attach to
const string FilePath = "WIDGET-001 drawing.pdf";     // the local file to attach
const string OutsideUse = "Y";                        // Outside Use: required to print with a form; "N" = internal only
string[] Areas = { "Assembly Maintenance", "Sales Order Pick Ticket" };  // extra display areas, by name;
                                                      // { } = the dialog's defaults, { "ALL" } = every area
const string SavePromptAnswer = "";                   // e.g. "cb_1" -- the button for a prompt the save raises
// ---------------------------------------------------------------------------

const int ItemMaintenanceArea = 1314;                 // document_link.source_area_cd for an item
const string UploadFolderSetting = "item_maintenance_doc_link_upload_folder_path";

var handler = new HttpClientHandler
{
    // Test tenants often present a self-signed cert. Delete this line in production.
    ServerCertificateCustomValidationCallback =
        HttpClientHandler.DangerousAcceptAnyServerCertificateValidator,
};
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromMinutes(2) };
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var token = await GetTokenAsync(client);
var uiServer = await GetUiServerAsync(client, token);
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var fileName = Path.GetFileName(FilePath);
var content = await File.ReadAllBytesAsync(FilePath);

// The folder P21's own Add Link dialog uploads into, and the item's uid.
var settings = await ODataAsync("system_setting", "value", $"name eq '{UploadFolderSetting}'");
var folder = settings.Count == 0 ? null : settings[0].GetProperty("value").GetString();
if (string.IsNullOrEmpty(folder)) { Console.WriteLine($"System setting {UploadFolderSetting} is not set"); return; }
folder = folder.TrimEnd('\\');
var quotedId = ItemId.Replace("'", "''");  // OData doubles a quote inside a string literal
var items = await ODataAsync("inv_mast", "inv_mast_uid", $"item_id eq '{quotedId}'");
if (items.Count == 0) { Console.WriteLine($"{ItemId} is not in P21"); return; }
var uid = items[0].GetProperty("inv_mast_uid").GetDecimal().ToString("0");
var linkPath = $"{folder}\\{fileName}";

// A second run must not add a second link.
var linksOnItem = $"source_area_cd eq {ItemMaintenanceArea} and key1_cd eq 'inv_mast_uid' " +
                  $"and key1_value eq '{uid}' and row_status_flag eq 704";
var existing = await ODataAsync("document_link", "document_link_uid,link_path", linksOnItem);
if (existing.Any(r => string.Equals(r.GetProperty("link_path").GetString(), linkPath,
        StringComparison.OrdinalIgnoreCase)))
{
    Console.WriteLine($"{ItemId} already links {linkPath}");
    return;
}

// 1. Upload. The body is the raw file; path names the upload folder.
var uploadUrl = $"{BaseUrl}/api/filehandler/file/path?fileName={Uri.EscapeDataString(fileName)}" +
                $"&path={Uri.EscapeDataString(folder)}";
var upload = await client.PostAsync(uploadUrl, new ByteArrayContent(content));
upload.EnsureSuccessStatusCode();
using (var uploaded = JsonDocument.Parse(await upload.Content.ReadAsStringAsync()))
{
    var size = uploaded.RootElement.GetProperty("SizeInBytes").GetInt64();
    if (size != content.Length)
        throw new InvalidOperationException($"Upload landed {size} bytes of {content.Length}");
    Console.WriteLine($"Uploaded {uploaded.RootElement.GetProperty("FullPath").GetString()}");
}

// 2. The Item window, the item, its Document Links tab, Add Link.
var session = await SendAsync(HttpMethod.Post, $"{uiServer}/api/ui/interactive/sessions/",
    new { ResponseWindowHandlingEnabled = true }, "session");
var sessionId = session.TryGetProperty("Id", out var id) ? id.GetString()
              : session.GetProperty("SessionId").GetString();
try
{
    var window = await SendAsync(HttpMethod.Post, $"{uiServer}/api/ui/interactive/v2/window",
        new { SessionId = sessionId, ServiceName = "Item" }, "open Item");
    var windowId = window.GetProperty("WindowId").GetString()!;

    await TabAsync("TABPAGE_1");
    await ChangeAsync(windowId, "item_id", ItemId, tabName: "TABPAGE_1");
    await TabAsync("DOCUMENT_LINK");
    var answer = await SendAsync(HttpMethod.Post, $"{uiServer}/api/ui/interactive/v2/tools",
        new { SessionId = sessionId, WindowId = windowId, ToolName = "m_addlink",
              DatawindowName = "document_link" }, "Add Link");
    var dialog = OpenedWindow(answer)
        ?? throw new InvalidOperationException($"Add Link opened no dialog: {answer}");

    // The dialog's own datawindow is _dw_link; it has no tabs.
    foreach (var (field, value) in new[] {
                 ("link_path", linkPath), ("link_name", fileName),
                 ("outside_use_flag", OutsideUse), ("mandatory_flag", "N") })
        await ChangeAsync(dialog, field, value, datawindow: "_dw_link");
    if (Areas.SequenceEqual(new[] { "ALL" }))
        // Select All moves every Available Area to Selected Areas.
        await SendAsync(HttpMethod.Post, $"{uiServer}/api/ui/interactive/v2/tools",
            new { SessionId = sessionId, WindowId = dialog, ToolName = "cb_selectall" }, "Select All");
    else
        foreach (var area in Areas)
        {
            if ((await AreaNamesAsync(dialog, "target")).Contains(area))
                continue;  // one of the dialog's defaults
            var available = await AreaNamesAsync(dialog, "source");  // re-read: the list shrinks
            if (!available.Contains(area))
                throw new InvalidOperationException(
                    $"'{area}' is not an Available Area: {string.Join(", ", available)}");
            // Selecting the row is a web-client call: ui/full, no /api/ prefix, 1-based
            // row. It is what enables the dialog's Select (cb_select) button.
            await SendAsync(HttpMethod.Post, $"{uiServer}/ui/full/v2/data/select",
                new { WindowId = dialog, DatawindowName = "source", TabPageName = (string?)null,
                      RowsToSelect = new[] { available.IndexOf(area) + 1 },
                      ActiveRowSpecification = "*" }, $"select {area}");
            await SendAsync(HttpMethod.Post, $"{uiServer}/api/ui/interactive/v2/tools",
                new { SessionId = sessionId, WindowId = dialog, ToolName = "cb_select" },
                $"Select {area}");
        }
    await SendAsync(HttpMethod.Post, $"{uiServer}/api/ui/interactive/v2/tools",
        new { SessionId = sessionId, WindowId = dialog, ToolName = "cb_ok" }, "OK");

    // 3. Save the Item window: the body is the bare window id.
    var saved = await SendAsync(HttpMethod.Put, $"{uiServer}/api/ui/interactive/v2/data",
        windowId, "save");
    // A business rule on the Item window can stop the save with a prompt
    // (Status 3). Name it and its buttons, and answer only when told to.
    while (saved.GetProperty("Status").GetInt32() == 3 && OpenedWindow(saved) is string prompt)
    {
        using var promptWindow = JsonDocument.Parse(await client.GetStringAsync(
            $"{uiServer}/api/ui/interactive/v2/window?id={prompt}"));
        var title = promptWindow.RootElement.GetProperty("Definition").GetProperty("Title").GetString();
        using var tools = JsonDocument.Parse(await client.GetStringAsync(
            $"{uiServer}/api/ui/interactive/v2/tools?windowId={prompt}"));
        var buttons = tools.RootElement.EnumerateArray()
            .Where(t => t.GetProperty("ToolName").GetString()!.StartsWith("cb_") &&
                        !string.IsNullOrEmpty(t.GetProperty("Text").GetString()))
            .ToDictionary(t => t.GetProperty("ToolName").GetString()!,
                          t => t.GetProperty("Text").GetString()!);
        if (!buttons.ContainsKey(SavePromptAnswer))
            throw new InvalidOperationException($"The save opened '{title}' with buttons " +
                string.Join(", ", buttons.Select(b => $"{b.Key} = {b.Value}")) +
                "; set SavePromptAnswer to one of them");
        Console.WriteLine($"Answered '{title}' with {buttons[SavePromptAnswer]}");
        saved = await SendAsync(HttpMethod.Post, $"{uiServer}/api/ui/interactive/v2/tools",
            new { SessionId = sessionId, WindowId = prompt, ToolName = SavePromptAnswer }, "answer");
    }
    if (saved.GetProperty("Status").GetInt32() != 1)
        throw new InvalidOperationException($"The save did not finish: {saved}");
    await client.DeleteAsync($"{uiServer}/api/ui/interactive/v2/window?id={windowId}");

    async Task TabAsync(string name) =>
        await SendAsync(HttpMethod.Put, $"{uiServer}/api/ui/interactive/v2/tab",
            new { SessionId = sessionId, WindowId = windowId, TabName = name, PageName = name },
            $"tab {name}");
}
finally
{
    await client.DeleteAsync($"{uiServer}/api/ui/interactive/sessions/");
}

// 4. Read it back: the link, and where P21 shows it.
var link = (await ODataAsync("document_link",
        "document_link_uid,link_name,link_path,outside_use_flag", linksOnItem))
    .First(r => string.Equals(r.GetProperty("link_path").GetString(), linkPath,
        StringComparison.OrdinalIgnoreCase));
var linkUid = link.GetProperty("document_link_uid").GetDecimal().ToString("0");
var areas = (await ODataAsync("document_link_area", "display_area_cd",
        $"document_link_uid eq {linkUid} and row_status_flag eq 704"))
    .Select(a => (int)a.GetProperty("display_area_cd").GetDecimal()).Order();
Console.WriteLine($"Linked {link.GetProperty("link_name").GetString()} to {ItemId} as " +
                  $"document_link_uid {linkUid}, outside use " +
                  $"{link.GetProperty("outside_use_flag").GetString()}, shown in areas " +
                  $"[{string.Join(", ", areas)}]");

// --- helpers ---------------------------------------------------------------

// One OData table read.
async Task<List<JsonElement>> ODataAsync(string table, string select, string where)
{
    var url = $"{BaseUrl}/odataservice/odata/table/{table}?$select={select}" +
              $"&$filter={Uri.EscapeDataString(where)}";
    var response = await client.GetAsync(url);
    response.EnsureSuccessStatusCode();
    using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
    return doc.RootElement.GetProperty("value").EnumerateArray().Select(e => e.Clone()).ToList();
}

// The dialog's Available ("source") or Selected ("target") areas, in order.
async Task<List<string>> AreaNamesAsync(string window, string datawindow)
{
    using var doc = JsonDocument.Parse(await client.GetStringAsync(
        $"{uiServer}/api/ui/interactive/v2/data?id={window}"));
    foreach (var dw in doc.RootElement.EnumerateArray())
    {
        if (dw.GetProperty("Name").GetString() != datawindow) continue;
        var column = dw.GetProperty("Columns").EnumerateArray()
            .Select(c => c.GetString()).ToList().IndexOf("code_description");
        return dw.TryGetProperty("Data", out var data) && data.ValueKind == JsonValueKind.Array
            ? data.EnumerateArray().Select(row => row[column].GetString()!).ToList()
            : new List<string>();
    }
    return new List<string>();
}

// One Interactive call; refuses HTTP errors and P21's Status 2 (failure).
async Task<JsonElement> SendAsync(HttpMethod method, string url, object body, string what)
{
    using var request = new HttpRequestMessage(method, url)
    {
        Content = new StringContent(JsonSerializer.Serialize(body), Encoding.UTF8,
            "application/json"),
    };
    var response = await client.SendAsync(request);
    var text = await response.Content.ReadAsStringAsync();
    if (!response.IsSuccessStatusCode)
        throw new InvalidOperationException($"{what}: HTTP {(int)response.StatusCode} {text}");
    var answer = text.Length == 0 ? default : JsonDocument.Parse(text).RootElement.Clone();
    if (answer.ValueKind == JsonValueKind.Object &&
        answer.TryGetProperty("Status", out var status) && status.GetInt32() == 2)
        throw new InvalidOperationException($"{what}: P21 refused it: {text}");
    return answer;
}

// One field change, on a tab of the window or on a tabless dialog's datawindow.
async Task ChangeAsync(string target, string field, string value,
    string? tabName = null, string? datawindow = null)
{
    var item = new Dictionary<string, string?> { ["TabName"] = tabName, ["FieldName"] = field,
                                                 ["Value"] = value };
    if (datawindow is not null) item["DatawindowName"] = datawindow;
    await SendAsync(HttpMethod.Put, $"{uiServer}/api/ui/interactive/v2/change",
        new { SessionId = sessionId, WindowId = target, List = new[] { item } },
        $"change {field}");
}

// The window id a tool opened (its windowopened event), or null.
static string? OpenedWindow(JsonElement answer)
{
    if (!answer.TryGetProperty("Events", out var events)) return null;
    foreach (var e in events.EnumerateArray())
        if (e.GetProperty("Name").GetString() == "windowopened")
            foreach (var pair in e.GetProperty("Data").EnumerateArray())
                if (pair.GetProperty("Key").GetString() == "windowid")
                    return pair.GetProperty("Value").GetString();
    return null;
}

// v2 token endpoint — credentials go in the body, never in headers.
static async Task<string> GetTokenAsync(HttpClient client)
{
    var payload = JsonSerializer.Serialize(new { username = Username, password = Password });
    var response = await client.PostAsync(
        $"{BaseUrl}/api/security/token/v2",
        new StringContent(payload, Encoding.UTF8, "application/json"));
    response.EnsureSuccessStatusCode();
    return ReadField(await response.Content.ReadAsStringAsync(), "AccessToken");
}

// Transaction and Interactive calls go to the UI server, not BaseUrl.
static async Task<string> GetUiServerAsync(HttpClient client, string token)
{
    using var request = new HttpRequestMessage(
        HttpMethod.Get, $"{BaseUrl}/api/ui/router/v1/?urlType=external");
    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
    var response = await client.SendAsync(request);
    response.EnsureSuccessStatusCode();
    return ReadField(await response.Content.ReadAsStringAsync(), "Url").TrimEnd('/');
}

// Some middleware answers these two endpoints in XML even when asked for JSON.
static string ReadField(string payload, string field)
{
    try
    {
        var value = JsonDocument.Parse(payload).RootElement.GetProperty(field).GetString();
        if (!string.IsNullOrEmpty(value)) return value;
    }
    catch (Exception ex) when (ex is JsonException or KeyNotFoundException) { }

    var match = System.Text.RegularExpressions.Regex.Match(payload, $"<{field}>([^<]+)</{field}>");
    if (!match.Success)
        throw new InvalidOperationException(
            $"No {field} in response: {payload[..Math.Min(200, payload.Length)]}");
    return match.Groups[1].Value;
}