Calling Cloud Flow from Pages

Pages and Forms can invoke Cloud Flow Web Hooks when a user-facing workflow needs trusted server-side processing. The frontend collects input and presents results; Cloud Flow validates the request, performs the backend operation, and responds to the caller.

In ioLoop, this can be implemented using Page Flow blocks or custom frontend JavaScript with supported ioLoop Client APIs or appropriate HTTP requests. Built-in Forms, Widgets, and Page Flow provide higher-level interfaces to capabilities available to custom frontends. Choosing a visual or custom implementation does not change the Web Hook's server-side permissions or responsibilities.

This page focuses on connecting a Page or Form to Cloud Flow and handling the resulting interaction. For endpoint settings, request processing, response streaming, and external callers, see Web Hooks.

When to Call Cloud Flow

Use Cloud Flow when a Page needs an operation that should run in a trusted server-side environment, such as:

• Enforcing capacity limits, eligibility rules, or other protected business conditions.
• Confirming that a caller may modify a particular record.
• Using configured Connections and credentials to contact external services.
• Processing files through server-side functionality.
• Performing server-only Database operations or more complex data processing.
• Returning a calculated or restricted result based on trusted information.
• Coordinating work that must not depend on client-side values being trustworthy.

Not every interaction requires Cloud Flow. Pages, Forms, Widgets, Page Flow blocks, and custom frontend JavaScript can perform permitted client-side Database operations directly through the ioLoop Client APIs. Simple navigation, UI updates, Form opening, and immediate input feedback also belong in the frontend.

Requirement	Recommended Approach
Show or hide a Page Element	Page Flow or custom frontend JavaScript.
Open a Form as a modal	Supported Form and Page Flow behavior, or a custom modal interface.
Read records permitted by Table Access	Data Table Widget, Page Flow Database blocks, or Client API.
Create or update a permitted record without additional protected rules	Supported Form, Page Flow, or Client API operation.
Enforce server-side ownership, eligibility, or capacity rules	Cloud Flow Web Hook.
Use a provider credential or server-only Database functionality	Cloud Flow and appropriate Server APIs or Connections.
Receive an HTTP request from a Page and return a backend result	Cloud Flow Web Hook.

Choose based on the operation's trust and capability requirements, not merely because it uses Project data.

Frontend and Cloud Flow Responsibilities

A Page-to-Cloud Flow interaction has two distinct execution environments.

Frontend: Page Flow or Custom JavaScript	Backend: Cloud Flow Web Hook
Responds to the user's action.	Receives the HTTP request.
Collects Form values or selected-item context.	Validates the submitted values and caller context.
Provides immediate input guidance.	Enforces protected authorization and business rules.
Shows a loading or processing state.	Performs Database, file, or Connection operations.
Waits for the request result.	Constructs and completes the HTTP response.
Shows a confirmation or error and updates the interface.	Returns the outcome and only the data the caller should receive.

The frontend is responsible for the user experience. Cloud Flow is responsible for the trusted work. Frontend checks do not replace server-side validation when the result affects protected data or operations.

Typical Request Lifecycle

A common workflow follows these steps:

1. A visitor selects a Button, submits a Form, or performs another Page action.
2. The frontend reads the required values and performs immediate validation where useful.
3. The frontend prepares the request and invokes the intended Cloud Flow Web Hook.
4. The Web Hook's access configuration determines whether the caller may invoke the endpoint.
5. Cloud Flow validates the inputs and checks the application's authorization and business rules.
6. Cloud Flow performs the server-side operation and completes its response.
7. The frontend checks the request outcome and any application-level result.
8. On confirmed success, the frontend updates the Page or closes the Form as appropriate. On failure, it provides useful recovery feedback.

Page or Form
  User action
  Collect and validate input
  Show processing state
          |
          | Invoke Cloud Flow Web Hook
          v
Cloud Flow
  Validate and authorize
  Apply business rules
  Run trusted operations
  Complete HTTP response
          |
          v
Page or Form
  Interpret request and operation results
  Show success, rejection, or error
  Refresh affected content where needed

This diagram illustrates responsibilities, not the literal sequence or names of Page Flow blocks.

Preparing the Cloud Flow Web Hook

Before connecting a Page, make sure the corresponding backend operation exists.

1. In Backend → Cloud Flow, create or select a Web Hook.
2. Give it a stable name representing its purpose, such as CreateRegistration or ApproveRequest.
3. Configure Hook HTTP Method to match the intended caller. The standard Page Flow Cloud Flow Invoke Hook block uses POST.
4. Define the required request fields and their expected values.
5. Implement validation, authorization, processing, and response completion in the Cloud Flow Editor.
6. Configure Access (Security) for the intended callers.
7. Save the Cloud Flow, confirm it is enabled, and test it using the development Web Hook endpoint.

