> 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.md).

# Service Commissioning Files

Describe a service in one YAML file, from the connections and endpoints it needs to the users and permissions it creates.

A service commissioning file is a YAML file that serves as the blueprint of a [service](https://docs.cybus.io/data-flows/services.md). It defines how Connectware configures and deploys the service, and holds the following:

* All resources that make up the service, such as connections, endpoints, mappings, containers, and users
* The configuration of each resource
* The relationships and dependencies between the resources

When you enable the service, Connectware reads the service commissioning file. It automatically creates all specified resources and configures them according to the defined parameters.

Parameters let you install the same service commissioning file several times with different values. For example, you install it once per machine and enter a different device address each time.

To draft or edit service commissioning files with an AI tool, see [Writing Service Commissioning Files with AI Assistance](https://docs.cybus.io/guides/operations/writing-service-commissioning-files-with-ai-assistance.md).

## Sections of a Service Commissioning File

A service commissioning file has the following top-level sections. Each section has its own page with the details:

| Section                                                                                    | Required     | Content                                                                                                           |
| ------------------------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| [version](https://docs.cybus.io/data-flows/service-commissioning-files/version.md)         | Optional     | The format of the service commissioning file. The only valid value is `1`.                                        |
| [description](https://docs.cybus.io/data-flows/service-commissioning-files/description.md) | **Required** | What the service does. Connectware shows it in the Admin UI.                                                      |
| [metadata](https://docs.cybus.io/data-flows/service-commissioning-files/metadata.md)       | **Required** | The name of the service, and optionally its version, provider, homepage, and icon.                                |
| [parameters](https://docs.cybus.io/data-flows/service-commissioning-files/parameters.md)   | Optional     | Values that you use throughout the service. You enter them when you install or reconfigure the service.           |
| [definitions](https://docs.cybus.io/data-flows/service-commissioning-files/definitions.md) | Optional     | Values that you reuse within the service commissioning file.                                                      |
| [resources](https://docs.cybus.io/data-flows/service-commissioning-files/resources.md)     | **Required** | What Connectware creates for the service, such as connections, endpoints, mappings, and Unified Namespace assets. |

## Example

The following service commissioning file reads a temperature from a Modbus/TCP device and uses every section:

{% code title="temperature-monitoring.yml" lineNumbers="true" %}

```yaml
version: 1

description: >
  Reads the temperature from a Modbus/TCP device and publishes it on an MQTT
  topic.

metadata:
  name: Temperature Monitoring
  version: 1.0.0

parameters:
  deviceAddress:
    type: string
    default: 192.168.1.100
    description: IP address of the Modbus/TCP device

definitions:
  pollingInterval: 1000

resources:
  modbusConnection:
    type: Cybus::Connection
    properties:
      protocol: Modbus
      connection:
        host: !ref deviceAddress # the address you enter at installation
        port: 502

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

{% endcode %}

## Size Limit

Connectware stores the configuration of each resource internally as one message of up to 32 MB. Keep the configuration of each resource below this size, for example the content of a [Cybus::File](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-file.md).


---

# 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.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.
