Building Your First Cereal Script

In this tutorial, we will guide you through the process of creating your very first script for the Cereal Automation platform. By the end of this guide, you will have a working script that you can run and test locally.

Prerequisites

Before we begin, ensure you have the following installed:

• Java Development Kit (JDK) 17 or higher.
• IntelliJ IDEA (Community or Ultimate edition recommended).
• Git for version control.

Step 1: Setting up the Project

The easiest way to start is by using the official Cereal Script Template. This template comes pre-configured with the necessary dependencies and build scripts.

1. Use the Template: Navigate to the Script-Template repository on GitHub.
2. Create Repository: Click the Use this template button to create a new repository under your own account. Name it something like my-first-cereal-script.
3. Clone the Repository: Clone your newly created repository to your local machine using your terminal or Git client.

   git clone https://github.com/YourUsername/my-first-cereal-script.git
   

4. Open in IntelliJ: Open IntelliJ IDEA and select Open, then navigate to the folder where you cloned the repository.

Step 2: Project Configuration

Once the project is open, we need to configure a few metadata files to identify your script.

1. Update Build Settings

Open the settings.gradle.kts file in the root directory. Change the rootProject.name to match your script’s name.

rootProject.name = "MyFirstScript"

2. Configure the Manifest

The manifest.json file is crucial as it tells Cereal about your script. Open src/main/resources/manifest.json and update the fields:

{
  "package_name": "com.yourname.script.first",
  "name": "My First Script",
  "version_code": 1,
  "script": "com.yourname.script.first.MyFirstScript"
}

• package_name: This must be unique. It is recommended to use reverse domain notation (e.g., com.yourname.script.first).
• name: The display name of your script.
• version_code: An internal version number (integer) that must be incremented for each release.
• script: The fully qualified class name of your main script class.

3. Rename the Package

Now, rename the default package structure to match the package_name you defined in the manifest.

1. In the Project view, expand src/main/kotlin.
2. Right-click on com.cereal.script.sample -> Refactor -> Rename.
3. Rename it to com.yourname.script.first (or whatever you chose).

Step 3: Defining Script Configuration

Scripts often require input from the user. This is handled by the ScriptConfiguration interface.

1. Locate SampleConfiguration.kt in your package.
2. Right-click and Refactor -> Rename it to MyScriptConfiguration.kt.
3. Replace the content with the following:

package com.yourname.script.first

import com.cereal.api.script.configuration.ScriptConfiguration
import com.cereal.api.script.configuration.ScriptConfigurationItem

interface MyScriptConfiguration : ScriptConfiguration {

    @ScriptConfigurationItem(
        keyName = "greeting_message",
        name = "Greeting Message",
        description = "The message to display in the logs.",
        defaultValue = "Hello, Cereal World!"
    )
    fun greetingMessage(): String
}

This defines a single configuration item that allows the user to input a greeting message.

Step 4: Implementing the Script Logic

Now for the fun part: writing the script logic.

1. Locate SampleScript.kt.
2. Rename it to MyFirstScript.kt.
3. Update the code to implement your logic:

package com.yourname.script.first

import com.cereal.api.script.Script
import com.cereal.api.script.ScriptComponentProvider
import com.cereal.api.script.execution.ExecutionResult
import kotlinx.coroutines.delay

class MyFirstScript : Script<MyScriptConfiguration> {

    override suspend fun onStart(configuration: MyScriptConfiguration, provider: ScriptComponentProvider): Boolean {
        provider.logger().info("Starting My First Script...")
        // Return true to indicate the script is ready to start
        return true
    }

    override suspend fun execute(
        configuration: MyScriptConfiguration,
        provider: ScriptComponentProvider,
        statusUpdate: (String) -> Unit
    ): ExecutionResult {
        // 1. Get the configuration value
        val message = configuration.greetingMessage()

        // 2. Log the message
        provider.logger().info("User says: $message")

        // 3. Update the status shown in the UI
        statusUpdate("Processing greeting...")
        
        // 4. Simulate some work
        delay(1000)

        // 5. Return success
        return ExecutionResult.Success("Script completed successfully!")
    }

    override suspend fun onFinish(configuration: MyScriptConfiguration, provider: ScriptComponentProvider) {
        provider.logger().info("Cleaning up...")
    }
}

Understanding the Methods

• onStart: Runs once when the script is initialized. Use this for validation or setup. Returning false aborts the script.
• execute: The main loop of your script. It returns an ExecutionResult which determines if the script should repeat (Loop), finish (Success), or fail (Error).
• onFinish: Runs when the script stops, allowing for cleanup.

Step 5: Testing Your Script

You don’t need to upload your script to Cereal to test it. You can run it locally using the provided test harness.

1. Open src/test/kotlin/com/yourname/script/first/TestSampleScript.kt.
2. Rename it to TestMyFirstScript.kt.
3. Update the test class to use your new Script and Configuration classes:

package com.yourname.script.first

import com.cereal.api.script.test.TestScriptRunner
import kotlinx.coroutines.runBlocking
import org.junit.jupiter.api.Test

class TestMyFirstScript {

    @Test
    fun testScript() = runBlocking {
        // Create an instance of your script
        val script = MyFirstScript()
        
        // Run the script using the TestRunner
        TestScriptRunner.run(script)
    }
}

4. Run the test by clicking the green play icon next to the testScript function.
5. Check the Run console in IntelliJ. You should see your log messages:

   [INFO] Starting My First Script...
   [INFO] User says: Hello, Cereal World!
   [INFO] Cleaning up...
   

Next Steps

Congratulations! You’ve built and tested your first Cereal script.

• Learn how to Publish your script.
• Explore available Components like Notifications and User Interaction.
• Read about Advanced Configuration.