Skip to main content

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​

MethodWhat 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​

MethodWhat it does
utils.http.statusThe 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​

MethodWhat 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.

ObjectWhat it holds
utils.collectionThe collection this API belongs to, including its saved authValues.
utils.apiThe API record that is running.
utils.inputThe input this run was called with, for example from a workflow.
utils.lastResultThe full last result, with status, headers and data. Useful right after a retry.
utils.axiosPlain 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.