Interface parameters

Interface parameters define the input fields that appear in the connector configuration UI. Use these parameters to allow users to customize connector behavior—such as filtering data or providing credentials—without modifying the underlying Blueprint YAML.

Parameter structure

Interface parameters are defined within the interface_parameters block of your Blueprint. They are organized by sections to group related inputs logically in the UI.

For example,

interface_parameters:
  section:
    source:
      - name: "parameter_name"
        type: "parameter_type"
        # Type-specific configuration

Parameter types

Refer the following table to determine the correct parameter type for your use case.

Type	Description	Use case
string	Text input field	Base URLs, filters, custom values
authentication	Credential collection	API tokens, OAuth2, Basic Auth
date_range	Start/end date picker	Time-bounded data fetching
list	Dropdown selection	Predefined options
integer	Numeric input	Page sizes, limits
boolean	True/False checkbox	Feature toggles
multiselect	Multiple selections	Filtering by multiple values

String Parameters

You can use string parameters to create free-text input fields.

Basic Configuration

interface_parameters:
  section:
    source:
      - name: "domain"
        type: "string"
        value: ""              # Default value (empty)

Setting default values

interface_parameters:
  section:
    source:
      - name: "api_version"
        type: "string"
        value: "v3"           # Pre-filled default

Usage in steps

Reference string parameters using {param_name} syntax:

connector:
  base_url: "https://{domain}.api.example.com/{api_version}"

steps:
  - name: "Fetch Data"
    type: "rest"
    http_method: "GET"
    endpoint: "{{%BASE_URL%}}/data?version={api_version}"

Example: Jira domain parameter

interface_parameters:
  section:
    source:
      - name: "jira_domain"
        type: "string"
        value: ""

connector:
  name: "Jira Cloud"
  base_url: "https://{jira_domain}.atlassian.net/rest/api/3"

Authentication parameters

You can use authentication parameters to securely collect and store the credentials you need to access protected APIs. For more information, refer to authentication methods.

Bearer token

Use this method if you need to authenticate using a single static token.

interface_parameters:
  section:
    source:
      - name: "api_credentials"
        type: "authentication"
        auth_type: "bearer"
        fields:
          - name: "bearer_token"
            type: "string"
            is_encrypted: true

Basic HTTP

If your target API requires a username and password, use the basic_http type.

interface_parameters:
  section:
    source:
      - name: "api_credentials"
        type: "authentication"
        auth_type: "basic_http"
        fields:
          - name: "username"
            type: "string"
          - name: "password"
            type: "string"
            is_encrypted: true

API Key

Use this configuration when you need to pass a specific key/value pair.

interface_parameters:
  section:
    source:
      - name: "api_credentials"
        type: "authentication"
        auth_type: "api_key"
        location: "header"       # or "query_param"
        fields:
          - name: "key_name"
            type: "string"
            value: "X-API-Key"
          - name: "key_value"
            type: "string"
            is_encrypted: true

OAuth2

For service-to-service authentication, you can configure OAuth2.

interface_parameters:
  section:
    source:
      - name: "api_credentials"
        type: "authentication"
        auth_type: "oauth2"
        oauth2_settings:
          grant_type: "client_credentials"
          token_url: "https://auth.example.com/oauth/token"
        fields:
          - name: "client_id"
            type: "string"
          - name: "client_secret"
            type: "string"
            is_encrypted: true

Date range parameters

You can use date range parameters to capture specific start and end points from your UI. This is essential for time-bounded data fetching, allowing you to pull only the records you need for a specific period.

Basic configuration

interface_parameters:
  section:
    source:
      - name: "date_range"
        type: "date_range"
        period_type: "date"
        format: "YYYY-mm-DD"
        fields:
          - name: "start_date"
            value: ""
          - name: "end_date"
            value: ""

Period types

Period Type	Description
date	Full date selection (year, month, day)
month	Month and year only
year	Year only

Supported date formats

Format	Example output
YYYY-mm-DD	2024-01-15
YYYY-mm-DDTHH:MM:SSZ	2024-01-15T00:00:00Z
YYYY-mm-DDTHH:MM:SS+00:00	2024-01-15T00:00:00+00:00
DD/mm/YYYY	15/01/2024
mm/DD/YYYY	01/15/2024
DD-mm-YYYY	15-01-2024
YYYY/mm/DD	2024/01/15
YYYYMMDD	20240115
unix_timestamp	1705276800
unix_timestamp_ms	1705276800000
DD.mm.YYYY	15.01.2024
YYYY-mm-DDTHH:MM:SS.sssZ	2024-01-15T00:00:00.000Z

Usage in steps

Reference date range values using {param_name.start_date} and {param_name.end_date} syntax:

steps:
  - name: "Fetch Records"
    type: "rest"
    http_method: "GET"
    endpoint: "{{%BASE_URL%}}/records"
    query_params:
      from_date: "{date_range.start_date}"
      to_date: "{date_range.end_date}"

Example: Complete date range setup

interface_parameters:
  section:
    source:
      - name: "report_dates"
        type: "date_range"
        period_type: "date"
        format: "YYYY-mm-DDTHH:MM:SSZ"
        fields:
          - name: "start_date"
            value: ""
          - name: "end_date"
            value: ""

steps:
  - name: "Fetch Activity Log"
    type: "rest"
    http_method: "GET"
    endpoint: "{{%BASE_URL%}}/activity"
    query_params:
      start: "{report_dates.start_date}"
      end: "{report_dates.end_date}"

List parameters

You can use list parameters to provide a dropdown menu of predefined options.

Basic configuration

