Skip to content

User Interaction Component

The User Interaction component lets your script ask for input during execution. It provides two separate capabilities: - Web view interactions for displaying web content (showUrl, showHtml). - A simple Continue button for lightweight acknowledgements (showContinueButton).

Web View Interactions (showUrl, showHtml)

When implementing your script's onStart, execute, or onFinish methods, you can access the User Interaction component through the provided ComponentProvider.

fun execute(provider: ComponentProvider) {
    val userInteraction = provider.userInteraction()

    // Show a URL and wait for specific condition
    val urlResponse = userInteraction.showUrl("Login Page", "https://example.com/login") {
        it.url.contains("success") // Terminates when URL contains "success"
    }

    // Show HTML content and wait for form submission
    val htmlResponse = userInteraction.showHtml("Input Form", htmlContent) {
        it.url.contains("form-submitted")
    }

    // Process the response
    processUserResponse(htmlResponse)
}

Example: HTML form flow

The following example shows how to create a simple HTML form to ask the user for a confirmation code:

val html = """
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Confirmation Code</title>
</head>
<body>
    <h2>Enter Confirmation Code</h2>
    <form action="https://www.cereal-automation.com" method="POST">
        <input type="text" name="confirmationCode" placeholder="Enter code here" required>
        <button type="submit">Submit</button>
    </form>
</body>
</html>
"""

// Show the HTML and wait for the form submission
val request = provider.userInteraction().showHtml("Confirmation Code", html.trimIndent()) {
    it.url.contains("cereal-automation.com")
}

// Extract and use data from the response
provider.logger().info("Form submitted to: ${request.url}")
provider.logger().info("Request method: ${request.method}")
provider.logger().info("Form data: ${request.postData}")

Continue Button

Use showContinueButton() when you only need the user to acknowledge and allow the script to proceed, without navigating to a web page or submitting a form.

Behavior: - Renders a Continue button inside the task row. - Suspends execution until the user clicks the button, then resumes. - Returns: None (suspends until the user clicks Continue).

Example:

// Inform the user about the next step
provider.logger().info("Ready to proceed to the next step. Click Continue when you are ready.")

// Wait until the user clicks Continue
provider.userInteraction().showContinueButton()

// Continue with your logic
performNextStep()

Processing Responses for showUrl/showHtml

The response object returned by showUrl and showHtml contains valuable information about the user's interaction:

  • url - The final URL that triggered the termination condition
  • method - HTTP method used (GET, POST, etc.)
  • requestHeaders - Headers included in the request
  • postData - Data submitted through forms or other POST requests

Best Practices

  • Design simple, clear interfaces for user input
  • Provide clear instructions within the HTML/web page
  • Include validation to ensure data quality
  • Set appropriate termination conditions to detect when user input is complete
  • Keep UI elements consistent with Cereal's design where possible
  • Use showContinueButton() for lightweight acknowledgements (e.g., "Press the confirmation link in the email you received, then continue").