Script Method Reference
Overview
Every script, whether it belongs to a collection or an API and whether it runs before or after the request, has a utils object with the methods below. The Script Utilities tab in the Script Help panel lists them while you edit. Lodash is also available as _.
info
helpers is an older name for the same object and still works. New scripts should use utils.
Request and Auth
| Method | What it does |
|---|---|
utils.executeSavedApi(apiId, options) | Runs another saved API, referenced for example as @Auth, and returns its result. |
utils.applyRequestAuth(request, type, values) | Applies authentication to a request. The type is BEARER, BASIC, API_KEY or NONE. |
utils.updateRequestBearerToken(token, request) | A shortcut that sets only the Bearer token. |
utils.removeRequestAuth(request) | Removes authentication from the request. |
utils.updateCollectionAuth(patch) | Saves a token so it is reused, by merging the given fields into the collection's stored authentication. |
utils.replaceCollectionAuth(values) | The same, but replaces the stored authentication values entirely. |
Retry and Token Refresh
| Method | What it does |
|---|---|
utils.http.status | The response status so far. Read it in a Post Script to decide whether to retry. |
utils.retryRequest(overrides) | Sends the current request again, as it is or with parts changed. |
utils.refreshTokenAndRetry(authApiId, options) | The one call version of the refresh pattern: runs the login API, extracts the token, saves it and retries. |
utils.extractToken(payload, tokenPath) | Pulls a token out of a login response. Give a tokenPath such as data.token when the token is not at the top level. |
utils.isAuthError(status, body) | True for a 401, or for a body that mentions an expired, invalid or missing token. |
Data Utilities
| Method | What it does |
|---|---|
utils.defaultValue(value, fallback) | Gives a fallback when a value is null or undefined. |
utils.formatDateOnly(value) | Turns an ISO date and time into YYYY-MM-DD. |
utils.addSourceToArrays(labelKey, arrays) | Joins several arrays into one and tags each item with the array it came from. |
utils.getValue(obj, path, fallback) | Reads a nested field by dot path, for example a.b.c. |
utils.setValue(obj, path, value) | Writes a nested field by dot path. |
utils.deepClone(value) | Makes a deep copy of an object or array before you edit it. |
utils.mergeObjects(a, b) | Deep merges several objects into one. |
Context Objects
These are available for reading only.
| Object | What it holds |
|---|---|
utils.collection | The collection this API belongs to, including its saved authValues. |
utils.api | The API record that is running. |
utils.input | The input this run was called with, for example from a workflow. |
utils.lastResult | The full last result, with status, headers and data. Useful right after a retry. |
utils.axios | Plain HTTP clients for the collection, the API or a bare request, for a one off call that should not go through a saved API. |
tip
Use utils.getValue when reading a field from an outside response. It returns your fallback instead of failing when the field is missing.