Skip to main content

​
Overview

APM allows you to remotely create or update print templates via WebSocket. This enables dynamic template management from your web application without manually editing configuration files.

​
Update Template Request

Send a template update to APM.

​
Message Format

{
  "Action": "UpdateTemplate",
  "Template": {
    "TemplateId": "template_ticket_001",
    "Name": "Sales Receipt",
    "DocumentType": "ticket_venta",
    "Sections": [
      {
        "Name": "Header",
        "Type": "Static",
        "Order": 1,
        "Elements": [
          {
            "Type": "Text",
            "StaticValue": "My Store Name",
            "Format": "Bold,Large",
            "Align": "Center",
            "Order": 1
          },
          {
            "Type": "Text",
            "Label": "Invoice: ",
            "Source": "Number",
            "Format": "Bold",
            "Align": "Left",
            "Order": 2
          }
        ]
      },
      {
        "Name": "Items",
        "Type": "Table",
        "DataSource": "Items",
        "Order": 2,
        "Elements": [
          {
            "Type": "Text",
            "Source": "Name",
            "WidthPercentage": 50,
            "Align": "Left",
            "Order": 1
          },
          {
            "Type": "Text",
            "Source": "Quantity",
            "WidthPercentage": 15,
            "Align": "Center",
            "Order": 2
          },
          {
            "Type": "Text",
            "Source": "Price",
            "Format": "Currency",
            "WidthPercentage": 35,
            "Align": "Right",
            "Order": 3
          }
        ]
      },
      {
        "Name": "Footer",
        "Type": "Static",
        "Order": 3,
        "Elements": [
          {
            "Type": "Text",
            "Label": "Total: ",
            "Source": "Total",
            "Format": "Bold,Large",
            "Align": "Right",
            "Order": 1
          },
          {
            "Type": "QR",
            "Source": "InvoiceUrl",
            "Size": 6,
            "Align": "Center",
            "Order": 2
          }
        ]
      }
    ],
    "GlobalStyles": {
      "FontFamily": "Arial",
      "FontSize": "12"
    }
  }
}

​
Request Fields

​
Action
string
required
Must be UpdateTemplate to update or create a template.
​
Template
object
required
The complete template configuration.

​
Template Update Result

After processing a template update, APM sends a result message back to the requesting client.

​
Message Format

​
Success

{
  "Action": "TemplateUpdateResult",
  "DocumentType": "ticket_venta",
  "Success": true,
  "Message": "Plantilla 'ticket_venta' actualizada exitosamente en Windows."
}

​
Error

{
  "Action": "TemplateUpdateResult",
  "DocumentType": "ticket_venta",
  "Success": false,
  "Message": "Error en Windows: Invalid template structure"
}

​
Response Fields

​
Action
string
Always TemplateUpdateResult for template update responses.
​
DocumentType
string
The document type that was updated.
​
Success
boolean
true if the template was saved successfully, false otherwise.
​
Message
string
Descriptive message about the result.

​
Example: Complete Template Update Flow

const ws = new WebSocket('ws://localhost:7000/websocket/');

ws.onopen = () => {
  // Create a simple receipt template
  const templateUpdate = {
    Action: 'UpdateTemplate',
    Template: {
      TemplateId: 'receipt_simple',
      Name: 'Simple Receipt',
      DocumentType: 'ticket_venta',
      Sections: [
        {
          Name: 'Header',
          Type: 'Static',
          Order: 1,
          Elements: [
            {
              Type: 'Text',
              StaticValue: 'RECEIPT',
              Format: 'Bold,Large',
              Align: 'Center',
              Order: 1
            }
          ]
        },
        {
          Name: 'Items',
          Type: 'Table',
          DataSource: 'Items',
          Order: 2,
          Elements: [
            {
              Type: 'Text',
              Source: 'Name',
              WidthPercentage: 60,
              Order: 1
            },
            {
              Type: 'Text',
              Source: 'Total',
              WidthPercentage: 40,
              Align: 'Right',
              Order: 2
            }
          ]
        },
        {
          Name: 'Total',
          Type: 'Static',
          Order: 3,
          Elements: [
            {
              Type: 'Text',
              Label: 'TOTAL: ',
              Source: 'Total',
              Format: 'Bold,Large',
              Align: 'Right',
              Order: 1
            }
          ]
        }
      ],
      GlobalStyles: {}
    }
  };
  
  ws.send(JSON.stringify(templateUpdate));
};

ws.onmessage = (event) => {
  const result = JSON.parse(event.data);
  
  // Check if this is a template update result
  if (result.Action === 'TemplateUpdateResult') {
    if (result.Success) {
      console.log(`Template updated: ${result.Message}`);
      // Now you can use this template for printing
    } else {
      console.error(`Template update failed: ${result.Message}`);
    }
  }
};

​
Section Types

​
Static

Prints fixed content or single values from the document. 
{
  "Name": "Header",
  "Type": "Static",
  "Elements": [
    { "Type": "Text", "StaticValue": "Company Name" },
    { "Type": "Text", "Source": "InvoiceNumber" }
  ]
}

​
Table

Iterates over a collection and prints rows. 
{
  "Name": "Items",
  "Type": "Table",
  "DataSource": "Items",
  "Elements": [
    { "Type": "Text", "Source": "Name", "WidthPercentage": 50 },
    { "Type": "Text", "Source": "Price", "WidthPercentage": 50 }
  ]
}

​
Repeated

Repeats a block of elements for each item in a collection. 
{
  "Name": "Promotions",
  "Type": "Repeated",
  "DataSource": "Promotions",
  "Elements": [
    { "Type": "Text", "Source": "Title", "Format": "Bold" },
    { "Type": "Text", "Source": "Description" }
  ]
}

​
Element Types

TypeDescriptionCommon Properties
TextText contentSource, StaticValue, Label, Format, Align
Barcode1D barcodeSource, BarWidth, Height
QRQR codeSource, Size, Align
ImageImage (from document data)Source, Height
LineSeparator lineFormat

​
Format Options

Multiple format options can be combined with commas:
  • Bold - Bold text
  • Large - Large font size
  • Italic - Italic text
  • Currency - Format as currency
  • Underline - Underlined text
Example: "Format": "Bold,Large"

​
Best Practices

  1. Test Templates Locally First: Create and test templates in the APM configuration before deploying remotely
  2. Use Descriptive Names: Give templates and sections clear, descriptive names
  3. Order Matters: Use the Order property to control the sequence of sections and elements
  4. Width Percentages: For table columns, ensure width percentages add up to approximately 100%
  5. Data Source Paths: Use dot notation for nested properties (e.g., "Customer.Name")

​
Troubleshooting

​
Template Not Found When Printing

Ensure the DocumentType in your template exactly matches the DocumentType in your print requests.

​
Template Update Failed

  • Verify JSON structure is valid
  • Check that required fields are present
  • Ensure element types are valid
  • Review error message in the result

​
Template Renders Incorrectly

  • Verify data source paths match your document structure
  • Check width percentages for table columns
  • Ensure format and align values are valid

​
Source Reference

  • Template model: source/Core/Models/PrintTemplate.cs:8
  • Update request model: source/Core/Models/UpdateTemplateRequest.cs:8
  • Update result model: source/Core/Models/TemplateUpdateResult.cs:6
  • WebSocket handler: source/Infraestructure/Services/WebSocketServerService.cs:463
  • Event handler: source/WorkerService/Worker.cs:37

Build docs developers (and LLMs) love

Get started for freeTalk to us