Devices rarely speak the protocol you wish they did. A meter answers DLMS, a legacy gateway needs a Telnet command, a sensor posts a binary frame nobody else understands. A connector function is your own JavaScript, running inside the platform, that translates between OpenGate and that reality.

No middleware to deploy, no service to keep alive: you POST the script, and OpenGate runs it at the moment the data or the operation passes through.

What one looks like

A connector function is a JSON document with a javascript field holding the code, plus the metadata that tells OpenGate when to run it:

{
  "name": "CollectionInfoConnectorFunction",
  "description": "Connector function for collected data",
  "operationalStatus": "DISABLED",
  "type": "COLLECTION",
  "southCriterias": [
    "http://collected/data",
    "mqtt://iot/collected"
  ],
  "javascript": "... javascript code ..."
}

Each function belongs to exactly one channel, and its name must be unique within that channel.

The three types

The type answers which direction is this translating?

flowchart TB
    APP["Back-office application"] -->|"launches an operation"| REQ["REQUEST"]
    REQ -->|"speaks the device protocol"| DEV["Device"]
    DEV -->|"answers the operation"| RES["RESPONSE"]
    DEV -->|"pushes data"| COL["COLLECTION"]
    RES -->|"operation result"| OUT["Operation updated"]
    COL -->|"data points"| STO["Platform storage"]

    classDef cf fill:#addcf8,stroke:#2b7cb8,color:#000,font-weight:bold
    class REQ,RES,COL cf

The three blue boxes are the connector functions: your JavaScript, at the point where each translation happens.

Type Runs when Must return
REQUEST The platform has an operation to send to the device Nothing is required. Return null, or omit the return, and the operation stays open until a response arrives. Return the response object and the operation finishes right there
RESPONSE Something arrives from the device at a south URI, answering an operation The OpenGate standard response object. Return nothing and no operation update happens
COLLECTION Something arrives from the device at a south URI, carrying data The OpenGate standard collection object. Return nothing and nothing is collected

The core JavaScript API gives you the response and collection objects to build those returns without assembling JSON by hand.

Criteria: how OpenGate picks your function

Criteria Used by Meaning
northCriterias REQUEST only, mandatory Matches the operation coming from the platform. Two functions cannot share the same list
southCriterias RESPONSE and COLLECTION, mandatory One or more URIs the device talks to. Each URI can belong to only one connector function

A REQUEST function also needs operationName, which must be an operation type you are allowed to use, and must leave southCriterias unset. RESPONSE and COLLECTION functions are the mirror image: south criteria set, northCriteria and operationName unset.

South criteria are URIs carrying the protocol, and the accepted set is configurable:

https://   mqtts://   wss://   snmps://   dlms://   coaps://

When it runs, and on which devices

operationalStatus is what keeps a half-written function from touching your fleet:

Value OpenGate runs the function
DISABLED Never
TEST Only on devices whose operational status is TEST
PRODUCTION Only on devices whose operational status is PRODUCTION

The natural order is therefore: create it DISABLED, move it to TEST against a test device, and only then to PRODUCTION.

Chaining functions

A function can hand over to another when it finishes, using cf.response and cf.collection. Only these hand-offs are honoured — anything else is silently ignored:

From Can invoke
REQUEST RESPONSE, COLLECTION, or both
RESPONSE COLLECTION
COLLECTION Nothing

That is what lets a single device message both close an operation and collect the readings it carried. See Concatenated Connector Functions.

Where to go next

To Read
Write the script: what it receives, what it must return Core JavaScript API
Talk a specific protocol: DLMS, SNMP, SSH, MQTT… Protocol APIs
Clone a ready-made function instead of writing one Catalog API
Debug a function that is already running Debugging

Managing them over REST

/north/v80/connectorFunctions/provision/organizations/{organizationName}/channels/{channelName}
Action Profiles allowed
CREATE, UPDATE, DELETE admin, admin_domain, super_admin_domain, root
GET, list Any profile

Once created, identifier and type are immutable. Everything else can be updated.

Create a COLLECTION function in a channel:

curl -X POST 'https://api.opengate.es/north/v80/connectorFunctions/provision/organizations/{organizationName}/channels/{channelName}' \
  -H 'X-ApiKey: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d @connector-function.json

A valid request returns 201 with a Location header carrying the identifier of the new function.

List the connector functions of a channel:

curl 'https://api.opengate.es/north/v80/connectorFunctions/provision/organizations/{organizationName}/channels/{channelName}' \
  -H 'X-ApiKey: <your-api-key>'
The REST API barely reads your JavaScript

Creating or updating a connector function performs only minimal JavaScript parsing. A script that is syntactically odd but parseable will be accepted and fail at runtime, which is why TEST status and debugging matter.

API specification