A Web Hook's settings show its development test URL and published URL pattern. Use the URLs displayed by ioLoop instead of constructing them from assumptions. Renaming a Web Hook can change the endpoint used by Pages and external callers.

For the detailed Web Hook configuration and response controls, see Web Hooks and Managing Cloud Flow.

Calling a Web Hook with Page Flow

Page Flow provides dedicated blocks for invoking a configured Cloud Flow Web Hook and responding when the request completes.

Block or Result Path	Purpose
Cloud Flow Invoke Hook	Sends an HTTP POST request to a Cloud Flow Web Hook and provides success and failure paths.
Cloud Flow: URL of Web Hook	Supplies the URL of the selected Web Hook.
On success	Executes follow-up Page Flow logic for a successful invocation.
On failure	Executes the failure-handling path when the invocation fails.
HTTP Data	Provides response data within the supported success callback context.
HTTP Error	Provides error information within the supported failure callback context.

Configuring the Invocation

A typical Page Flow setup is:

1. Open the Page or Form in the Page Editor and select Flow.
2. Start from the relevant user event, such as a Button action or a Form submission workflow.
3. Collect the required values and prepare an object containing the request data.
4. Add Cloud Flow Invoke Hook and identify the intended Web Hook using the supported Web Hook URL block.
5. Supply the request data in the form expected by the invocation block.
6. In the supported success path, examine the returned HTTP Data and verify the business operation's result.
7. In the failure path, use HTTP Error to show an appropriate message and restore the Page's usable state.
8. Save Page Flow and Preview the interaction from the actual Page or Form.

For exact block inputs and behavior, see Page Flow General Blocks and HTTP and Web Hooks.

Waiting for Completion

Cloud Flow invocation is an asynchronous browser-side operation. Do not start the call and assume its result is already available in the next unrelated statement.

Put dependent work in the supported callback or completion path. For example, refresh a Data Table or display the final confirmation only after the backend operation reports success.

While the request is processing, consider disabling its Submit control or otherwise preventing repeated submissions. Restore an appropriate interactive state if the request fails. Preventing repeated clicks improves the user experience, but important duplicate-protection rules must also be enforced in the Backend.

Calling a Web Hook from Custom Frontend Code

A fully custom Page—including an SPA-style interface or a custom modal Form—can invoke Cloud Flow without using the visual Page Flow blocks.

Custom frontend JavaScript can use the same supported ioLoop Client API capabilities underlying built-in frontend components, or an appropriate HTTP request to the configured Web Hook endpoint. It can then manage its own loading, success, error, and retry behavior.

This approach is useful when:

• A custom interface owns its own event handling and Form state.
• The Page uses a JavaScript-driven component architecture.
• A custom modal needs the same trusted backend processing as an ioLoop Form.
• Custom code needs precise control over how a returned result changes the interface.

The caller must still use the correct Web Hook URL, HTTP method, supported request format, and access context. Custom JavaScript does not gain additional backend permissions by bypassing visual blocks. The Web Hook must enforce the same authorization and business rules for every caller.

Do not embed a Project User Web Hook Key in Page Flow, custom frontend JavaScript, HTML, or another browser-delivered asset. Web Hook Keys are intended for callers that can store credentials securely. Pages should use the signed-in Project User context and the supported Page Flow or Client API invocation methods.

Use the Client API for documented browser-side functions and Standards-Based Frontend for the broader implementation approach. For direct HTTP requests, follow the Web Hook's configured contract and applicable browser/network requirements rather than assuming an undocumented API signature.

Passing Request Data

Send the smallest set of values Cloud Flow needs to perform the operation.

Input	Example Use
Form fields	Attendee information for a registration request.
Record ID	Identifies the order, ticket, or record being acted on.
Selected item	Identifies the event or product associated with the action.
Requested operation	Identifies a supported operation or decision to process.
Workflow context	Provides necessary information from an earlier Page step.

For example, a registration request might send:

{
  "eventId": "event-123",
  "attendeeName": "Asha Patel",
  "attendeeEmail": "[email protected]"
}

This JSON is an illustrative request contract, not a built-in ioLoop request schema. Define the fields expected by your own Web Hook and prepare the frontend input accordingly.

What Not to Trust

Cloud Flow must not assume that browser-supplied values are authoritative. In particular:

• A user ID or User Group supplied as plain input is not proof of identity or membership.
• A record ID is not proof that the caller owns or may modify that record.
• A price, discount, capacity, or status submitted by the browser is not a trusted business decision.
• A hidden Form field or disabled Button does not protect the underlying operation.

