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.

note

The syntax for referencing parameters in steps depends on the Blueprint structure you are using. In a single-report Blueprint, use {param_name}. In a multi-report Blueprint, use {{%param_name%}} for both global and report parameters. We recommend the multi-report structure for all new Blueprint development.

Parameter structure

Define interface parameters within the interface_parameters block of your Blueprint. These sections logically group related inputs 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

Report parameters

A Blueprint can contain multiple reports, where each report extracts data from a different API endpoint. When you configure a multi-report Blueprint, you define parameters at two levels:

• Global parameters: Use these for values that every report shares, such as authentication credentials and the base URL. You define these once, and all reports in the Blueprint use them.
• Report parameters: Use these for values that are specific to a report, such as filters, status values, or date ranges. Each report has its own independent set of report parameters.

warning

Do not define a date_range parameter in the global interface_parameters block for a multi-report Blueprint. Define it inside each report's report_parameters block instead.

When you use a multi-report Blueprint as a source in a Source-to-Target flow, date range fields appear within each report's configuration section, not at the global level. Configure the date range separately for each report in the flow.

Example: Multi-report Blueprint with global and report parameters

The following example shows a GitHub Blueprint that fetches pull requests and issues as separate reports. The owner and repo parameters are global; each report defines its own state filter. Within a report's steps, reference both global parameters and report parameters using {{%param_name%}} syntax.

interface_parameters:
  section:
    source:
      - name: connectToAPI
        type: authentication
        auth_type: bearer
        location: header
        fields:
          - name: bearer_token
            type: string
            is_encrypted: true
      - name: owner           # Global — shared by all reports
        type: string
      - name: repo            # Global — shared by all reports
        type: string

connector:
  name: githubMultiReportConnector
  type: rest
  base_url: https://api.github.com
  default_headers:
    Accept: application/vnd.github+json
    X-GitHub-Api-Version: "2022-11-28"
  variables_storages:
    - name: results_dir
      type: file_system
  variables_metadata:
    final_output_file:
      storage_name: results_dir
      format: json

reports:
  - name: ListPullRequests
    report_parameters:
      - name: state           # Report-specific — applies to this report only
        type: string
        value: open
    steps:
      - name: GetPullRequests
        type: rest
        http_method: GET
        endpoint: /repos/{{%owner%}}/{{%repo%}}/pulls
        query_params:
          state: "{{%state%}}"
        variables_output:
          - variable_name: final_output_file
            variable_format: json
            response_location: data
            overwrite_storage: false

  - name: ListIssues
    report_parameters:
      - name: state
        type: string
        value: open
    steps:
      - name: GetIssues
        type: rest
        http_method: GET
        endpoint: /repos/{{%owner%}}/{{%repo%}}/issues
        query_params:
          state: "{{%state%}}"
        variables_output:
          - variable_name: final_output_file
            variable_format: json
            response_location: data
            overwrite_storage: false

After you save the Blueprint and reload metadata for a report, the column schema is automatically detected. You can then configure the mapping for each report independently from the Mapping tab.

note

Data Integration does not automatically migrate existing single-report Blueprints to the multi-report structure. To use the multi-report structure, create a new Blueprint file. We recommend the multi-report structure for all new Blueprint development.

For examples of both the single-report and multi-report YAML structures, refer to Blueprint components and configuration.

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}"

note

In a multi-report Blueprint, use {{%param_name%}} syntax instead. For example, {{%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
epoch	Unix timestamp. value_type controls whether the output appears as a string or integer.

note

The value_type field controls how to pass the epoch timestamp in the request. It applies only when period_type is epoch.

• string — Passes the timestamp as a quoted string, for example, "1704067200". Default behavior if value_type is not specified.
• integer — Passes the timestamp as an integer, for example, 1704067200. Use this for APIs that expect numeric epoch values.

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}"

note

In a multi-report Blueprint, use {{%date_range.start_date%}} and {{%date_range.end_date%}} instead.

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}"

Example: Epoch date range with integer output

Use this configuration for APIs that expect Unix timestamps as integers rather than strings:

interface_parameters:
  section:
    source:
      - name: date_range
        type: date_range
        period_type: epoch
        value_type: int
        fields:
          - name: start_date
          - name: end_date

Usage in steps

query_params:
  createdAfter: "{date_range.start_date}"
  createdBefore: "{date_range.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}"

note

In a multi-report Blueprint, use {{%status_filter%}} instead.

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}"

Multi-select 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

The syntax for referencing parameters in steps depends on the Blueprint structure you are using.

Single-report Blueprint

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}

Multi-report Blueprint (recommended)

In the multi-report structure, reference both global and report parameters using {{%param_name%}} syntax inside report 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

In both structures, 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 use 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: Verify the target API technical specifications 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"