File Structure - Stackone

Connectors are organized into a main connector file and, optionally, partial files. Partial files can be used to split large connectors up into more manageable chunks for maintenance and are consumed in the StackOne platform as if it were a single configuration file.

Best practices

For maintaining connectors for development, use the directory structure below:

connectors/{provider}/
├── {provider}.connector.s1.yaml            # Main connector file (authentication, metadata)
├── {provider}.{resourceA}.s1.partial.yaml  # Partial file (actions grouped by resourceA)
├── {provider}.{resourceB}.s1.partial.yaml  # Partial file (actions grouped by resourceB)
└── {provider}.events.s1.partial.yaml       # Partial file (event handlers - if available)

Main connector file

The main connector file defines the top-level properties (see YAML Schema): connector metadata, authentication, and an actions block (plus an events block for webhooks) that reference the partial files. Partial files are referenced in the main file by the filename without the .s1.partial.yaml extension.

Parital files must be within the same folder as the main connector file.

# acme.connector.s1.yaml
StackOne: 1.0.0
...
actions:
  - $ref: acme.employees  # references acme.employees.s1.partial.yaml
  - $ref: acme.departments  # references acme.departments.s1.partial.yaml

events:
  setup: {...}
  router: {...}
  externalAccountIdExtractor: {...}
  actions:
    - $ref: acme.events  # references acme.events.s1.partial.yaml

Add references in alphabetical order for readability.

Partial files

Each partial file is a group of actions, e.g. grouped per resource.

# acme.employees.s1.partial.yaml
- actionId: list_employees
  ...

- actionId: get_employee
  ...

# acme.departments.s1.partial.yaml
- actionId: list_departments
  ...

- actionId: get_department
  ...

Event handlers are grouped the same way:

# acme.events.s1.partial.yaml
- actionId: employee_created
  actionType: event
  ...

- actionId: employee_updated
  actionType: event
  ...

YAML Schema

Full YAML schema for building connectors with field tables and examples.

​Best practices

​Main connector file

​Partial files

​Related

YAML Schema

Best practices

Main connector file

Partial files

Related