On this page

Scripting

The ctx reference

Normal and Integration scripts reach CoCoCo through the global ctx. Functions that wait on something, such as a query or a device, return ok, result: check ok before you use the result (see Calling CoCoCo). Each entry shows which kinds of script can use it.

ctx.api

ctx.api.client

  • Integration
ctx.api.client(name: string) -> ok, result: any

Returns the integration's ready client for an API client that declares a setup: the setup runs once, the first time the running instance needs the client, and later calls reuse the client it returned. Fails with a message when the client has no setup or its setup failed; a failed setup runs again on the next call.

ctx.cache

ctx.cache.delete

  • Normal
  • Integration
ctx.cache.delete(key: string) -> ok, result: nil

Deletes a cache value: your account's cache, or in an integration the instance's.

ctx.cache.get

  • Normal
  • Integration
ctx.cache.get(key: string) -> ok, result: any

Reads a cache value: your account's cache, or in an integration the instance's.

ctx.cache.set

  • Normal
  • Integration
ctx.cache.set(input: { key: string, ttl: number | nil, value: any })
  -> ok, result: nil

Writes a cache value (single-table input): your account's cache, or in an integration the instance's. ttl is in seconds (default 3600, capped at 604800 = 7 days); the encoded value is limited to 4 KB.

ctx.config

ctx.config.get

  • Normal
  • Integration
ctx.config.get(key?: string, default?: any) -> ok, result: any

Reads a config value, with an optional default: your account's config, or in an integration the instance's install-time config. With no key, returns the whole config table.

ctx.dataContainer

ctx.dataContainer.delete

  • Normal
  • Integration
ctx.dataContainer.delete(name: string, schemaName?: string)
  -> ok, result: nil

The older name for ctx.store.delete, which works the same way.

ctx.dataContainer.get

  • Normal
  • Integration
ctx.dataContainer.get(name: string, schemaName?: string)
  -> ok, result: {
    createdAt: string | nil,
    data: any,
    name: string,
    schemaName: string | nil,
    updatedAt: string | nil
  } | nil

The older name for ctx.store.get, which works the same way.

ctx.dataContainer.list

  • Normal
  • Integration
ctx.dataContainer.list(
  schemaName?: string,
  opts?: { limit: number | nil, offset: number | nil }
)
  -> ok, result: {
    createdAt: string | nil,
    data: any,
    name: string,
    schemaName: string | nil,
    updatedAt: string | nil
  }[]

The older name for ctx.store.list, which works the same way.

ctx.dataContainer.put

  • Normal
  • Integration
ctx.dataContainer.put(name: string, data: any, schemaName?: string)
  -> ok, result: {
    createdAt: string | nil,
    data: any,
    name: string,
    schemaName: string | nil,
    updatedAt: string | nil
  }

The older name for ctx.store.put, which works the same way.

ctx.dataContainer.query

  • Normal
  • Integration
ctx.dataContainer.query(
  query: {
    schemaName: string | nil,
    taggableId: string | nil,
    taggableType: string | nil
  }
)
  -> ok, result: {
    createdAt: string | nil,
    data: any,
    name: string,
    schemaName: string | nil,
    updatedAt: string | nil
  }[]

The older name for ctx.store.query, which works the same way.

ctx.device

ctx.device.forWorkcenter

  • Normal
ctx.device.forWorkcenter(workCenterId: string) -> WorkCenterDevice

The device assigned to this work center.

ctx.device.get

  • Normal
  • Integration
ctx.device.get(idOrName: string) -> Device

The device with this id or name. In an integration, the id of one of the resources its manifest binds.

ctx.device.http

  • Normal
  • Integration
ctx.device.http(
  idOrName: string,
  request: {
    auth: {
      basic: { password: string, username: string } | nil,
      bearer: string | nil
    } | nil,
    body: string | nil,
    headers: { [key: string]: string } | nil,
    method: string | nil,
    path: string | nil,
    query: { [key: string]: any } | nil,
    timeoutMs: number | nil,
    url: string | nil
  }
)
  -> ok, result: {
    body: string | nil,
    headers: { [key: string]: string },
    status: number
  }

Sandboxed HTTP request through a device connection. The request body must be a string (json.encode a table first); the response body is the raw string, never decoded (json.decode it).

ctx.device.sql

  • Normal
  • Integration