Use the available trusted request context, Database records, and relevant Backend rules to verify these conditions. Do not send secret keys or Connection credentials from the browser.

Working with Modal Forms

A Cloud Flow call can be part of either a Table-Backed Form workflow or a Custom Form workflow. Use Form Page Flow when the Form needs additional processing around validation or submission.

The opening Page and the Form have different responsibilities:

Component	Typical Responsibility
Opening Page	Opens the modal, supplies shared context or edit data, and refreshes surrounding content after an appropriate result.
Form	Initializes fields, collects user input, validates values, and coordinates submission where configured.
Cloud Flow Web Hook	Processes the trusted operation and returns an outcome.

Edit data identifies and initializes the record being edited. Shared context is additional information passed from the opening Page and can be used in New, Edit, or Custom Form workflows. They are not interchangeable.

For example, a New Registration Form may receive a selected event as shared context even though it is creating a new record. The Form can pass the event identifier and attendee details to the Web Hook; Cloud Flow must still verify that the event exists and accepts registrations.

Do not close the modal or report submission success merely because the Web Hook request was started. Coordinate the Form's success/error state and the opening Page's response with the confirmed operation outcome.

See Opening Forms as Modals, Form Page Flow, and Forms and Widgets.

Interpreting Cloud Flow Results

A frontend caller must distinguish the HTTP invocation outcome from the application operation outcome.

Result Layer	What It Tells You
HTTP status and transport	Whether the HTTP request completed successfully according to the endpoint's response.
Application result	Whether the requested business operation actually completed as intended.

For example, a Web Hook may return an HTTP response successfully while its application data reports that registration was rejected because the event is full. In that case, the Page must not show a successful registration confirmation.

ioLoop Result Objects commonly use status, data, and err to describe application-level outcomes. A Web Hook may use such an object when it is the agreed response contract, but not every HTTP or Cloud Flow response automatically has this shape.

An illustrative application response is:

{
  "status": true,
  "data": {
    "registrationId": "REG-1042"
  },
  "err": ""
}

When handling the response:

1. Check the supported Page Flow success or failure path, or the equivalent result in custom JavaScript.
2. If the invocation succeeded, interpret the application response according to the Web Hook's contract.
3. Confirm that the operation succeeded before changing the Page to a completed state.
4. Use returned data only after confirming it is present and appropriate for the UI.
5. Handle rejections and technical errors separately where useful.

User-Facing Feedback

Situation	Example Message
Operation completed	Registration received. Your confirmation number is REG-1042.
Business rule rejected the action	This event is no longer accepting registrations.
Access denied	You don't have permission to complete this action.
Network or server failure	We couldn't complete the request. Please try again.
Required information missing	Complete the required fields before continuing.

Keep private diagnostic details in appropriate backend logs, not in messages displayed to visitors.

Example: Event Registration with Capacity Enforcement

Consider a public event Page where visitors register for events with limited capacity.

1. Display the Event

Use permitted frontend Database operations or configured data-driven components to show the event name, description, and current availability. Availability displayed in the browser is informational and can become outdated.

2. Collect the Registration

A Button opens a registration Form. The opening Page provides the selected event as shared context. The Form collects the attendee's information and performs immediate validation.

3. Call Cloud Flow

The Form's Page Flow invokes a CreateRegistration Web Hook with the required attendee and event values. The Form shows a processing state while waiting for the result.

4. Perform Trusted Processing

Conceptually, Cloud Flow should:

Receive registration request
  Validate required fields and event ID
  Verify applicable permissions and eligibility
  Check registration status and remaining capacity
  If the request is not allowed
    Return an appropriate rejection
  Otherwise
    Create the permitted registration
    Return confirmation information

This is a conceptual sequence, not a literal block implementation. If multiple users can register simultaneously, capacity enforcement must account for concurrency. A separate capacity read followed by a create operation should not be assumed to be an automatic atomic transaction.

5. Handle the Outcome

• On confirmed success, show the registration confirmation, close or update the Form as configured, and refresh the displayed event information.
• On business rejection, keep the user informed and avoid creating the appearance that the registration succeeded.
• On technical failure, provide recovery guidance and restore appropriate controls without duplicating a completed operation.

The same overall behavior can be implemented using an ioLoop modal Form and Page Flow blocks or a fully custom JavaScript modal using the supported Client APIs.

Access and Security

Cloud Flow's trusted execution environment does not automatically authorize each operation.

For Web Hooks, Access (Security) controls which callers may invoke the endpoint under its configured access model. Cloud Flow logic must separately validate the requested operation and its target records.

