Skip to main content

Hello World

In this tutorial you will create a minimal Aptean Mesh service — a single AL codeunit that receives an RPC call from the mobile client and returns a JSON page with "Hello from Aptean Mesh!" on screen. By the end, you will have a working end-to-end example that you can build on.

How It Works​

The Aptean Mesh architecture has three moving parts:

  1. JSON page definition — a JSON file that describes the UI (stored as a BC Mobile Page record)
  2. Service codeunit — an AL codeunit that implements IBCRPC220FDW and handles RPC methods
  3. Service registration — an event subscriber that tells the RPC registry which codeunit handles which service

The mobile client fetches the JSON page definitions on startup, renders them, and calls your service codeunit whenever the user interacts with a page that has a service binding.

Step 1: Create the Page JSON​

Create the file resources/mobilepage/hello-world.json in your project:

{
  "pageId": "HELLO-WORLD",
  "service": "HELLO",
  "header": {
    "title": "Hello World"
  },
  "contract": {
    "initialAction": "init"
  },
  "body": [
    {
      "type": "text",
      "valueKey": "greeting",
      "style": "HEADER"
    }
  ]
}

Key fields:

FieldDescription
pageIdUnique identifier for this page within your App Bundle
serviceThe service code that links this page to a service codeunit (registered in the Mobile Service Registry)
header.titleThe title displayed in the page header
contract.initialActionReferences an action ID to call when the page first loads. Here it triggers the init action which calls Initialize on the service.
bodyArray of UI components to render. The text component uses valueKey to bind to the greeting field from the service response.

Notice that the text component does not contain a hardcoded string. Instead, valueKey: "greeting" tells the client to look up the greeting key in the service response and display its value. This is the core of Aptean Mesh data binding — the server provides the data, and the JSON page defines where to display it.

Step 2: Create the Service Codeunit​

Create src/Services/HelloWorldService.Codeunit.al:

namespace MyCompany.MeshDemo;
using Aptean.Mesh.SDUI;

codeunit 50100 HelloWorldService implements IBCRPC220FDW
{
    [EventSubscriber(ObjectType::Codeunit, Codeunit::MobileRPCRegistry220FDW, OnResolveService, '', false, false)]
    local procedure ResolveHelloWorldService(CodeunitId: Integer; var Service: Interface IBCRPC220FDW; var IsServiceResolved: Boolean)
    begin
        if IsServiceResolved then
            exit;

        if CodeunitId = Codeunit::HelloWorldService then begin
            Service := this;
            IsServiceResolved := true;
        end;
    end;

    procedure RPC(var State: Codeunit MobileRPCState220FDW) ResponseJson: JsonObject
    begin
        case State.Method() of
            'Initialize':
                exit(Initialize(State));
        end;
    end;

    local procedure Initialize(var State: Codeunit MobileRPCState220FDW) Result: JsonObject
    var
        GreetingLbl: Label 'greeting', Locked = true;
    begin
        Result.Add(GreetingLbl, 'Hello from Aptean Mesh!');
    end;
}

What This Code Does​

  1. implements IBCRPC220FDW — The codeunit declares that it implements the Aptean Mesh RPC interface. This interface has a single method: RPC(var State: Codeunit MobileRPCState220FDW) ResponseJson: JsonObject.

  2. ResolveHelloWorldService (event subscriber) — Subscribes to the OnResolveService event on MobileRPCRegistry220FDW. The pattern is always the same: check IsServiceResolved (to avoid overriding another handler), compare CodeunitId, set Service := this, and set IsServiceResolved := true.

  3. RPC procedure — Routes incoming method calls by name. The mobile client sends a JSON-RPC request with a method field (e.g., "Initialize"), which you read via State.Method().

  4. Initialize procedure — Returns a JSON object with a greeting key. The mobile client receives this response and binds it to the page.

Step 3: Publish the Extension​

  1. Press F5 (or run AL: Publish) to compile and deploy your extension to the sandbox
  2. If there are errors, check that your symbols are downloaded and that the dependency in app.json is correct

Step 4: Configure BC Records​

Create an App Bundle​

  1. Search for Mobile App Bundles and open the list
  2. Create a new bundle — Code: DEMO, Description: Demo Bundle
  3. Leave it in Development status for now

Add a Mobile Page​

  1. From the App Bundle card, open Mobile Pages
  2. Create a new record with Page ID = HELLO-WORLD and Service = HELLO
  3. Paste the JSON from Step 1 into the Page Json field

Set the Root Page​

On the App Bundle card, set Root Page ID to HELLO-WORLD.

Register the Service​

  1. Search for Mobile Service Registry and open it
  2. Create a new record: App Bundle ID = your bundle, Mobile Service Code = HELLO, Codeunit Id = 50100

Assign the Bundle to Your User​

On the App Bundle card, open User Assignments and add your BC user.

Step 5: Test on the Mobile Client​

  1. Open the Aptean Mesh Client app on your Android device or emulator
  2. Connect to your BC environment (see Connecting the Client)
  3. Sign in — the app will fetch the page flow and render your "HELLO-WORLD" page
  4. You should see "Hello from Aptean Mesh!" displayed on screen

What's Next​