ctx.device.sql(
  idOrName: string,
  request: { bindings: any[] | nil, query: string }
)
  -> ok, result: {
    columns: string[],
    executionTimeMs: number | nil,
    rows: any[][],
    rowsAffected: number | nil
  }

Sandboxed SQL through a device connection. Edge transport envelopes, including SQL results, are limited to 16 MiB (16,777,216 bytes, including protocol overhead). Select only needed columns and page large result sets.

Device

A device, reached through its connection. Returned by ctx.device.get, with these methods:

device:http

  • Normal
  • Integration
device:http(
  request: {
    auth: {
      basic: { password: string, username: string } | nil,
      bearer: string | nil
    } | nil,
    body: string | nil,
    headers: { [key: string]: string } | nil,
    method: string | nil,
    path: string | nil,
    query: { [key: string]: any } | nil,
    timeoutMs: number | nil,
    url: string | nil
  }
)
  -> ok, result: {
    body: string | nil,
    headers: { [key: string]: string },
    status: number
  }

Sends an HTTP request through the device's connection; path is relative to its base URL.

device:id

  • Normal
  • Integration
device:id() -> ok, result: string

The device's id.

device:jmf

  • Normal
  • Integration
device:jmf(message: string, path?: string)
  -> ok, result: {
    body: any,
    headers: { [key: string]: string },
    status: number
  }

Posts a JMF message (built with ctx.jmf.build) to the device; path defaults to /.

device:jmfReceiver

  • Normal
  • Integration
device:jmfReceiver() -> ok, result: JMFReceiver

Returns (ok, receiver) with the JMF destination and optional auth for this device. Resolves through its network controller, otherwise platform JMF. Failure returns (false, reason); never falls back from a configured controller. Treat receiver.auth as credentials and do not log it.

device:sql

  • Normal
  • Integration
device:sql(request: { bindings: any[] | nil, query: string })
  -> ok, result: {
    columns: string[],
    executionTimeMs: number | nil,
    rows: any[][],
    rowsAffected: number | nil
  }

Runs a SQL query through the device's database connection; cells come back as plain values, SQL NULL as nil. Edge envelopes, including SQL results, are limited to 16 MiB (16,777,216 bytes, including protocol overhead); select needed columns and page large result sets.

WorkCenterDevice

The device assigned to a work center. Returned by ctx.device.forWorkcenter, with these methods:

device:http

  • Normal
device:http(
  request: {
    auth: {
      basic: { password: string, username: string } | nil,
      bearer: string | nil
    } | nil,
    body: string | nil,
    headers: { [key: string]: string } | nil,
    method: string | nil,
    path: string | nil,
    query: { [key: string]: any } | nil,
    timeoutMs: number | nil,
    url: string | nil
  }
)
  -> ok, result: {
    body: string | nil,
    headers: { [key: string]: string },
    status: number
  }

Sends an HTTP request through the device's connection; path is relative to its base URL.

device:id

  • Normal
device:id() -> ok, result: string

The device's id.

device:jmf

  • Normal
device:jmf(message: string, path?: string)
  -> ok, result: {
    body: any,
    headers: { [key: string]: string },
    status: number
  }

Posts a JMF message (built with ctx.jmf.build) to the device; path defaults to /.

device:jmfReceiver

  • Normal
device:jmfReceiver() -> ok, result: JMFReceiver

Returns (ok, receiver) with the JMF destination and optional auth for this device. Resolves through its network controller, otherwise platform JMF. Failure returns (false, reason); never falls back from a configured controller. Treat receiver.auth as credentials and do not log it.

device:sql

  • Normal
device:sql(request: { bindings: any[] | nil, query: string })
  -> ok, result: {
    columns: string[],
    executionTimeMs: number | nil,
    rows: any[][],
    rowsAffected: number | nil
  }

Runs a SQL query through the device's database connection; cells come back as plain values, SQL NULL as nil. Edge envelopes, including SQL results, are limited to 16 MiB (16,777,216 bytes, including protocol overhead); select needed columns and page large result sets.

ctx.edgeApp

ctx.edgeApp.invoke

  • Normal
  • Integration
ctx.edgeApp.invoke(handle: string, payload?: any) -> ok, result: any

Invokes a deployed edgeApp by handle.

ctx.graph

ctx.graph.impact

  • Normal
  • Integration
ctx.graph.impact(
  entityId: string,
  options?: { direction: string | nil, maxDepth: number | nil }
)
  -> ok, result: {
    depth: number | nil,
    id: string,
    label: string | nil,
    status: string | nil,
    type: string
  }[]

