Wiki macro SDK

Upload Wiki document resources and update macro static content from your app backend for public sharing, mobile, search and exports.

Requirements

ONES	@ones-open/node-sdk
7.45.0+	0.0.20+

Declare a Wiki custom macro and install and enable the app. Run the SDK on your app's Node.js backend using stored installation callback data.

Public interfaces

import { wiki } from '@ones-open/node-sdk'
import type { InstallationInfo, WikiMacroContext } from '@ones-open/node-sdk'

async function publishSummary(
  installationInfo: InstallationInfo,
  context: WikiMacroContext,
  summary: string,
) {
  try {
    const macro = wiki.macro(installationInfo).instance(context)
    await macro.saveExportSpec([{ type: 'text', data: summary }], [])
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error)
    console.error('Static content update failed:', message)
    throw error
  }
}

Interface	Purpose	Return value
wiki.macro(installationInfo)	Create a client for the installation	WikiMacroClient
client.instance(context)	Bind an existing macro instance	WikiMacroInstance
macro.uploadResource(file)	Upload a resource to the macro's document	Promise<string>
macro.saveExportSpec(exportSpec, resources)	Replace complete static content and resource references	Promise<void>

See Macro types for fields. None of these interfaces accepts a callback. Client creation and binding are synchronous; uploading and updating return Promises.

Where the data comes from

1. Store InstallationInfo from the app installation callback on the backend.
2. Read macro location with ONES.getExtensionContext in the render entry and send the associated context to your backend. Validate business permissions, installation ownership and the target record before retaining the association.
3. After business data is saved, generate static content for each associated macro and call saveExportSpec. Update each instance separately if several macros reference the same record.

Keep installation credentials on the backend. Context identifies an existing macro; it neither creates a macro nor grants business permissions to the user invoking an operation.

Relationship to Wiki page editing

saveExportSpec does not change customData, require a configuration edit session or create a page version. After success, refresh sharing or mobile pages or export again to see updates. Search uses updated static text; existing exported files remain unchanged.

Business data and static content do not synchronize automatically. If business persistence succeeds but static publication fails, retry only static publication. Cancelling a concurrent macro configuration edit can still restore pre-session static content; decide when to synchronize again according to your business logic.

To save document configuration, use Web SDK saveData in the macro edit entry.