For protected workflows:

• Verify the caller's authenticated context where applicable.
• Recheck record ownership, User Group membership, and business rules using trustworthy information.
• Use configured Connections for private credentials.
• Return only the records and fields the caller should receive.
• Do not expose confidential files or table records through a broadly accessible endpoint.
• Consider duplicate requests, overlapping operations, and potentially expensive public calls.

A Page's access restriction, hidden Button, or browser-side validation is not sufficient to secure a Web Hook that can be called independently of that Page.

For details, see Access Security and Table Access.

Previewing, Testing, and Publishing

Test through the actual Page or Form that will invoke the Web Hook, not solely from the Cloud Flow Editor.

The Project Editor provides development Web Hook endpoints and a Cloud Flow test runtime. Use the appropriate development endpoint and verify that the test runtime is available when needed. After publishing, the live application uses the corresponding published backend endpoint.

During Preview, built-in Database operations automatically use the Project's development database. External Connections and manually configured service calls require separate attention: Preview does not necessarily put third-party services into test mode.

Test Case	What to Verify
Valid request	Cloud Flow completes the intended operation and the Page shows the correct result.
Missing or invalid input	The request is rejected safely and the user can correct it.
Business rejection	The Page does not mistake a valid HTTP response for a completed business operation.
Unauthorized caller	Protected data is not exposed and no unauthorized change occurs.
Duplicate submission	Repeated requests do not create unintended duplicate records or external actions.
Backend failure	The UI reports failure without falsely claiming success.
Page refresh	Data Tables, Data Design, or summary values update after confirmed changes.
Environment	Development and published URLs, Database data, and external provider modes are correct.

Use Testing and Logs to inspect test and live behavior. After publishing, use Launch Project to verify the released interaction.

Troubleshooting

Problem	What to Check
The Web Hook is not invoked	Selected Web Hook, enabled state, HTTP method, URL, access configuration, and test runtime.
Cloud Flow receives missing data	Request object, field names, Form values, and whether the correct input was supplied to the call.
The request is denied	Web Hook Access (Security), authenticated context, and operation-specific authorization.
The UI shows success for a rejected action	HTTP success handling versus the application-level result.
The Page does not refresh	Whether refresh or update logic runs after confirmed success in the correct callback path.
The request is sent more than once	Repeated event handlers, multiple clicks, retries, and Backend duplicate protection.
The workflow works in Preview but fails when published	Web Hook URL, production records, published configuration, live Connections, and Cloud Flow logs.
A custom frontend request fails	Configured endpoint method, access context, request format, and browser/network restrictions.

Start with a known request and compare what the frontend sent, what Cloud Flow logged, and what the caller received.

Good Practices

• Keep the interface and backend responsibilities distinct. The Page coordinates interaction; Cloud Flow enforces trusted rules.
• Define a clear request and response contract. Make required inputs, application outcomes, and error behavior predictable.
• Use the documented invocation blocks or Client APIs. Choose visual Page Flow or custom code based on maintainability.
• Keep requests minimal. Send what the operation needs, not unnecessary records or private information.
• Wait for completion. Use supported success/failure paths rather than assuming an asynchronous operation is finished.
• Confirm business success. A successful HTTP request is not enough when the operation can be rejected.
• Handle repeated requests safely. Combine useful frontend prevention with Backend duplicate protection.
• Test the full workflow. Include failures, permissions, and production-environment differences.

Common Mistakes

Avoid these patterns:

• Calling Cloud Flow for every permitted client-side Database operation.
• Putting trusted business rules or secrets in Page Flow or browser-side Custom Code.
• Treating browser-provided record IDs, roles, or prices as authoritative.
• Calling a Web Hook with an incompatible HTTP method or an outdated URL.
• Showing a final success state before the backend confirms completion.
• Treating HTTP success and application success as the same result.
• Forgetting to handle the invocation failure path.
• Closing a modal or refreshing Widgets before the operation completes.
• Assuming Cloud Flow operations cannot affect live external services during development testing.
• Testing only through the Cloud Flow Editor instead of the real Page or Form.

Page-to-Cloud Flow integrations work best when the frontend sends a well-defined request, the backend performs the trusted operation, and the frontend interprets the completed result before updating the user experience.

Technical Reference

• Page Flow General Blocks
• Page Flow HTTP and Web Hooks Blocks
• Cloud Flow HTTP and Web Hooks Blocks
• Result Objects
• Client API
• Server API

Related Topics

• Page Flow
• Data and Cloud Flow
• Opening Forms as Modals
• Form Page Flow
• Web Hooks
• Access Security
• Testing and Logs
• Using Database