Returns entities reachable up/downstream from a fulfillment entity.

ctx.graph.provenanceImpact

  • Normal
  • Integration
ctx.graph.provenanceImpact(
  entityId: string,
  options?: { direction: string | nil, maxDepth: number | nil }
)
  -> ok, result: {
    depth: number | nil,
    id: string,
    label: string | nil,
    status: string | nil,
    type: string
  }[]

Returns entities reachable up/downstream from a provenance entity, over the structural composite (operational + fulfillment + provenance). Requires provenance:read.

ctx.graph.provenanceTrace

  • Normal
  • Integration
ctx.graph.provenanceTrace(
  entityId: string,
  options?: { direction: string | nil, maxDepth: number | nil }
)
  -> ok, result: {
    edges: { rel: string, source: string, target: string }[],
    nodes: {
      depth: number | nil,
      id: string,
      label: string | nil,
      status: string | nil,
      type: string
    }[]
  }

Returns the cross-layer lineage subgraph (nodes + edges) around a provenance entity, over the structural composite (operational + fulfillment + provenance). Requires provenance:read.

ctx.graph.trace

  • Normal
  • Integration
ctx.graph.trace(
  entityId: string,
  options?: { direction: string | nil, maxDepth: number | nil }
)
  -> ok, result: {
    edges: { rel: string, source: string, target: string }[],
    nodes: {
      depth: number | nil,
      id: string,
      label: string | nil,
      status: string | nil,
      type: string
    }[]
  }

Returns the fulfillment lineage subgraph (nodes + edges) around an entity.

ctx.graph.whatIf

  • Normal
  • Integration
ctx.graph.whatIf(
  seeds: string[],
  extraEdges: {
    rel: string | nil,
    source: string,
    target: string,
    weight: number | nil
  }[],
  options?: { direction: string | nil, maxDepth: number | nil }
)
  -> ok, result: {
    affected: {
      depth: number | nil,
      id: string,
      label: string | nil,
      newlyReachable: boolean,
      status: string | nil,
      type: string
    }[],
    introducesCycle: boolean
  }

First-class hypothetical impact: the delta between the baseline reachable set from seeds and the reachable set with extraEdges unioned in (over the structural composite by default), plus whether the injected edges introduce a cycle. Requires provenance:read.

ctx.graphql

ctx.graphql.mutation

  • Normal
  • Integration
ctx.graphql.mutation(query: string, variables?: { [key: string]: any })
  -> ok, result: {
    data: any | nil,
    errors: { message: string }[] | nil
  }

Runs a GraphQL mutation with the caller's authorization. Returns (ok, result).

ctx.graphql.query

  • Normal
  • Integration
ctx.graphql.query(query: string, variables?: { [key: string]: any })
  -> ok, result: {
    data: any | nil,
    errors: { message: string }[] | nil
  }

Runs a GraphQL operation with the caller's authorization. Validation infers selected result fields and variable types for literal operations and immutable query strings; dynamic documents retain the general result envelope.

ctx.graphql.transaction

  • Normal
  • Integration
ctx.graphql.transaction(
  body: (GraphQLTransaction) => any,
  isolation?: string
)
  -> ok, result: any

Runs a callback in one database transaction. Optional isolation is database_default or serializable; dispatch and fulfillment completion require serializable. Use tx:query and tx:mutation; returns (ok, callbackResult) after commit. Any operation failure rolls back, even if caught. Nested transactions are rejected. The handle expires when the callback ends.

GraphQLTransaction

A borrowed GraphQL transaction, valid only inside its callback.

transaction:mutation

  • Normal
  • Integration
transaction:mutation(query: string, variables?: { [key: string]: any })
  -> ok, result: {
    data: any | nil,
    errors: { message: string }[] | nil
  }

Runs a GraphQL mutation on this transaction. Returns (ok, result); any failure prevents commit.

transaction:query

  • Normal
  • Integration
transaction:query(query: string, variables?: { [key: string]: any })
  -> ok, result: {
    data: any | nil,
    errors: { message: string }[] | nil
  }

Runs a GraphQL query on this transaction. Returns (ok, result); any failure prevents commit.

transaction:rollback

  • Normal
  • Integration
transaction:rollback() -> nil

Permanently requests rollback. Repeated calls are harmless; subsequent queries and mutations fail. The callback may finish normally; transaction returns (false, 'rolled_back') after cleanup.

