ioLoop Docs

Appearance

$io.system ​

Client API reference.

Functions ​

$io.system.connectionCommand ​

Invoke a client-supported command exposed by a configured Connection.

Usage ​

js
$io.system.connectionCommand(serviceName, connectionName, command, commandParams)

Description ​

Invokes a command exposed by a Connection configured in your Project. Not every Connection provides commands, and only commands that support the client context can be called with this Client API.

Although the call is initiated by Page Flow or client JavaScript, the command executes on the server using the configured Connection. The call is subject to the Connection's Access settings. See the documentation for the Connection service for its available commands, parameters, and return values.

Usage Scenarios ​

  • Invoke a Connection command from Page Flow or custom client JavaScript
  • Invoke a supported operation using a Connection configured in your Project
  • Pass command-specific data to an external service and handle the returned result

Parameters ​

serviceName ​

Type: String

Required: Yes

The service identifier for the configured Connection. See the Connection service's documentation for its identifier and supported client commands. You may use the App Assets sidebar to copy the service name.

connectionName ​

Type: String

Required: Yes

The name of the configured Connection to use. You may use the App Assets sidebar to copy the Connection name.

command ​

Type: String

Required: Yes

A command exposed by the Connection service for use in the client context. You may use the App Assets sidebar to select and copy a supported command.

commandParams ​

Type: Object

Required: Yes

An object whose properties match the selected command's documented parameters. You may use the App Assets sidebar to copy a parameter template and fill in its values.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties:

  • status: A Boolean value of true if the operation was successful or false otherwise.
  • data: If successful, the command's documented result; otherwise null.
  • err: If successful set to null, otherwise the information about the error (usually as a string).

$io.system.createTimer ​

Creates a one-shot timer for the specified interval, with optional time units.

Usage ​

js
$io.system.createTimer(interval, cbFn, cbContext, units)

Description ​

Creates a one-shot timer for the specified interval, with optional time units. After the interval elapses, the provided callback function will be called. Note that the timer is a one-shot and needs to be explicitly rearmed using the $io.system.reArmTimer function.

Parameters ​

interval ​

Type: Number

Required: Yes

The interval in the specified units. Defaults to milliseconds when units is omitted.

cbFn ​

Type: Function

Required: Yes

The function to invoke, after the timer elapses. The function will be passed two parameters:

  • Reference to an object representing the timer which can be used to call the $io.system.reArmTimer function.
  • The context object provided in the cbContext parameter

cbContext ​

Type: Object

Required: Yes

A context object to be passed to the callback function. Can be null.

units ​

Type: String

Required: No

Optional time units: 'seconds', 'minutes', or 'hours'. If omitted, empty, or unrecognized, interval is interpreted as milliseconds.

Output ​

Type: Object

Returns the armed timer object, which can be passed to $io.system.reArmTimer.

$io.system.delay ​

Pause execution for the specified number of milliseconds.

Usage ​

js
$io.system.delay(delayMs)

Description ​

Suspends execution for delayMs milliseconds using an async sleep, returning a Promise that resolves after the specified time.

Recommended for spacing out API calls, simple retry loops, or giving the event loop a brief breather between tasks.

Usage Scenarios ​

  • Throttle API requests or add small gaps between retries
  • Sequence async steps with intentional timing
  • Backoff before reattempting a transient operation

Parameters ​

delayMs ​

Type: Number

Required: Yes

Duration to wait in milliseconds (e.g., 50, 250, 1000). Must be >= 0.

Output ​

Type: Promise

Resolves after the specified delay.

$io.system.ensureAuthenticated ​

Require login and optional group/role permissions, showing a login modal when needed without navigating away from the page.

Usage ​

js
$io.system.ensureAuthenticated(options)

Description ​

Refreshes the current session information. If the user is not logged in, shows a login modal while keeping the current page loaded. Incorrect credentials keep the modal open with an error so the user can retry or cancel. After login, checks the optional group and minimum role level using the same membership rules as $io.system.queryGroupMembership, including admin access. Group IDs for this check can be: 0: Public, 1: All Users, 2-11: app-defined custom groups, 12: Admin. Even when groupId is 0 (Public), this function still requires login.

Returns success only when login and any requested permissions are satisfied. If the user is logged in but lacks permission, returns an Access denied error and leaves the user logged in. Concurrent calls share one login modal and check their own group/role requirements separately.

