Table of Contents

How to customize Publication with an integration

This article describes two ways to use publication to send data to a third-party system:

  • Generate the complete payload (unstructurred data like JSON, XML, etc.) in a custom implementation and send it through the publication queue.
  • Let the publication implementation populate the structured publication-line fields, as the Pimics API implementation does, and use a public implementation codeunit.

Publication Interface

Pimics has interface "PIMX Publication Update Line c7", which is used by Publication to generate data in the format expected by a channel.

When you want to prepare data for another solution, use this interface and select the integration approach that matches the target system.

Important

Define a separate enum option and a separate interface implementation for every custom synchronization. Do not change the shared API implementation (or other) to add channel-specific behavior. The standard implementations can change over time to support their own channels, and keeping custom logic in a dedicated implementation prevents changes for one channel from affecting another integration.

Step 1: Implement the integration

Option 1 — Generate and queue the complete payload

Use this option when the target system expects a payload that is not represented by the standard publication-line fields. The custom implementation reads the cached publication data, creates the target payload, and inserts the message into the publication queue.

TODO
  • [ ] Create a codeunit CustomPublicationUpdate.Codeunit.al
  • [ ] Implement the "PIMX Publication Update Line c7" interface
  • [ ] Use Data parameter to retrieve publication data (items, categories, etc.)
  • [ ] Generate the target payload (JSON, XML, etc.)
  • [ ] Insert the message into the publication queue using QueueHelper.InsertMessage()
  • [ ] Set the HTTP method (POST, PATCH, PUT) and target URL
  • [ ] Return true if successful, false if the update fails

Example:

HIDDEN

interface "PIMX Publication Update Line c7" has about 20 procedures (Init, UpdateItem, UpdateVariant, UpdateCatalogItem, UpdateItemGroup, UpdateProductGroup, UpdateChapter, UpdateCatalogGroup, UpdateDocument, UpdateDocumentLine, UpdateFeature, UpdateKeyword, UpdateText, UpdateCrossReference, UpdateContent, UpdateContentHeader, BeforeModifyExistingLine, BeforeInsertNewLine, ReferenceIsValid, PublicationGroupIsDone, ProductIsDone, ProductDataIsDone, CreateCustomData, UpdateCustomData, DeleteLine). Your codeunit must implement all of them, not only the ones relevant to your channel. Start from codeunit PIMX Publ. Update Empty (a no-op implementation where every procedure simply returns true) and copy/paste it as your template, then override only the procedures you need.

codeunit 50100 "PIMX Custom Publ. Update" implements "PIMX Publication Update Line c7"
{
    Access = Internal;
    
    var
        QueueHelper: Codeunit "PIMX Publication Queue Helper";
        TargetUrl: Label 'https://api.customsystem.com/products';

    procedure Init()
    begin
    end;

    procedure UpdateItem(var _line: Record "PIMX Publication Line"; AllocationLine: Record "PIMX Allocation Line"; Data: Codeunit "PIMX Publication Data"): Boolean
    var
        _Item: Record Item;
        JsonPayload: Text;
        IsNew: Boolean;
    begin
        // Step 1: Retrieve item data from the publication cache
        if not Data.GetItem(_Item, _line.Nummer) then
            exit(false);
        
        // Step 2: Create JSON payload for your target system
        JsonPayload := BuildItemJsonPayload(_Item);
        
        // Step 3: Check if this is new data or an update
        IsNew := (_line.GetData() <> JsonPayload);
        
        // Step 4: Save or send based on your integration approach
        if IsNew then begin            
            // Just store the JSON in the publication line for caching
            _line.SetData(JsonPayload);

            // For systems that send immediately (e.g., Shopify, REST APIs)
            QueueHelper.InsertMessage(
                Enum::"PIMX API Method"::Post,
                TargetUrl,
                JsonPayload
            );
        end;
        
        exit(true);
    end;

    local procedure BuildItemJsonPayload(_Item: Record Item): Text
    var
        JsonObject: JsonObject;
        JsonText: Text;
    begin
        JsonObject.Add('id', _Item."No.");
        JsonObject.Add('name', _Item.Description);
        JsonObject.Add('description', _Item."Description 2");
        JsonObject.Add('sku', _Item."No.");
        
        JsonObject.WriteTo(JsonText);
        exit(JsonText);
    end;

    // All other interface procedures (UpdateVariant, UpdateItemGroup, UpdateProductGroup,
    // UpdateChapter, UpdateCatalogGroup, UpdateCatalogItem, UpdateDocument, UpdateDocumentLine,
    // UpdateFeature, UpdateKeyword, UpdateText, UpdateCrossReference, UpdateContent,
    // UpdateContentHeader, BeforeModifyExistingLine, BeforeInsertNewLine, ReferenceIsValid,
    // PublicationGroupIsDone, ProductIsDone, ProductDataIsDone, CreateCustomData,
    // UpdateCustomData, DeleteLine) must also be implemented
}

