Variables, secrets and troubleshooting

Variable administration

Variables hold the plaintext settings a script reads, such as a base URL, an ID or an environment name. You need script-engine.admin to open Admin settings → Script Engine → Variables. Create a variable with a Key name, value, description, and scope. A key name uses letters, digits, and underscores, and does not start with a digit, for example Partner_Api_BaseUrl. Workflow environment variables follow the same rule, so a name you use in both places is valid in both. Leave the scope at All scripts, or choose a script when only that script needs the value. At runtime, scripts read the value from context["variables"] using the key name:

def execute(input, context):
    base_url = context["variables"]["Partner_Api_BaseUrl"]
    token = context["secrets"]["Partner_Api_Token"]
    reply = context["http"].post(
        f"{base_url}/requests",
        json={"caseNo": input["caseNo"]},
        headers={"Authorization": f"Bearer {token}"},
    )
    return {"requestId": reply["id"]}

A fixed token kept in a secret, as here, suits an API key. If the API wants a token that you first request with a client ID and client secret, see Call an API that uses OAuth client credentials. Unlike secrets, the list shows each value and who changed it last, so you can check what a script sees when it misbehaves. Values are stored in plaintext. Put passwords, tokens, client secrets and keys in secrets instead. Key names are unique across the variable store, including script-scoped entries. Deleting a variable removes it from future execution contexts, and a script that reads it fails until it is added again. Deleting a script deletes the variables scoped to it.

Secret administration

You need script-engine.admin to open Admin settings → Script Engine → Secrets. Script management alone does not allow secret administration. Create a secret with a Key Name, value, description, and scope. Choose a specific script when only that script needs the credential; Global makes it available to all scripts. At runtime, scripts obtain the value from context["secrets"] using the key name. The list returns secret metadata, not stored values. To rotate a value, edit the entry and supply its replacement. Key names are unique across the secret store, including script-scoped entries; use distinct names for distinct credentials.

Hiding values in the administration list is not a barrier against someone who can author code that receives those secrets. Treat script-authoring access as trusted integration access. Do not place secret values in source, commit messages, returned data, or log messages.

Deleting a secret removes it from future execution contexts. Review dependent scripts before deleting or changing its scope. Changing a credential here does not revoke it at the external provider.

Secret metadata shows the script scope without exposing a stored credential.

Call an API that uses OAuth client credentials

Many partner APIs expect a bearer token that you first request from an OAuth token endpoint with a client ID and client secret. Keep the token URL, client ID and audience or scope in variables, and the client secret in a secret. You need script-engine.admin to manage both. Then call context["http"].client_credentials_token(...) right before each request, instead of requesting the token yourself. This Workflow Action (workflow_action) reads a claim from a partner API whose tokens come from Auth0, which identifies the API by an audience:

def execute(input, context):
    v, http = context["variables"], context["http"]

    def token(force_refresh=False):
        return http.client_credentials_token(
            v["Partner_TokenUrl"],
            v["Partner_ClientId"],
            context["secrets"]["Partner_ClientSecret"],
            audience=v["Partner_Audience"],
            force_refresh=force_refresh,
        )

    url = f"{v['Partner_ApiBaseUrl']}/api/v1/claims/{input['claimNo']}"
    # Get the token outside the try: a failed token request is not an API 401.
    headers = {"Authorization": "Bearer " + token()}
    try:
        claim = http.get(url, headers=headers)
    except HttpError as e:
        if e.status_code != 401:
            raise
        # The API rejected the token: get a fresh one and retry once.
        claim = http.get(url, headers={"Authorization": "Bearer " + token(force_refresh=True)})
    return {"claimStatus": claim["status"]}

HttpError is available in every script without an import. Its status_code is the HTTP status the API answered with. The Script Engine keeps the token and gives the same one to every script and run that uses the same credentials, until shortly before it expires and for at most 24 hours. Runs that start at the same time share one token request. You therefore see a token request each time the token nears expiry, not one per run. The token is kept in memory only: after the Script Engine restarts, for example after an update, the first call requests a new token. If your environment runs the Script Engine on more than one server, each server requests its own token.

Changing the secret, audience, scope, token URL or client ID gives a new token at the next run.
A failed token request is not remembered: the next call that needs a new token tries again. A token whose reply does not say when it expires (expires_in) is used for that call but not kept.
If the API answers 401, request a token again with force_refresh=True and retry once, as the example does. You get a fresh token, or the one another run has just fetched. For the same credentials, a forced refresh requests a new token at most once every 30 seconds; within that time you get the current one. If the forced request fails, the kept token stays in use.
force_refresh=True replaces only a token that the same run has already received. As the first call in a run it returns the kept token, so call client_credentials_token normally first, as the example does.
A permission or role that you grant the client at the provider, without changing the secret, audience or scope, reaches your scripts only when the kept token expires (up to 24 hours for providers that issue day-long tokens, as Auth0 does by default) or after a forced refresh. The example passes a 403 on as an error. Treat 403 like 401 (write if e.status_code not in (401, 403): instead of if e.status_code != 401:) only for an API whose 403 always means that the client lacks a permission or role, and preferably only while you roll out such a change. Never do it for an API that also answers 403 when it refuses a single record, such as a claim this client may not see: every such answer can then request a new token, up to one every 30 seconds for the same credentials, instead of one each time the token nears expiry.
If no token is obtained, the call raises HttpError with a message that starts with Token request failed:. Its status_code is the token endpoint’s status, or None when no reply arrived: a timeout, a network failure, or a destination that is not allowed. An invalid argument raises ValueError, and the message names the argument. So does a run that obtains tokens for more than eight different sets of credentials: the ninth set raises ValueError.
The token endpoint must use HTTPS and, like every context["http"] call, be one of the environment’s allowed destinations.
Never log, print or return the token, and never put it in a URL.

