Build and Script Execution API

This API allows you to discover and execute project-specific build tasks and custom scripts.

The process is a two-step workflow:

1. Discover: First, use the GET /sources REST endpoint to find all available build files (e.g., pom.xml) and scripts (e.g., *.nss). This response provides a list of specific actions you can take.
2. Execute: Then, use the unique WebSocket execute link provided for each action to run the task and stream its log output in real-time.

---

1. Discovering Build Files and Scripts

The GET /sources endpoint scans the project and expansion directories to identify executable tasks.

GET /sources

Retrieves a list of all detected build files and scripts, along with the actions that can be performed on them.

Request

curl http://localhost:8080/sources

Response Body Structure

The response contains buildFiles and scripts arrays within the data.properties object.

• buildFiles (Array<Object>): A list of detected build files (pom.xml, package.json, etc.).
  • id (String): The unique identifier for the build file, typically its path.
  • technology (String): The build technology identified (e.g., maven).
  • actions (Array<Object>): A list of executable tasks for this build file.
    • id (String): The unique identifier for the action.
    • name (String): The name of the action (e.g., package, install).
    • links.execute (String): The WebSocket URL endpoint used to run this action.
• scripts (Array<Object>): A list of detected custom script files (*.nss).
  • id (String): The unique identifier for the script, typically its path.
  • name (String): The file name of the script.
  • links.execute (String): The WebSocket URL endpoint used to run this script.

Example Response

Click to see the full example response

{
    "data": {
        "id": "sources",
        "type": "sources",
        "properties": {
            "buildFiles": [
                {
                    "id": "bookApp/pom.xml",
                    "type": "build-file",
                    "properties": {
                        "name": "bookApp/pom.xml",
                        "technology": "maven",
                        "actions": [
                            {
                                "id": "bookApp/pom.xml::package",
                                "type": "script",
                                "properties": {
                                    "name": "package"
                                },
                                "links": {
                                    "execute": "/tasks/build/bookApp%2Fpom.xml/actions/package"
                                }
                            },
                            {
                                "id": "bookApp/pom.xml::install",
                                "type": "script",
                                "properties": {
                                    "name": "install"
                                },
                                "links": {
                                    "execute": "/tasks/build/bookApp%2Fpom.xml/actions/install"
                                }
                            }
                        ]
                    }
                }
            ],
            "scripts": [
                {
                    "id": "scripts/rejuvenate.nss",
                    "type": "script",
                    "properties": {
                        "name": "scripts/rejuvenate.nss"
                    },
                    "links": {
                        "execute": "/tasks/scripts/scripts%2Frejuvenate.nss"
                    }
                }
            ]
        }
    },
    "server": {
        "version": "1.10.1"
    }
}

---

2. Executing a Task via WebSocket

To run any action or script discovered via the GET /sources endpoint, establish a WebSocket connection to its corresponding execute link.

Endpoint URL

The URL for each task is dynamic and is provided in the links.execute field of the action or script object.

Examples:

• Build Action: ws://localhost:8080/tasks/build/bookApp%2Fpom.xml/actions/package
• Script: ws://localhost:8080/tasks/scripts/scripts%2Frejuvenate.nss

Behavior

1. Connection: A client connects to the WebSocket endpoint.
2. Execution & Logging: The server immediately starts the task and begins streaming logs to the client as plain-text messages.
3. Termination: The server closes the connection automatically when the task finishes.

Connection Close Codes

The WebSocket close code indicates the outcome of the task.

Status Code	Reason	Description
1000	Normal Closure	The task completed successfully.
1011	Internal Server Error	The task failed due to an error. Review logs for details.