ctx.integration

ctx.integration.get

  • Normal
ctx.integration.get(idOrName: string) -> IntegrationInstance

An integration instance in your account, by its id or name. Getting it looks nothing up: its methods fail with a message when no instance you can see has that id or name. With a literal name or id, the result is typed with that instance's Actions.

ctx.integration.getBindings

  • Integration
ctx.integration.getBindings() -> ok, result: { [key: string]: string }

The manifest resource bindings of this instance.

ctx.integration.getId

  • Integration
ctx.integration.getId() -> ok, result: string

The integration instance ID.

ctx.integration.getIntegrationId

  • Integration
ctx.integration.getIntegrationId() -> ok, result: string

The integration definition ID.

ctx.integration.getVersion

  • Integration
ctx.integration.getVersion() -> ok, result: string

The installed integration version.

IntegrationInstance

An integration instance in your account, found by its id or name. Returned by ctx.integration.get, with these methods:

instance:getAction

  • Normal
instance:getAction(name: string) -> IntegrationAction

One of the instance's Actions, by name. Getting it looks nothing up: an Action the instance does not declare fails when called. With a literal name, the Action is typed with its own input, configuration and result.

instance:id

  • Normal
instance:id() -> ok, result: string

The instance's id.

instance:name

  • Normal
instance:name() -> ok, result: string

The instance's name.

instance:status

  • Normal
instance:status() -> ok, result: string

The instance's status: ACTIVE, PAUSED, ERROR or UPGRADING.

instance:version

  • Normal
instance:version() -> ok, result: string

The version of the integration the instance runs.

IntegrationAction

An Action of an integration instance. Returned by IntegrationInstance:getAction, with these methods:

action:call

  • Normal
action:call(input: any, config?: any) -> ok, result: any

Runs the Action with this input, and the Action's configuration when it takes one; returns its result. Running an Action needs write access to the instance, and the instance must be active.

ctx.jdf

ctx.jdf.build

  • Normal
  • Integration
ctx.jdf.build(ops: any[]) -> ok, result: string | nil

Renders a JDF build-operation list to JDF XML. Returns (ok, xml) — ok=false with the error message on failure.

ctx.jdf.buildV2

  • Normal
  • Integration
ctx.jdf.buildV2(job: any, options?: any) -> ok, result: any

Builds the opt-in v2 domain description. Result contains ok, xml or diagnostics.

ctx.jdf.checkCombinedV2

  • Normal
  • Integration
ctx.jdf.checkCombinedV2(data: any, query: any) -> ok, result: any

Transport behind lib/jdf/v2 check_combined: checks that each process of a combined node has the resources it requires. Returns (ok, result); result.status is covered, missing or unknown, with one entry per requirement.

ctx.jdf.compareSelectionsV2

  • Normal
  • Integration
ctx.jdf.compareSelectionsV2(resource: any, query: any, version: string)
  -> ok, result: any

Transport behind lib/jdf/v2 compare_selections: compares the effective values of one parsed resource under two partition selections. Returns (ok, result) with the comparison and diagnostics.

ctx.jdf.evaluateCapabilitiesV2

  • Normal
  • Integration
ctx.jdf.evaluateCapabilitiesV2(
  snapshot: any,
  selection: any,
  requirements: any,
  options?: any
)
  -> ok, result: any

Evaluates structured requirements against explicit capability facts; no device I/O.

ctx.jdf.loadTemplate

  • Normal
  • Integration
ctx.jdf.loadTemplate(name: string) -> ok, result: any

Loads a stored JDF template script by name and returns the value that script returns.

ctx.jdf.packageV2

  • Normal
  • Integration
ctx.jdf.packageV2(action: string, request: any) -> ok, result: any

Pure bounded JDF MIME package operations; assets come only from supplied values.

ctx.jdf.parse

  • Normal
  • Integration
ctx.jdf.parse(xml: string, options?: any) -> ok, result: any | nil

Parses JDF XML into a table. Returns (ok, doc) — ok=false with the error message on failure.

ctx.jdf.parseV2

  • Normal
  • Integration
ctx.jdf.parseV2(xml: string, options?: any) -> ok, result: any

Parses JDF to indexed resources and process uses, retaining namespace-aware extension data.

ctx.jdf.resolveResourceV2

  • Normal
  • Integration