For Microsoft Entra ID, pass scope instead of audience. Only the token function in the example changes:

def token(force_refresh=False):
    return http.client_credentials_token(
        v["Erp_TokenUrl"],     # https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
        v["Erp_ClientId"],
        context["secrets"]["Erp_ClientSecret"],
        scope=v["Erp_Scope"],  # api://<app-id>/.default
        force_refresh=force_refresh,
    )

By default the client ID and client secret are sent in the request body. If the provider expects them as an HTTP Basic header, pass auth_method="client_secret_basic".

Inspect execution logs

With script-engine.view or a higher Script Engine permission, open Admin settings → Script Engine → Execution Logs. Filter by success/failure, user, or date interval, then apply the filters. The current type dropdown offers the Caseflow types; leave it at All when investigating event hooks or workflow actions. Use Load More for older results. Open a row to inspect the script and version IDs, type, entity ID, execution mode, user, duration, time, error, and correlation ID when present. Input and output details appear only when payload capture is available; their absence does not mean the script received no input.

An execution detail identifies the script version, caller, status, correlation ID, input, and output.

Diagnose by symptom

Symptom	What to check
Script is saved but behavior has not changed	Compare the published version with the version you pushed. Save and publish are separate operations.
Publish is unavailable	Check manage access, syntax and contract validation, and whether the latest saved version is already published.
No script is found	Verify the caller’s slug or binding, the script type, and that a version is published. Resolution failures can occur before an execution-log row is created.
External autofill returns nothing	Check the set binding, primary value, member keyword IDs, and the returned rows against the external-autofill contract.
Event hook does not run	Check document type, trigger event, publication, and whether the source operation emits that event. Ask support to investigate delivery if these match.
Access is denied during a callback	Check the actual calling identity: user, event-hook service account, or workflow service.
Execution fails or times out	Read the error and duration; check input/output contract, external destination availability, and the work done by the script.
A variable is missing or has the wrong value	Check the key name, its scope, and the value in Variables. A script-scoped variable is not visible to other scripts.
A secret is missing	Check the key name and script/global scope. Have a secrets administrator replace an unreadable value rather than exposing it in a diagnostic.
`Token request failed: …` from `client_credentials_token`	The message names the token endpoint’s status and, when it is a standard OAuth code, the reason, for example `invalid_client`. Check the client ID, the audience or scope, and the secret. After you rotate the secret at the provider, update the secret here; the next run requests a new token. If the provider expects HTTP Basic, pass `auth_method="client_secret_basic"`. The token endpoint must use HTTPS and be an allowed destination.
An external API answers 401 to a token	Retry once with `force_refresh=True`. Repeated 401s mean the token’s audience, scope or permissions do not match the API.
An external API still refuses a token after you granted the client a permission at the provider	The Script Engine keeps a token until shortly before it expires, up to 24 hours. The new permission arrives with the next token: wait for the kept one to expire, or force a refresh after the refusal. If the API answers 403 and its 403 always means a missing permission, you can handle 403 like 401 while you roll out the change, as described in Call an API that uses OAuth client credentials. Not for an API that also answers 403 for a single record the client may not see: each such answer can request a new token.

When escalating, include environment, time, script slug and executed version ID, entity ID, correlation ID if shown, and the operation that triggered it. Exclude credentials and unnecessary business data.

Where to read next

Introduction to Workflows

Understand how the Nobly Insight workflow engine automates document and case processes — definitions, triggers, nodes, actions, and tasks.

Getting started

Features

How we use AI

Permissions & access

Document types & keywords

Client administration

Search administration

AI search

AI document classification

AI administration

Caseflow

Form documents

Script Engine

Workflows

ContentFlow

Integrations

Mailbox importer

AI assistant access

Reporting

Retention & deletion

Configuration promotion

Release notes

Variables, secrets and troubleshooting

Variable administration

Secret administration

Call an API that uses OAuth client credentials

Inspect execution logs

Diagnose by symptom

Where to read next

Introduction to Workflows

​Variable administration

​Secret administration

​Call an API that uses OAuth client credentials

​Inspect execution logs

​Diagnose by symptom

​Where to read next

Introduction to Workflows

Variable administration

Secret administration

Call an API that uses OAuth client credentials

Inspect execution logs

Diagnose by symptom

Where to read next