Connectors

The connector framework is Nembl's system for integrating with external services. Connectors handle authentication, API communication, and data mapping so that workflows can interact with third-party tools without custom code.

Connector Framework Overview

Each connector encapsulates:

• Authentication -- OAuth 2.0, API key, or custom auth, managed through Nembl's credential storage.
• Actions -- predefined operations the connector can perform (e.g., "send message", "create issue").
• Triggers -- events from the external service that can start a workflow (e.g., "new issue created").
• Data mapping -- translation between the external service's data format and Nembl's workflow variables.

How Connectors Fit in the Platform

Workflow Phase
  └── Connector Action
        └── Connector (e.g., Slack)
              └── External API call
                    └── Response → next workflow phase

Connectors are invoked during workflow execution. When a phase reaches a connector action, Nembl calls the external API, processes the response, and passes the result to the next phase.

Installing Connectors

From the Connector Catalog

1. Navigate to Settings > Connectors.
2. Click Add Connector.
3. Browse or search the connector catalog.
4. Click Install on the connector you need.
5. The connector appears in your installed list, ready for authentication.

Connector Categories

OAuth Flow

Most connectors use OAuth 2.0 for authentication, which provides scoped, revocable access without storing passwords.

Connecting via OAuth

1. Open the installed connector from Settings > Connectors.
2. Click Connect.
3. You are redirected to the external service's authorization page (e.g., Slack's "Allow Access" screen).
4. Authorize Nembl to access the required scopes.
5. You are redirected back to Nembl with the connection confirmed.

OAuth Token Lifecycle

• Access tokens are short-lived (typically 1 hour) and refreshed automatically.
• Refresh tokens are stored securely as secrets in your company namespace.
• If a refresh token expires or is revoked, Nembl marks the connector as disconnected and prompts you to re-authorize.

Reconnecting

If a connector becomes disconnected:

1. Navigate to Settings > Connectors.
2. The disconnected connector shows a warning badge.
3. Click Reconnect and complete the OAuth flow again.

Credential Management

API Key Connectors

For connectors that use API keys (PagerDuty, OpsGenie, Linear, Generic REST):

1. Open the connector.
2. In the Authentication section, click Set API Key.
3. Enter the key or select an existing secret.
4. Click Save.

Credential Storage

All credentials (OAuth tokens and API keys) are stored in AWS Secrets Manager under your company namespace:

nembl/{companyId}/connector-{connectorSlug}

Credentials are encrypted at rest and in transit. They are never exposed in logs, audit trails, or API responses.

Rotating Credentials

1. For API key connectors: generate a new key in the external service, update the secret in Nembl, verify the connection, then revoke the old key.
2. For OAuth connectors: click Reconnect to generate new tokens. The old tokens are automatically revoked.

Using Connectors in Workflow Phases

Adding a Connector Action

1. Open a workflow in the builder.
2. Select or create a phase.
3. Click Add Action > Connector Action.
4. Select the connector and action:

5. Map workflow variables to the action's input parameters.
6. Optionally map the response to workflow variables for use in subsequent phases.

Response Handling

Connector actions return data that can be used in later workflow phases:

Phase: "Create GitHub Issue"
  Action: GitHub → Create Issue
  Inputs:
    repo: "devopspolis/nembl"
    title: "{{ request.title }}"
    body: "{{ request.fields.description }}"
  Outputs:
    githubIssueUrl → {{ connectorResponse.html_url }}
    githubIssueNumber → {{ connectorResponse.number }}

Phase: "Notify Team"
  Action: Slack → Send Message
  Inputs:
    channel: "#engineering"
    message: "Created issue {{ githubIssueUrl }}"

Error Handling

When a connector action fails (e.g., external API returns an error):

• The workflow phase is marked as failed.
• The error details are logged in the workflow execution history.
• If the phase has a retry configuration, Nembl retries the action automatically.
• If retries are exhausted, the workflow follows the configured error path (if defined) or pauses for manual intervention.

Building Custom Integrations

For services without a dedicated connector, use the Generic REST API connector.

Configuring a Custom Connector

1. Install the Generic REST API connector.
2. Set the base URL, authentication method, and default headers.
3. In workflow phases, configure the HTTP method, path, headers, and body for each action.

Advanced: Custom Request Transformations

For complex integrations, use workflow data phases to transform data before and after connector calls:

Phase 1: "Prepare Payload" (Data Transform)
  → Format request data into the external API's expected structure

Phase 2: "Call External API" (Generic REST Connector)
  → POST the transformed data

Phase 3: "Process Response" (Data Transform)
  → Extract and format the response for use in the workflow

Monitoring Connector Health

Connection Status

From Settings > Connectors, each connector shows its current status:

Execution History

View connector action results from the workflow execution history:

• Which connector and action were called
• Request sent to the external API
• Response received
• Success or failure status
• Error details if failed

Best Practices

• Use dedicated service accounts. In the external service, create a service account specifically for Nembl rather than using a personal account.
• Grant minimal scopes. When authorizing OAuth connectors, review the requested scopes and ensure they match what your workflows need.
• Test connector actions. Before deploying a workflow with connector actions, test the phase individually to verify the integration works.
• Handle failures gracefully. Configure error paths in your workflow so that connector failures do not block the entire process.
• Monitor for disconnections. OAuth tokens can expire or be revoked by the external service. Check connector status weekly.
• Use the Generic REST connector as a last resort. Dedicated connectors handle pagination, rate limiting, and error handling automatically.