ctx.jdf.resolveResourceV2(resource: any, query: any, version: string)
  -> ok, result: any

Transport behind lib/jdf/v2 resolve_resource: resolves the effective, inherited values of one parsed resource for a partition selection. Returns (ok, result) with the matches and diagnostics; it reads parsed data only.

ctx.jmf

ctx.jmf.build

  • Normal
  • Integration
ctx.jmf.build(ops: any[]) -> ok, result: string | nil

Renders a JMF build-operation list to JMF XML. Returns (ok, xml) — ok=false with the error message on failure.

ctx.jmf.buildV2

  • Normal
  • Integration
ctx.jmf.buildV2(envelope: any, options?: any) -> ok, result: any

Builds JMF XML from the opt-in v2 message description. Returns a result with ok and either xml or diagnostics.

ctx.jmf.loadTemplate

  • Normal
  • Integration
ctx.jmf.loadTemplate(name: string) -> ok, result: any

Loads a stored JMF template script by name and returns the value that script returns.

ctx.jmf.parse

  • Normal
  • Integration
ctx.jmf.parse(xml: string, options?: any) -> ok, result: any | nil

Parses JMF XML into a table (kind = jmf or jdf_stub). Returns (ok, doc) — ok=false with the error message on failure.

ctx.jmf.parseV2

  • Normal
  • Integration
ctx.jmf.parseV2(xml: string, options?: any) -> ok, result: any

Parses JMF XML to plain message, payload and status facts without keeping XML nodes. Returns a result with ok and either the parsed message or diagnostics; parsing is not schema validation.

ctx.knowledge

ctx.knowledge.query

  • Normal
  • Integration
ctx.knowledge.query(
  seeds: string[],
  options?: { limit: number | nil, query: string | nil }
)
  -> ok, result: {
    graph: {
      body: string,
      conceptId: string | nil,
      confirmations: number,
      contradicts: string[],
      entityId: string | nil,
      entityType: string | nil,
      id: string,
      provenance: string,
      scope: string,
      score: number
    }[],
    supporting: {
      body: string,
      conceptId: string | nil,
      confirmations: number,
      contradicts: string[],
      entityId: string | nil,
      entityType: string | nil,
      id: string,
      provenance: string,
      scope: string,
      score: number
    }[]
  }

Retrieves your account's knowledge relevant to the given bounded-entity seeds (TypeID strings; graph spread + attached notes, ranked). Optional free-text query biases the spread semantically.

ctx.log

ctx.log.error

  • Normal
  • Integration
ctx.log.error(message: string, attrs?: { [key: string]: any }) -> nil

Logs an ERROR message with optional structured attributes.

ctx.log.info

  • Normal
  • Integration
ctx.log.info(message: string, attrs?: { [key: string]: any }) -> nil

Logs an INFO message with optional structured attributes.

ctx.log.warn

  • Normal
  • Integration
ctx.log.warn(message: string, attrs?: { [key: string]: any }) -> nil

Logs a WARNING message with optional structured attributes.

ctx.ml

ctx.ml.clusterSeries

  • Normal
  • Integration
ctx.ml.clusterSeries(
  series: number[][],
  options?: {
    epsilon: number | nil,
    metric: string | nil,
    minClusterSize: number | nil,
    window: number | nil
  }
)
  -> ok, result: { labels: number[], nClusters: number }

DBSCAN clustering of series by DTW distance (augurs).

ctx.ml.detectChangepoints

  • Normal
  • Integration
ctx.ml.detectChangepoints(
  series: number[],
  options?: { method: string | nil }
)
  -> ok, result: { changepoints: number[] }

Structural-break detection on a univariate series (augurs).

ctx.ml.detectOutliers

  • Normal
  • Integration
ctx.ml.detectOutliers(
  series: number[][],
  options?: { method: string | nil, sensitivity: number | nil }
)
  -> ok, result: { isOutlier: boolean[], outlyingSeries: number[] }

Outlier detection across a group of aligned series (augurs).

ctx.ml.detectSeasonality

  • Normal
  • Integration
ctx.ml.detectSeasonality(series: number[])
  -> ok, result: { periods: number[] }

Periodogram seasonal-period detection on a univariate series (augurs).

ctx.ml.dtwDistance

  • Normal
  • Integration
ctx.ml.dtwDistance(
  a: number[],
  b: number[],
  options?: { metric: string | nil, window: number | nil }
)
  -> ok, result: { distance: number }