The author must await the result and check status before fetching or displaying protected content. Server endpoints must also enforce the required permissions. Current-user information is updated before the result is returned after a successful session check or login. No separate waitForAuthInfo call is required.

Example requiring a group and role: const result = await $io.system.ensureAuthenticated({groupId: 2, roleLevel: 2}); if(!result.status) { return; } // Fetch and display the protected content here.

To require login only, omit options: const result = await $io.system.ensureAuthenticated();

Usage Scenarios ​

  • Require login before loading protected content within a public single-page app
  • Check a user's group and minimum role level before continuing a navigation action

Parameters ​

options ​

Type: Object

Required: No

Optional object with the following properties:

  • groupId: Optional integer group identifier from 0 through 12. 0 is Public, 1 is All Users, 2-11 are app-defined custom groups, and 12 is Admin. Group IDs 0, 1, and 12 are fixed system IDs and cannot be renamed. Use the numeric identifier, not the group name.
  • roleLevel: Optional minimum integer role level from 0 through 4. 0 is Staff Level 1, 1 is Staff Level 2, 2 is Supervisor, 3 is Manager, and 4 is Dept Lead. Defaults to 0 when omitted. Requires groupId to be supplied. Omitting options or passing {} requires login without a group/role check. Invalid options return a failure response without opening the modal.

Output ​

Type: Promise

Resolves to the standard response object:

  • status: true only if the user is authenticated and any requested access check passes.
  • data: null.
  • err: null on success; otherwise an error string, such as Login cancelled, Access denied, an invalid-options error, or an authentication-server error.

$io.system.execCloudFlowWebHook ​

Communicate with or Invoke a ioLoop Cloud Flow web-hook endpoint defined in your app.

Usage ​

js
$io.system.execCloudFlowWebHook(webHookName, data)

Description ​

Communicate with a defined ioLoop Cloud Flow web-hook endpoint in your app. Please note that currently this function only supports HTTP POST type web-hooks and does not support HTTP GET webhooks.

Usage Scenarios ​

  • Call a Cloud Flow web hook from a page
  • Communicate with my app's backend logic from a page
  • Send data to my app's backend logic from a page

Parameters ​

webHookName ​

Type: String

Required: Yes

The name of the webhook endpoint. To create a Webhook endpoint refer to: https://docs.ioloop.com/project-editor/backend/cloud-flow/web-hooks#creating-a-web-hook You may use the App Assets side-bar (on the left) to copy the name of the Webhook.

data ​

Type: Object

Required: Yes

The object representing the data to be sent in the request. If the web-hook does not need any data, you can set this to null.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties:

  • status: A Boolean value of true if the operation was successful or false otherwise.
  • data: If successful, an object representing the data returned by the web-hook, null otherwise.
  • err: If successful set to null, otherwise the information about the error (usually as a string).

$io.system.generateJson ​

Generate a JSON string from an object.

Usage ​

js
$io.system.generateJson(dataObj)

Description ​

Converts the provided object or value into a JSON string using JSON.stringify.

Usage Scenarios ​

  • Serialize an object before sending it to an API
  • Store an object as a JSON string

Parameters ​

dataObj ​

Type: Any

Required: Yes

The object or value to serialize as JSON.

Output ​

Type: String

A JSON string representation of the provided value.

$io.system.getCurrentUser ​

Returns the current authenticated user's username.

Usage ​

js
$io.system.getCurrentUser()

Description ​

Returns the current authenticated user's username. This function returns valid values only after the authentication information is retrieved successfuly from your ioLoop's app backend. See the $io.system.waitForAuthInfo function.

Parameters ​

This function does not require parameters.

Output ​

Type: String

The username for the currently authenticated user or an empty string.

$io.system.getFlowShareData ​

Retrieve shared data (object or value) from a form or page when displayed as a popup modal.

Usage ​

js
$io.system.getFlowShareData(name)

Description ​

Use this function to retrieve any data (objects or values) shared between a page or form, especially when the form is being shown as a popup modal. This allows you to access context-sensitive data passed from the parent flow, such as pre-filled fields or configuration settings.

Usage Scenarios ​

  • Access data passed from a parent page to a form displayed in a modal, such as pre-filled user details or settings
  • Retrieve shared data during multi-step workflows where data is passed between steps in modal popups
  • Access dynamic content shared between different components or modals within the same flow

Parameters ​

name ​

Type: String

Required: Yes

The property name of the shared data (object or value)

Output ​

Type: Any

