> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/data-flows/service-commissioning-files/resources.md).

# Resources

Declare the connections, endpoints, mappings, containers, and other resources that Connectware creates for your service.

The resources section holds the resources of your service. It can hold any number of resources. The resource type of each entry decides what Connectware creates when you enable the service. Examples are a connection to a machine, a user, or a Docker container.

* **Required**
* Type: `object`, with one entry per resource

Resources work together through references. For example, an endpoint uses a connection to read a data point. A mapping then routes the data of the endpoint to the topics that your applications use.

## Resource Types

The resource type identifies what kind of resource you declare, such as a connection or a Docker container. You set it with the `type` property of the resource. The resource type also decides which properties the resource takes.

The following resource types are available:

| Resource Type                                                                                                       | What It Does                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Cybus::Asset](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-asset.md)               | Declares one real thing in a Unified Namespace, such as a pump.                                                                                                                      |
| [Cybus::Connection](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-connection.md)     | Connects to a machine or an external system over a protocol, such as OPC UA or Modbus/TCP.                                                                                           |
| [Cybus::Container](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-container.md)       | Runs a Docker container that communicates with Connectware over MQTT.                                                                                                                |
| [Cybus::Endpoint](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-endpoint.md)         | Addresses one data point on a connection and maps it to an MQTT topic.                                                                                                               |
| [Cybus::File](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-file.md)                 | Writes a file into a volume.                                                                                                                                                         |
| [Cybus::IngressRoute](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-ingressroute.md) | Makes a port or path of a service container reachable from outside Connectware.                                                                                                      |
| [Cybus::Link](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-link.md)                 | Adds a link to a web resource, such as a web interface that a container serves.                                                                                                      |
| [Cybus::Mapping](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-mapping.md)           | Routes data from one or more MQTT topics to another topic.                                                                                                                           |
| [Cybus::Model](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-model.md)               | Describes one type of asset, such as a pump.                                                                                                                                         |
| [Cybus::Mount](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-mount.md)               | Places an asset in a namespace, or below a parent asset.                                                                                                                             |
| [Cybus::Namespace](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-namespace.md)       | Declares one Unified Namespace: its root, its tree, and its policies.                                                                                                                |
| [Cybus::Node](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-node.md)                 | Provides one data point on a [Cybus::Server](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-server.md), so that external clients can read or write it. |
| [Cybus::Role](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-role.md)                 | Defines a reusable set of permissions for users.                                                                                                                                     |
| [Cybus::Server](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-server.md)             | Runs a server, such as an OPC UA server, that external clients connect to. Nodes provide its data.                                                                                   |
| [Cybus::User](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-user.md)                 | Creates a user and optionally grants it permissions.                                                                                                                                 |
| [Cybus::Volume](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-volume.md)             | Provides persistent storage for containers.                                                                                                                                          |

For nodes and servers, the resource type also names the protocol, such as `Cybus::Node::Opcua` or `Cybus::Server::Http`. See [Cybus::Node](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-node.md#node-types) and [Cybus::Server](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-server.md#server-types).

The Namespace, Model, Asset, and Mount resources declare a Unified Namespace. See [Unified Namespace](https://docs.cybus.io/unified-namespace/unified-namespace.md).

## Declaring a Resource

Each entry has a resource ID as its key, a resource type, and usually properties. The following example declares a Modbus/TCP connection and an endpoint that reads one register through it:

{% code lineNumbers="true" %}

```yaml
resources:
  modbusConnection:
    type: Cybus::Connection
    properties:
      protocol: Modbus
      connection:
        host: 192.168.1.100
        port: 502

  temperature:
    type: Cybus::Endpoint
    properties:
      protocol: Modbus
      connection: !ref modbusConnection
      subscribe:
        fc: 3
        address: 1
        length: 2
        dataType: floatBE
```

{% endcode %}

In this example, `modbusConnection` and `temperature` are resource IDs. `Cybus::Connection` and `Cybus::Endpoint` are resource types, which also decide the properties that a resource takes. Everything under `properties` configures the resource. The `!ref modbusConnection` of the endpoint references the connection by its resource ID.

## Resource ID

A resource ID is the name that identifies a resource within a service commissioning file, so it must be unique there. You set it as the key of the resource, such as `modbusConnection`. Other resources in the same service commissioning file use it to reference the resource with `!ref`.

To reference a resource of another service, put the service ID of that service and a double colon (`::`) in front of the resource ID. For example, `serviceA::resourceB` references the resource `resourceB` of the service `serviceA`. In a `!ref`, take the service ID from a parameter, for example `!ref '${otherService}::modbusConnection'`. See [Inter-Service Referencing](https://docs.cybus.io/data-flows/services/inter-service-referencing.md).

### Resource ID Naming Requirements

A resource ID starts with an ASCII letter or a digit. After that, it can contain uppercase and lowercase ASCII letters, digits, underscores (`_`), and periods (`.`). This matches the regular expression `^[a-zA-Z0-9][a-zA-Z0-9_.]*$`.

Hyphens (`-`) are not allowed. Connectware uses them to join the service ID and the resource ID, for example in the names of Docker containers.

The resource ID of a [Cybus::Asset](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-asset.md) must not contain a period either, because a period separates the asset from its property in a reference.

### Resource ID Length Restrictions

For the maximum length of service IDs and resource IDs, see [Length Restrictions](https://docs.cybus.io/data-flows/services/serviceid.md#service-id-length-restrictions).

## Resource Properties

Resource properties are the settings of a resource, such as the host and the port of a connection. You set them under the `properties` key. Each resource type page lists the properties of its type. If a resource needs no properties, leave out the `properties` key.

A property value can be any YAML value: a string, a number, a boolean, a list, or an object. You can also insert values with the following tags:

* `!ref` inserts a [parameter](https://docs.cybus.io/data-flows/service-commissioning-files/parameters.md#reference-method-ref), a [definition](https://docs.cybus.io/data-flows/service-commissioning-files/definitions.md), a [global pre-defined parameter](https://docs.cybus.io/data-flows/service-commissioning-files/parameters.md#global-pre-defined-parameters), or a reference to another resource.
* `!sub` inserts the values of parameters, definitions, global pre-defined parameters, and references to other resources into a string, for example `!sub '${myVolume}:/data'`. See [String Substitution Method](https://docs.cybus.io/data-flows/service-commissioning-files/parameters.md#string-substitution-method-sub).
* `!merge` combines the properties of object definitions with properties that you add. See [Merging Definitions](https://docs.cybus.io/data-flows/service-commissioning-files/definitions.md#merging-definitions).

To transform data, add [Rule Engine](https://docs.cybus.io/data-flows/rule-engine.md) rules to the `rules` property of an endpoint or a node, or of each entry in the `mappings` of a mapping.

The following excerpt shows each kind of value. It is not a complete resource:

{% code lineNumbers="true" %}

```yaml
properties:
  name: Filling line # string
  label: '[line 1] filling station' # string that starts with a special character, in quotes
  port: 502 # number
  enabled: true # boolean
  hosts: # list
    - 192.168.1.100
    - 192.168.1.101
  host: !ref deviceAddress # parameter
  connection: !ref modbusConnection # another resource
  topic: !sub '${Cybus::MqttRoot}/temperature' # string substitution
  options: !merge # merge of a definition with an added property
    connectionDefaults:
    timeout: 5000
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cybus.io/data-flows/service-commissioning-files/resources.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