Option 2 — Populate structured publication data

Use this option when the target system can consume the structured data stored in publication-line fields, similar to the Pimics API. In this approach, the publication process handles the line structure and your implementation focuses on mapping the available publication data to the fields.

TODO
  • [ ] Create a codeunit CustomPublicationAPIUpdate.Codeunit.al
  • [ ] Implement the "PIMX Publication Update Line c7" interface (all procedures — see the note under Option 1)
  • [ ] Call the public API implementation (e.g., "PIMX Publ. Update API Impl.") to populate standard fields
  • [ ] Apply custom transformations or field mappings (e.g., rename fields, concatenate values, add prefix/suffix)
  • [ ] Return true if the update succeeds, false if it fails
  • [ ] Register the implementation in the enum value you created in Step 1
HIDDEN

"PIMX Publ. Update API Impl." (codeunit 70113905) is the shared, Access = Public codeunit that contains the actual data-mapping logic (UpdateItemSingle, UpdateItemGroupSingle, etc.) used by the API, API Translation, and Multilanguage API channels. If you only need to reuse one of those three channels as-is (without transformations), you can instead call the public wrapper "PIMX Publ. Update Public API" (codeunit 70113901), which implements the full interface for you — call Init(Enum::"PIMX Publ. Update Impl."::API) and delegate every interface procedure to it.

Example:

codeunit 50102 "PIMX Custom API Update" implements "PIMX Publication Update Line c7"
{
    Access = Internal;
    
    var
        ApiImpl: Codeunit "PIMX Publ. Update API Impl.";

    procedure Init()
    begin
    end;

    procedure UpdateItem(var _line: Record "PIMX Publication Line"; AllocationLine: Record "PIMX Allocation Line"; Data: Codeunit "PIMX Publication Data"): Boolean
    begin
        // Use the standard API implementation to populate publication-line fields
        if not ApiImpl.UpdateItemSingle(_line, AllocationLine, Data) then
            exit(false);
        
        // Apply custom transformations
        _line.Beschreibung := CopyStr(
            StrSubstNo('[CUSTOM] %1', _line.Beschreibung),
            1,
            MaxStrLen(_line.Beschreibung)
        );
        
        exit(true);
    end;

    // All other interface procedures must also be implemented (see the note under Option 1),
    // typically by delegating to the matching ...Single() method on ApiImpl, e.g.:
    // procedure UpdateItemGroup(...): Boolean
    // begin
    //     exit(ApiImpl.UpdateItemGroupSingle(_line, AllocationLine, Data));
    // end;
}

Step 2: Extend the publication data type enum

Add a new enum value to enum 70113732 "PIMX Publication Data Type" in the file PublicationDataType.Enum.al.

TODO
  • [ ] Open PublicationDataType.Enum.al
  • [ ] Add a new value with a unique ID (use 5xxx for custom integrations)
  • [ ] Set the Caption to describe your channel (e.g. "Custom API", "Third-party System")
  • [ ] Create a new codeunit that implements "PIMX Publication Update Line c7"
  • [ ] Link the implementation in the enum value

Example:

value(5100; "Custom System")
{
    Caption = 'Custom System';
    Implementation = "PIMX Publication Update Line c7" = "PIMX Custom Publ. Update";
}

Step 3: Send to API - only for Option 1 and Pimics is activ part

3.1 Set up the publication queue and job

After the integration codeunit generates the payload and inserts it into the publication queue, a background job must send the messages.

  1. Select Search (Alt+Q), enter Job Queue Entries, and choose the related link.
  2. Create a new job queue entry.
  3. Set Object Type to Codeunit and Object ID to Run to 70113798 ("PIMX Job Send Publ. Queue").
  4. Configure the Recurrence pattern (e.g., every 5 minutes) to control how often messages are sent.
  5. Set the start date and time for when the job should begin.
  6. Mark the entry as Status = Ready to activate the job.
  7. Save the entry.
  8. Verify the job runs by opening the Publication Queue page and checking that messages are processed and their status changes to Processed or Error.