Returns the shared data (object or value) associated with the provided name. Returns null if the property does not exist or its value is falsy, including false, 0, an empty string, null, undefined, or NaN.

$io.system.httpGet ​

Send an HTTP GET request.

Usage ​

js
$io.system.httpGet(url, cbSucc, cbFail)

Description ​

Sends an HTTP GET request to the specified URL. The success callback receives the response payload. The fail callback receives error information.

Usage Scenarios ​

  • Fetch data from an external endpoint
  • Call a public API to retrieve information

Parameters ​

url ​

Type: String

Required: Yes

The target URL to GET.

cbSucc ​

Type: Function

Required: Yes

Callback invoked on success. Receives the response payload as the first argument. The payload is the response body returned by the endpoint (object, string, or other type).

cbFail ​

Type: Function

Required: Yes

Callback invoked on failure. Receives error information as the first argument. This may be a string message, a false value, or an error object depending on the request path.

Output ​

Type: null

This function does not return a value.

$io.system.httpPost ​

Send an HTTP POST request.

Usage ​

js
$io.system.httpPost(url, data, cbSucc, cbFail)

Description ​

Sends an HTTP POST request to the specified URL. The success callback receives the response payload. The fail callback receives error information.

Usage Scenarios ​

  • Send form data or JSON payloads to an external endpoint
  • Trigger a webhook or API action

Parameters ​

url ​

Type: String

Required: Yes

The target URL to POST to.

data ​

Type: Object

Required: Yes

Data to send in the POST request. Use an empty object if no data is required.

cbSucc ​

Type: Function

Required: Yes

Callback invoked on success. Receives the response payload as the first argument. The payload is the response body returned by the endpoint (object, string, or other type).

cbFail ​

Type: Function

Required: Yes

Callback invoked on failure. Receives error information as the first argument. This may be a string message, a false value, or an error object depending on the request path.

Output ​

Type: null

This function does not return a value.

$io.system.ioLoopDateFromJsDate ​

Convert a JavaScript Date object to a ioLoop Page Flow Visual Programming date object

Usage ​

js
$io.system.ioLoopDateFromJsDate(jsDate)

Description ​

This function converts a JavaScript Date object to a ioLoop Page Flow visual programming editor date object.

Parameters ​

jsDate ​

Type: Date

Required: Yes

The JavaScript Date object to convert

Output ​

Type: Object

A ioLoop Page Flow visual programming editor date object.

$io.system.ioLoopDateFromMomentObject ​

Convert a moment.js object to a ioLoop Page Flow Visual Programming date object

Usage ​

js
$io.system.ioLoopDateFromMomentObject(mObject)

Description ​

This function converts a moment.js object to a ioLoop Page Flow visual programming editor date object.

Parameters ​

mObject ​

Type: Object

Required: Yes

The moment.js object to convert

Output ​

Type: Object

A ioLoop Page Flow visual programming editor date object.

$io.system.isTestMode ​

Determines if your app's logic is being executed in the ioLoop Page Editor's preview mode.

Usage ​

js
$io.system.isTestMode()

Description ​

This function checks if the current execution context of your app is running in the ioLoop Page Editor's preview functionality. It is useful for determining whether certain logic or features should be run only during development and testing, and not in the live production environment. This can help to isolate testing behavior from production use cases.

Usage Scenarios ​

  • Conditionally execute or bypass certain logic during app development or testing when in preview mode
  • Display mock data or placeholder content when the app is in preview mode
  • Test specific features or UI components without affecting the live production environment

Parameters ​

This function does not require parameters.

Output ​

Type: Boolean

Returns true if the logic is being executed in the ioLoop Page Editor's preview mode. Returns false if it is being run in a published or production environment.

$io.system.jsonParse ​

Parse a JSON string into an object.

Usage ​

js
$io.system.jsonParse(jsonStr)

Description ​

Parses the provided JSON string and returns the corresponding object or value. If the string is invalid JSON, this function returns null.

Usage Scenarios ​

  • Convert a JSON string into an object for further processing
  • Handle JSON responses stored as strings

Parameters ​

jsonStr ​

Type: String

Required: Yes

The JSON string to parse.

Output ​

Type: Any

The parsed value, or null if parsing fails.

$io.system.log ​

Logs the message along with timestamp and optional meta information to the console

Usage ​

js
$io.system.log(message, category, level)

Description ​

Logs the provided message to the console along with timestamp and optional meta information specified in the categry and level parameters.

