13.1 Entity Descriptors🔗

• name — The BC entity name (e.g., "customers", "salesOrders")

• publisher — #f for standard API, or the publisher name for custom APIs

• group — #f for standard API, or the API group for custom APIs

• version — #f for standard API, or the version for custom APIs

Standard entity modules export bc-entity values for each entity (e.g., customers, vendors, items). Use these with inspect, peek, and sample for schema and data exploration.

13.2 Schema Inspection🔗

Uses the text-table library for formatted table output.

Requires authentication. Fetches metadata on first use (then cached).

(require bcnav bcnav/api/master-data)

;; ... authentication ...

(inspect customers)

Produces something like:

Useful for copying into a module as inline documentation.

(displayln (inspect->comment customers))

Generates "@" subsection and "@" tabular forms that can be pasted into a ".scrbl" file.

(displayln (inspect->scribble customers))

When target is a bc-entity, fetches from the API (equivalent to calling the entity’s list function with #:top n).

When target is a bc-result, extracts the first n records from the existing result without making an API call.

Requires authentication when fetching from an entity.

(sample customers)      ;; fetch first 5 from API

(sample customers 10)   ;; fetch first 10 from API

;; Extract from an existing result

(define all-customers (customers-list))

(sample all-customers 3)  ;; first 3 records, no API call

When target is a bc-entity, fetches from the API. When target is a bc-result, displays records from the existing result.

Ideal for interactive exploration in the REPL. Uses sample internally to get data, then formats it using the text-table library.

Requires authentication when fetching from an entity.

(peek customers)      ;; fetch and display first 5 records

(peek customers 10)   ;; fetch and display first 10 records

;; Display from an existing result

(define result (customers-list))

(peek result 3)       ;; display first 3, no API call

This outputs a nicely formatted table:

13.3 Standard API Metadata🔗

Returns a hash table mapping entity names (as symbols) to entity-info structs.

The result is cached in current-bc-metadata-cache. Subsequent calls return the cached data without making an API request.

Requires authentication.

Calls fetch-metadata internally (using cached data if available).

(define info (entity-schema 'customer))

(entity-info-properties info)

13.4 Custom API Metadata🔗

Returns a hash table mapping entity names to entity-info structs.

Custom API metadata is cached separately from standard API metadata, keyed by the combination of publisher, group, and version.

13.5 Schema Data Structures🔗

• name — The entity name as a symbol

• key-properties — Property names that form the entity’s primary key (usually just '(id))

• properties — List of all properties (fields)

• navigation-properties — List of expandable relationships

• name — The property name as used in API requests/responses

• type — The OData/EDM type (e.g., "Edm.String", "Edm.Guid")

• nullable? — Whether the property can be null/empty

• name — The property name to use with #:expand

• target-type — The type of the related entity

• multiplicity — 'one for single related record, 'many for a collection

13.6 Enum Support🔗

Business Central uses enum types for fields with a fixed set of allowed values. These types have names like Microsoft.NAV.assemblyPolicy and are returned as encoded strings in API responses.

Each value is a pair of (numeric-value . decoded-name).

(enum-values items 'assemblyPolicy)

;; => ’((0 . "Assemble-to-Stock") (1 . "Assemble-to-Order"))

Use the numeric value in filters for cleaner queries:

(items-list #:query (make-query #:filter (eq 'assemblyPolicy 0)))

Special characters are converted to _xNNNN_ format where NNNN is the hex Unicode code point.

(bc-encode-enum "Assemble-to-Stock")

;; => "Assemble_x002D_to_x002D_Stock"

Converts _xNNNN_ patterns back to their original characters.

(bc-decode-enum "Assemble_x002D_to_x002D_Stock")

;; => "Assemble-to-Stock"

• name — Local name as a symbol (e.g., 'assemblyPolicy)

• full-name — Fully qualified name (e.g., "Microsoft.NAV.assemblyPolicy")

• members — List of allowed values, sorted by numeric value

• value — The numeric value (use this in filters)

• name — The API-encoded name (e.g., "Assemble_x002D_to_x002D_Stock")

• decoded-name — Human-readable name (e.g., "Assemble-to-Stock")

13.7 Cache Management🔗

Call this if you need to refresh metadata after BC schema changes (e.g., after installing extensions or updating BC).