Dynamic-time-warping distance between two series (augurs).

ctx.ml.dtwDistanceMatrix

  • Normal
  • Integration
ctx.ml.dtwDistanceMatrix(
  series: number[][],
  options?: { metric: string | nil, window: number | nil }
)
  -> ok, result: { matrix: number[][] }

Pairwise DTW distance matrix over a group of series (augurs).

ctx.ml.get

  • Normal
  • Integration
ctx.ml.get(name: string) -> MLModel

The model with this name.

ctx.ml.interpolate

  • Normal
  • Integration
ctx.ml.interpolate(series: number[]) -> ok, result: { values: number[] }

Linear gap-fill of NaN holes in a series (augurs).

ctx.ml.predict

  • Normal
  • Integration
ctx.ml.predict(modelName: string, featuresJSON: string)
  -> ok, result: {
    confidence: number | nil,
    predictedClass: string | nil,
    prediction: number | nil,
    warnings: string[] | nil
  }

Prediction against a model trained in your account.

ctx.ml.systemPredict

  • Normal
  • Integration
ctx.ml.systemPredict(modelName: string, featuresJSON: string)
  -> ok, result: {
    confidence: number | nil,
    predictedClass: string | nil,
    prediction: number | nil,
    warnings: string[] | nil
  }

Prediction against a system model role.

MLModel

A machine-learning model trained in your account. Returned by ctx.ml.get, with these methods:

model:forecast

  • Normal
  • Integration
model:forecast(horizon: number, level?: number)
  -> ok, result: {
    level: number | nil,
    lower: number[] | nil,
    point: number[],
    upper: number[] | nil
  }

Forecasts the next horizon periods of a time-series model, with an optional confidence level for the interval.

model:info

  • Normal
  • Integration
model:info()
  -> ok, result: {
    backend: string,
    concept: string,
    modelType: string,
    name: string,
    status: string
  }

The model's name, type, backend, concept and status.

model:predict

  • Normal
  • Integration
model:predict(features: { [key: string]: any } | string)
  -> ok, result: {
    confidence: number | nil,
    predictedClass: string | nil,
    prediction: number | nil,
    warnings: string[] | nil
  }

Predicts from one set of features.

ctx.notify

ctx.notify.send

  • Normal
  • Integration
ctx.notify.send(
  input: {
    body: string,
    bodyHtml: string | nil,
    group: string | nil,
    recipient: string | nil,
    subject: string
  } | string,
  options?: { body: string, bodyHtml: string | nil, subject: string }
)
  -> ok, result: { recipientCount: number, status: string } | nil

Sends a notification to a group or recipient. Pass a single table { group?/recipient?, subject, body, bodyHtml? }. The legacy (targetId, options) two-arg form is deprecated.

ctx.protobuf

ctx.protobuf.decode

  • Normal
  • Integration
ctx.protobuf.decode(descriptor: string, bytes: string)
  -> ok, result: any

Decodes a protobuf payload (base64) against a descriptor: a registered one, or in an integration one its manifest declares.

ctx.script

ctx.script.load

  • Normal
  • Integration
ctx.script.load(name: string) -> any

Loads another stored Script by name and returns its exports. Raises a catchable error when the Script does not exist — wrap in pcall to fall back.

ctx.sql

ctx.sql.query

  • Normal
  • Integration
ctx.sql.query(sql: string, bindings?: { [key: string]: any })
  -> ok, result: {
    headers: string[],
    limit: number,
    nextOffset: number | nil,
    rowCount: number,
    rows: any[][],
    truncated: boolean
  }

Read-only SQL over your account's reporting tables. Maximum 1000 rows per query. Check truncated; use LIMIT and OFFSET with a stable unique ORDER BY to fetch subsequent pages using nextOffset, or aggregate in SQL.

ctx.store

ctx.store.delete

  • Normal
  • Integration
ctx.store.delete(name: string, schemaName?: string) -> ok, result: nil

Deletes a stored record, if it exists.

ctx.store.get

  • Normal
  • Integration
ctx.store.get(name: string, schemaName?: string)
  -> ok, result: {
    createdAt: string | nil,
    data: any,
    name: string,
    schemaName: string | nil,
    updatedAt: string | nil
  } | nil

Reads one stored record by name. In an integration, give the schema it belongs to.

ctx.store.list

  • Normal
  • Integration