3.2 Configure authentication or implement a custom API client

You usually do not need to implement interface "PIMX API Client". Use the Default implementation and configure the authentication record that the target domain uses. The publication queue client then creates the HTTP request, applies the configured authentication, sends the request, and updates the queue status.

Note

The API client type (enum "PIMX API Type", values Empty, Default, Shopify) is not selected on a setup page. It is set in code by calling QueueHelper.SetType(...) on "PIMX Publication Queue Helper" before InsertMessage() is called (or defaults to Empty/Default behavior when not set). Only the authentication record and target domain are configured through the UI.

Use the following options to decide whether you need a custom implementation:

API client option Use when Implementation
Default Your target system uses the standard HTTP request and authentication handling. This is the recommended option for most custom integrations. PIMX API Client Default
Shopify You publish to Shopify and need Shopify-specific request handling, authentication, and payload adjustments. PIMX API Client Shopify
Custom API client Your target system requires request processing that the default client does not support, such as custom headers, a special request format, or a different response workflow. Your codeunit that implements PIMX API Client

Configure a standard authentication record

Create an authentication record and assign it to the target domain. The available authentication types are:

Authentication type Use when Implementation
Basic The target endpoint requires a user name and password. PIMX Basic Authnetication
OAuth 2.0 The target endpoint uses OAuth 2.0 client credentials. PIMX OAuth2 Token
SharePoint on-line The target endpoint is SharePoint Online. PIMX SharePoint Authnetication
Access Key The target integration uses an access key. No standard implementation; provide an integration-specific implementation if required.
Shopify The target endpoint uses Shopify authentication. No standard authentication-token implementation; Shopify authentication is handled by PIMX API Client Shopify.
Shopify OAuth 2.0 The target endpoint uses Shopify OAuth 2.0 authentication. No standard implementation; provide an integration-specific implementation if required.
  1. Select Search (Alt+Q), enter Authentication, and choose the related link.
  2. Create an authentication record and enter a unique Code.
  3. Select the required Type, then enter the credentials or token settings required by that type.
  4. Select Search (Alt+Q), enter Domains, and choose the related link.
  5. Open the domain used by the publication channel and set Default Authentication to the authentication record.
  6. Open Publication Channels, select the channel, and set Target Domain to this domain.

Step 4: Define the channel in the UI

After you've registered your enum value and created the implementation codeunit, define the channel in the Publication Channel setup.

  1. Select Search (Alt+Q), enter Publication Channels, and choose the related link.
  2. Select New to create a channel record.
  3. Enter a descriptive Code (e.g., CUSTOM_API, THIRD_PARTY).
  4. Set the Publication Type to your custom enum value (e.g., "Custom System").
  5. Enter an optional Description to document the channel's purpose and target system.
  6. Configure channel-specific settings if needed:
    • Set Target Domain if your system requires domain configuration
    • Set Default Authentication if the channel requires credentials
    • Configure channel-specific rules or allocations
  7. Select Save to create the channel.
  8. Now you can assign this channel to publication headers and items as described in Channels.

For more information on how channels work and how to assign them, see Channels.

Available public implementation codeunits

When implementing Option 2, you can call these public codeunits to reuse standard channel logic:

Implementation Codeunit ID Purpose
Multilanguage Print Impl. 70113906 Publishes data for multilanguage print output via InDesign
API Impl. 70113905 Publishes data using the standard API structure (used by API, API Translation, and Multilanguage API channels)
Shopify Impl. 70113907 Publishes product data to Shopify
Sana Commerce Internal Prepare data for Sana Commerce integration

These are the Access = Public codeunits with the reusable mapping logic. To reuse a whole channel unchanged (rather than calling the mapping logic directly), use the corresponding public wrapper instead, which already implements the full "PIMX Publication Update Line c7" interface:

Public wrapper Codeunit ID Wraps
PIMX Publ. Update Public API 70113901 API, API Translation, and Multilanguage API (select via Init(Enum "PIMX Publ. Update Impl."::API / "API Translation" / "API Multilang."))
PIMX Publ. Upd. MLPrint Public 70113904 Multilanguage Print
PIMX Shpfy Publ. Update Public 70113902 Shopify

The publication integration also uses interfaces "PIMX API Client" and "PIMX Authentication Token" for secure communication with external systems. Their implementations are internal and selected by the publication configuration.