interface_parameters:
  section:
    source:
      - name: "status_filter"
        type: "list"
        options:
          - name: "All Records"
            value: "all"
          - name: "Active Only"
            value: "active"
          - name: "Inactive Only"
            value: "inactive"
        value: "all"           # Default selection

Usage in steps

steps:
  - name: "Fetch Users"
    type: "rest"
    http_method: "GET"
    endpoint: "{{%BASE_URL%}}/users"
    query_params:
      status: "{status_filter}"

Example: Environment selection

interface_parameters:
  section:
    source:
      - name: "environment"
        type: "list"
        options:
          - name: "Production"
            value: "prod"
          - name: "Staging"
            value: "stage"
          - name: "Development"
            value: "dev"
        value: "prod"

connector:
  base_url: "https://{environment}.api.example.com/v1"

Integer parameters

You can use integer parameters to create numeric-only input fields.

Basic configuration

interface_parameters:
  section:
    source:
      - name: "page_size"
        type: "integer"
        value: 100            # Default value
        min: 1                # Minimum allowed
        max: 500              # Maximum allowed

Usage in steps

steps:
  - name: "Fetch Records"
    type: "rest"
    http_method: "GET"
    endpoint: "{{%BASE_URL%}}/records"
    query_params:
      limit: "{page_size}"

Boolean Parameters

Use the boolean type to create a simple True/False checkbox.

Basic configuration

interface_parameters:
  section:
    source:
      - name: "include_archived"
        type: "boolean"
        value: false          # Default to unchecked

Usage in steps

steps:
  - name: "Fetch Projects"
    type: "rest"
    http_method: "GET"
    endpoint: "{{%BASE_URL%}}/projects"
    query_params:
      include_archived: "{include_archived}"

Multiselect parameters

When you need to select more than one value from a list, use the multiselect type.

Basic configuration

interface_parameters:
  section:
    source:
      - name: "regions"
        type: "multiselect"
        options:
          - name: "North America"
            value: "na"
          - name: "Europe"
            value: "eu"
          - name: "Asia Pacific"
            value: "apac"
          - name: "Latin America"
            value: "latam"
        value: ["na", "eu"]   # Default selections (array)

Usage in steps

steps:
  - name: "Fetch Regional Data"
    type: "rest"
    http_method: "GET"
    endpoint: "{{%BASE_URL%}}/data"
    query_params:
      regions: "{regions}"    # Sent as comma-separated or array

---

Combining multiple parameters

A typical connector uses multiple interface parameters together:

Example

interface_parameters:
  section:
    source:
      # 1. Domain/URL configuration
      - name: "instance_url"
        type: "string"
        value: ""
      
      # 2. Authentication
      - name: "api_credentials"
        type: "authentication"
        auth_type: "bearer"
        fields:
          - name: "bearer_token"
            type: "string"
            is_encrypted: true
      
      # 3. Date filtering
      - name: "date_range"
        type: "date_range"
        period_type: "date"
        format: "YYYY-mm-DD"
        fields:
          - name: "start_date"
            value: ""
          - name: "end_date"
            value: ""
      
      # 4. Status filter
      - name: "record_status"
        type: "list"
        options:
          - name: "All"
            value: "all"
          - name: "Active"
            value: "active"
          - name: "Closed"
            value: "closed"
        value: "all"

connector:
  name: "CRM Connector"
  base_url: "https://{instance_url}.crm.example.com/api/v2"

steps:
  - name: "Fetch Records"
    type: "rest"
    http_method: "GET"
    endpoint: "{{%BASE_URL%}}/records"
    query_params:
      start_date: "{date_range.start_date}"
      end_date: "{date_range.end_date}"
      status: "{record_status}"

Variable reference syntax summary

Use this table as a reference for how to syntax your parameters within your Blueprint steps.

Parameter type	Syntax	Example
String	{param_name}	{domain}
Date Range Start	{param_name.start_date}	{date_range.start_date}
Date Range End	{param_name.end_date}	{date_range.end_date}
List	{param_name}	{status_filter}
Integer	{param_name}	{page_size}
Boolean	{param_name}	{include_archived}
Multiselect	{param_name}	{regions}

note

Interface parameters use {param_name} syntax (without percent signs), while internal variables extracted from API responses use {{%variable_name%}} syntax.

Best practices

• Use descriptive names: Choose specific names like jira_domain instead of generic names like domain.

  Example

  # Good
  - name: "jira_domain"
  - name: "report_date_range"
  - name: "ticket_status_filter"
  
  # Avoid
  - name: "domain"
  - name: "dates"
  - name: "filter"

• Provide sensible defaults: Set a value for integers so you can run your connector immediately without manual entry.

  Example

  - name: "page_size"
  type: "integer"
  value: 100        # Most users won't need to change this
  
  - name: "status"
  type: "list"
  value: "active"   # Common default selection

• Always encrypt sensitive data: Ensure all secret keys, passwords, and tokens are marked with is_encrypted: true to protect your sensitive information.

  Example

  fields:
    - name: "api_token"
      type: "string"
      is_encrypted: true    # Always for tokens, passwords, secrets

• Use list parameters for known options: When there are a fixed set of valid values, use list parameters instead of free-text strings.

  Example

  # Good - Prevents user errors
  - name: "environment"
  type: "list"
  options:
    - name: "Production"
      value: "prod"
    - name: "Sandbox"
      value: "sandbox"
  
  # Avoid - Error prone
  - name: "environment"
  type: "string"
  value: ""

• Match date formats to API requirements: Check the target API documentation and use the exact format required.

  Example

  # For APIs expecting ISO 8601
  format: "YYYY-mm-DDTHH:MM:SSZ"
  
  # For APIs expecting Unix timestamp
  format: "unix_timestamp"
  
  # For APIs expecting simple dates
  format: "YYYY-mm-DD"