ctx.store.list(
  schemaName?: string,
  opts?: { limit: number | nil, offset: number | nil }
)
  -> ok, result: {
    createdAt: string | nil,
    data: any,
    name: string,
    schemaName: string | nil,
    updatedAt: string | nil
  }[]

Lists stored records by name, up to opts.limit (default 100, at most 1000) from opts.offset.

ctx.store.put

  • Normal
  • Integration
ctx.store.put(name: string, data: any, schemaName?: string)
  -> ok, result: {
    createdAt: string | nil,
    data: any,
    name: string,
    schemaName: string | nil,
    updatedAt: string | nil
  }

Creates or replaces a stored record. In an integration, give a schema the manifest declares.

ctx.store.query

  • Normal
  • Integration
ctx.store.query(
  query: {
    schemaName: string | nil,
    taggableId: string | nil,
    taggableType: string | nil
  }
)
  -> ok, result: {
    createdAt: string | nil,
    data: any,
    name: string,
    schemaName: string | nil,
    updatedAt: string | nil
  }[]

Finds stored records tagged with a job (taggableType = "job", taggableId), optionally in one schema.

ctx.template

ctx.template.get

  • Normal
  • Integration
ctx.template.get(name: string) -> Template

The template with this name. In an integration, the id of one of the resources its manifest binds.

ctx.template.render

  • Normal
  • Integration
ctx.template.render(template: string, vars?: { [key: string]: any })
  -> ok, result: string

Renders a stored template with the given variables: the one-call form of ctx.template.get(name):render(vars).

Template

A stored template. Returned by ctx.template.get, with these methods:

template:id

  • Normal
  • Integration
template:id() -> ok, result: string

The template's id.

template:name

  • Normal
  • Integration
template:name() -> string

The name the template was looked up by.

template:render

  • Normal
  • Integration
template:render(vars?: { [key: string]: any }) -> ok, result: string

Renders the template with these variables.

ctx.twin

ctx.twin.attributes

  • Normal
ctx.twin.attributes()
  -> ok, result: {
    bands: {
      label: string,
      lowerInclusive: number | nil,
      upperExclusive: number | nil
    }[] | nil,
    description: string,
    displayName: string,
    key: string,
    kind: string,
    priority: number
  }[]

The behaviour attributes a hypothetical allocation may carry, highest priority first, with the bands a numeric attribute is grouped into. Needs the workCenterBehaviorProfile:read permission.

ctx.twin.project

  • Normal
ctx.twin.project(
  input: {
    applyPaceDrift: boolean | nil,
    bucketMinutes: number | nil,
    horizonHours: number | nil,
    hypotheticalAllocations: {
      attributes: { [key: string]: string | number } | nil,
      dependsOn: string[] | nil,
      dueAt: string | nil,
      jobLabel: string | nil,
      label: string,
      quantity: number | nil,
      runMinutes: number | nil,
      setupMinutes: number | nil,
      startAt: string,
      workCenterId: string
    }[] | nil,
    samples: number | nil,
    scheduleScenarioId: string | nil,
    seed: number | nil,
    workCenterId: string
  }
)
  -> ok, result: {
    allocations: {
      attributeValues: { key: string, value: string }[],
      endP10At: string,
      endP50At: string,
      endP90At: string,
      evidenceDepth: number,
      label: string | nil,
      operationId: string | nil,
      plannedEndAt: string,
      plannedStartAt: string,
      probabilityLaterThanPlanned: number,
      truncatedAtHorizonProbability: number,
      workCenterId: string
    }[],
    bucketMinutes: number,
    calendarScheme: string,
    horizonEndAt: string,
    horizonStartAt: string,
    machineStatus: string | nil,
    samples: number,
    scheduleScenarioId: string | nil,
    seed: number,
    slices: {
      availableMinutes: number,
      blockIndex: number | nil,
      dayKind: string | nil,
      endAt: string,
      expectedBusyMinutes: number,
      expectedLostMinutes: number,
      expectedStops: number,
      kind: string | nil,
      lostMinutesP10: number,
      lostMinutesP90: number,
      shiftDefinitionId: string | nil,
      shiftName: string | nil,
      startAt: string,
      stopProbability: number
    }[],
    strip: {
      availableShare: number,
      downProbability: number,
      endAt: string,
      expectedBusyShare: number,
      startAt: string
    }[],
    summary: {
      boundedAllocations: number,
      expectedLostMinutes: number,
      expectedStops: number,
      expectedUtilization: number,
      truncatedAllocations: number
    },
    timeZone: string | nil,
    timeZoneUnset: boolean,
    uncalibrated: boolean,
    workCenterId: string
  }

