Connectors and the response contract

Triggering a connector from script

Project.TriggerConnectorByName("MyTrigger");

TriggerConnectorByName(name) returns false if EnableHttpApi is off or the connector does not exist. Internally it issues a fire-and-forget GET /api/connector/trigger?name={name} against the local HTTP API.

Handling a connector trigger in script

When /api/connector/trigger?name=Foo arrives, the engine looks for OnConnectorFoo in the script and calls it with the original query string as a single string argument:

function OnConnectorFoo(query) {
    Logger.Info("Connector Foo invoked: " + query);
}

Script return-value contract

The same contract applies to /api/connector/trigger and /api/scriptengine/execute. The mapping from the JS function's return value to the HTTP response is:

Script returns	HTTP response
`string` (non-empty)	`200 OK`, `Content-Type: text/plain`, body = string
object / array	`200 OK`, `Content-Type: application/json`, body = JSON-serialized value
object with a numeric `httpStatus` field, with a `body` field — explicit envelope `{ httpStatus, body, contentType? }`	status from `httpStatus`; body = `body` (string → `text/plain`, object → `application/json`); content type override via optional `contentType` (full header value, e.g. `"Content-type: text/html; charset=utf-8"`)
object with a numeric `httpStatus` field, no `body` field — hybrid shape `{ ..., httpStatus }`	status from `httpStatus`; body = the remaining fields (everything except `httpStatus` and `contentType`) serialized as JSON
`undefined`, `null`, empty string, or no return statement	falls back to the endpoint's default message

A non-numeric httpStatus is treated as a regular payload field (the whole object is serialized as JSON 200 OK and a warning is logged).

// Plain text
function OnConnectorStartDemo() { return "Demo started"; }
// → 200 text/plain "Demo started"

// JSON 200 OK
function OnConnectorListScenes() { return Project.Scenes.map(s => s.Name); }
// → 200 application/json ["Main","Standby"]

// Hybrid: error response with custom status
function OnConnectorShowMultipliers() {
    return { result: "error", message: "Demo mode active", httpStatus: 400 };
}
// → 400 application/json {"result":"error","message":"Demo mode active"}

// Explicit envelope: HTML body with custom status
function OnConnectorStatusPage() {
    return {
        httpStatus: 200,
        body: "<h1>Composer is up</h1>",
        contentType: "Content-type: text/html; charset=utf-8"
    };
}
// → 200 text/html <h1>Composer is up</h1>