Building integrations

How to build a new integration

When building a new integration, furl provides tooling to ease the burden of generating boilerplate and get you to building the functionality you need quickly. Our tooling is spec driven; allowing the spec to drive what is to be generated and the hints for our Copilot to leverage when matching to the activities in your experience.

If you do not yet have access to the furl integration tooling, please request access in the Discord integration channel

Once the furl tooling is installed, it’s easy to start building a new integration with another tool:

1. Initialize the integration: go run cmd/furl/main.go init {integration_identifier}. This will create an integration directory and spec.yaml in pkg/integration_identifier.
2. Update the integration spec.yaml: Define integration details, connections, actions, and triggers as needed.

name: Example Integration
publisher: furl
connections:
  - id: oauth
    version: 0.0.1
    title: OAuth 2.0 (recommended)
    description: Slack OAuth 2.0 connection
    type: platform_oauth2_auth_code
actions:
  - id: example_action
    version: 0.0.1
    title: Example Action
    description: Run an example action
    inputs:
      - id: field_1
        type: string
        title: Field 1
        description: The first field
      - id: field_2
        type: string
        title: Field 2
        description: The second field
    outputs:
      - id: output_1
        type: string
        title: Output 1
        description: The first output
    hints:
      - Create a widget
      - Does a thing
triggers:
  - id: example_trigger
    version: 0.0.1
    title: Example Trigger
    description: Support an example trigger
    inputs:
      - id: input_1
        type: string
        title: Input 1
        description: The first input
    outputs:
      - id: output_1
        title: Output 1
        description: The first output
        type: string
    hints:
      - Create a widget
      - Does a thing

3. Generate the integration code: Run go run cmd/furl/main.go generate {integration_identifier}, resulting in generated files to implement:

4. Implement Connection(s): Modify create_connection.go for each connection type to initialize your client(s) for use by actions and triggers.
5. Implement Action(s) and Trigger(s): Modify run.go to implement the integration logic to achieve the outcome expected of the action and trigger. Remember to return Outputs so they can be used through an experience.

Adding a new action or trigger

When an integration already exists, it greatly reduces the amount of effort to add new actions and triggers. By updating the spec.yaml with the new action and regenerating, you are able to immediately start implementing the code:

1. Update spec.yaml: Add any new actions or triggers
2. Generate the integration: Run go run cmd/furl/main.go generate {integration_identifier}. This will only update generated files (.gen) and any new files that need added.
3. Implement the New Actions(s) and Trigger(s): Update the run.go for each new action or trigger. Test it out and contribute!