Projects one work centre over the next N hours (default 24, at most 336) from its behaviour profile and its published plan: per shift or time-bucket occurrence the expected busy and lost minutes with a P10–P90 band on the loss, the probability of a stop and the expected number of stops; a strip of down probability per bucket (5, 15, 30 or 60 minutes); and P10/P50/P90 ends per allocation. Hypothetical allocations must be on this work centre and start inside the window. The same input and result as the projectWorkCenterTwin GraphQL query, with attributes written as a plain table; timestamps are ISO8601 UTC instants and slice keys carry the tenant-local shift identity. Persists nothing. Needs the scenarioSimulationRun:execute permission.

ctx.twin.shadow

  • Normal
ctx.twin.shadow(workCenterId: string)
  -> ok, result: {
    catchUpConfidence: number | nil,
    evaluatedAt: string,
    operations: {
      attributeValues: { key: string, value: string }[],
      catchUpConfidence: number | nil,
      elapsedMinutes: number,
      evidenceDepth: number,
      expectedEndP10At: string | nil,
      expectedEndP50At: string | nil,
      expectedEndP90At: string | nil,
      jobId: string | nil,
      observedPaceUnitsPerMinute: number | nil,
      operationId: string,
      phase: string,
      phaseStartedAt: string,
      plannedEndAt: string | nil,
      projectedEndAt: string | nil,
      scenarioId: string | nil,
      since: string | nil,
      state: string
    }[],
    pace: {
      driftRatio: number | nil,
      since: string,
      state: string
    } | nil,
    state: string,
    workCenterId: string
  }

The live shadow of a work centre, computed now: what is running on it, the profile's expected finish, the observed pace, each operation's state (ON_TRACK, DRIFTING, STALLED, PAUSED, DOWN, DOWN_OVERDUE, UNCALIBRATED; IDLE with nothing running) and the catch-up confidence over the machine's own queue. A work centre may run several operations at once; the work centre's state is the most severe of them. pace is the pace track's current state (STEADY or SLOWING with the drift ratio and since when), or nil when the machine has no pace judgement. The same shape as the workCenterTwinShadow GraphQL query; timestamps are ISO8601 strings. Needs the workCenterBehaviorProfile:read permission.

ctx.twin.simulate

  • Normal
ctx.twin.simulate(
  input: {
    applyPaceDrift: boolean | nil,
    baseScheduleScenarioId: string | nil,
    hypotheticalAllocations: {
      attributes: { [key: string]: string | number } | nil,
      dependsOn: string[] | nil,
      dueAt: string | nil,
      jobLabel: string | nil,
      label: string,
      quantity: number | nil,
      runMinutes: number | nil,
      setupMinutes: number | nil,
      startAt: string,
      workCenterId: string
    }[],
    samples: number | nil,
    seed: number | nil
  }
)
  -> ok, result: {
    allocations: {
      attributeValues: { key: string, value: string }[],
      endP10At: string,
      endP50At: string,
      endP90At: string,
      evidenceDepth: number,
      label: string | nil,
      operationId: string | nil,
      plannedEndAt: string,
      plannedStartAt: string,
      probabilityLaterThanPlanned: number,
      truncatedAtHorizonProbability: number,
      workCenterId: string
    }[],
    jobs: {
      completionP50At: string,
      completionP90At: string,
      dueAt: string | nil,
      jobId: string | nil,
      jobLabel: string | nil,
      onTimeProbability: number | nil
    }[],
    summary: {
      expectedLateJobs: number,
      makespanP50At: string,
      makespanP90At: string,
      samples: number,
      truncatedAllocations: number,
      uncalibratedWorkCenterIds: string[]
    },
    workCenters: {
      expectedUnplannedDowntimeMinutes: number,
      expectedUtilization: number,
      latenessContributionMinutes: number,
      riskRank: number,
      workCenterId: string
    }[]
  }

Replays hypothetical work against the work-centre twin and returns on-time probabilities per job, P10/P50/P90 finishes per allocation and a risk ranking per work centre. The same input and result as the simulateWorkload GraphQL field, with attributes written as a plain table; timestamps are ISO8601 strings. Needs the scenarioSimulationRun:execute permission.