Usage Scenarios ​

  • Debug my logic, app or page

Parameters ​

message ​

Type: String

Required: Yes

The message to log.

category ​

Type: String

Required: Yes

A category e.g. "ERROR" or "INFO" or "WARNING". Can be any text including empty string.

level ​

Type: Number

Required: Yes

A number that specifies the level or severity of the log.

Output ​

Type: null

This function does not return a value.

$io.system.momentObjectFromIoLoopDate ​

Convert ioLoop Page Flow Visual Programming date object to a moment.js object

Usage ​

js
$io.system.momentObjectFromIoLoopDate(ioLoopDate)

Description ​

This function converts a ioLoop Page Flow visual programming editor date object to a moment.js object.

Parameters ​

ioLoopDate ​

Type: Object

Required: Yes

The ioLoop Page Flow visual programming editor date object to convert.

Output ​

Type: Object

moment.js object

$io.system.navigateToUrl ​

Navigates the page to the provided URL.

Usage ​

js
$io.system.navigateToUrl(url)

Description ​

Navigates the page to the provided URL.

Parameters ​

url ​

Type: String

Required: Yes

The URL to navigate to.

Output ​

Type: null

This function does not return a value.

$io.system.queryGroupMembership ​

Check if the current logged in user belongs to the specified group with the provided role level.

Usage ​

js
$io.system.queryGroupMembership(groupId,  roleLevel)

Description ​

Use this function to check if the current logged in user belongs to the specified group with the provided role level.

Usage Scenarios ​

  • Determine if a user has the necessary permissions to access a specific section or perform an action in the app
  • Restrict functionality based on the user's group and role level, such as limiting access to admin-only features
  • Verify if the current user holds a management or supervisory role before allowing them to modify certain records or settings
  • Check membership and role for custom group-based functionalities, such as assigning tasks to users in specific roles within a group

Parameters ​

groupId ​

Type: Number

Required: Yes

Integer representing the ioLoop app group identifier, which can be:

  • 0: Public User Group (no password)
  • 1: All Users Group
  • 2-11: App custom Groups
  • 12: Admin

roleLevel ​

Type: Number

Required: Yes

Integer representing the ioLoop app role level, which can be:

  • 0: Staff Level 1
  • 1: Staff Level 2
  • 2: Supervisor
  • 3: Manager
  • 4: Dept Lead

Output ​

Type: Boolean

true if the user has role level greater than or equal to the specified one for the group, false otherwise

$io.system.queryParameterValue ​

Returns the value of the specified URL query parameter.

Usage ​

js
$io.system.queryParameterValue(name)

Description ​

Returns the value of the specified URL query parameter.

Parameters ​

name ​

Type: String

Required: Yes

The name of the query parameter to get the value of.

Output ​

Type: String

The value of the query parameter or an empty string

$io.system.reArmTimer ​

Rearms a timer

Usage ​

js
$io.system.reArmTimer(timerObj)

Description ​

Rearms the timer created with $io.system.createTimer with the same interval and callback function.

Parameters ​

timerObj ​

Type: Object

Required: Yes

The timer to rearm.

Output ​

Type: null

This function does not return a value.

$io.system.setFlowShareData ​

Set or remove a named shared value in the current page or form flow.

Usage ​

js
$io.system.setFlowShareData(name, value)

Description ​

Stores a value under the specified name in the current page or form's shared data. Use $io.system.getFlowShareData to retrieve it. Passing a falsy value deletes the named property instead of storing that value.

Usage Scenarios ​

  • Share data between functions in the current page or form flow
  • Update or remove a named shared value

Parameters ​

name ​

Type: String

Required: Yes

The property name of the shared data.

value ​

Type: Any

Required: Yes

The value to store. Falsy values, including false, 0, an empty string, null, undefined, or NaN, delete the named property.

Output ​

Type: null

This function does not return a value.

$io.system.waitForAuthInfo ​

Wait for authentication information to be retrieved

Usage ​

js
$io.system.waitForAuthInfo()

Description ​

Use this function to wait for authentication information to be retrieved from your ioLoop's app backend. This does not require a logged-in user or display a login modal. Use $io.system.ensureAuthenticated to require login and optional permissions. Once completed successfuly, the functions $io.system.getCurrentUser and $io.system.queryGroupMembership can be used.

Parameters ​

This function does not require parameters.

Output ​

Type: Promise

A Promise that resolves to a Boolean value: true if successful or false otherwise