Interface Parameters

Understanding Interface Parameters in Blueprint YAML

Introduction

Interface parameters play a crucial role in defining and managing input parameters within a Blueprint YAML configuration. These parameters allow users to dynamically configure authentication, data extraction settings, and general API inputs, ensuring seamless integration with Rivery’s Source to Target (S2T) River.

Users create YAML configurations, ensuring precise control over the Blueprint behavior. Input parameters must be explicitly declared within the YAML file. These parameters will be exposed in the UI under Source Configuration and categorized into the following types:

• Authentication Parameters
• Incremental Loading Parameters
• Standard Inputs

This document explains the different categories of interface parameters, their structure in the YAML file, and how they interact within the S2T River UI.

Types of Interface Parameters and Their Usage

1. Authentication Parameters

Purpose: Manage secure API connections.

Authentication parameters define how a connector will authenticate API calls. These can be basic authentication, token-based authentication, or Bearer token authentication.

Basic Authentication Example

- name: "connectToAPI"
  type: "authentication"
  auth_type: "basic_http"
  fields:
    - name: "username"
      type: "string"
      value: "your_rivery_mail"
    - name: "password"
      type: "string"
      value: "look at 1password"

Token-Based Authentication Example

- name: "connectToAPI"
  type: "authentication"
  auth_type: "bearer"
  fields:
    - name: "bearer_token"
      type: "string"
      value: "your_bearer_token"

How It Works in YAML:

• The connectToAPI parameter contains authentication details.
• The authentication fields include credentials such as usernames, passwords, API keys, or tokens.
• The authentication type is specified (basic_http, bearer, etc.).

2. Incremental Loading Parameters

Purpose: Handle time-based data extraction efficiently.

Incremental loading parameters allow for efficient data retrieval by defining a date range for fetching data.

Example: Date Range for Incremental Loading

- name: "time_period"
  type: "date_range"
  period_type: "date"
  format: "YYYY-mm-DD"
  fields:
    - name: "start_date"
      value: "2024-12-01"
    - name: "end_date"
      value: "2024-12-12"

How It Works in YAML:

• The time_period parameter defines the start and end dates.
• The period_type can be date or datetime.
• The format ensures consistency across API requests.
• The query uses {time_period.start_date} and {time_period.end_date} to dynamically insert the values.

3. Standard Inputs

Purpose: Manage general API parameters that allow dynamic configurations.

These are general input parameters that can be used in API requests for different settings like domain names, pagination limits, or filtering options.

Example: Configuring a Domain Name

- name: "your_domain"
  type: "string"
  value: "rivery-jira"

Example: Pagination Parameters

- name: "pagination"
  type: "integer"
  value: 50

How It Works in YAML:

• The your_domain parameter dynamically sets the API domain.
• The pagination parameter controls how many results are retrieved per request.
• These values can be referenced in API calls dynamically.

How Interface Parameters Work in a Full YAML Configuration

The interface parameters are utilized within both the connector and steps sections of the YAML file.

interface_parameters:
  section:
    source:
      - name: "your_domain"
        type: "string"
        value: "rivery-jira"
      - name: "connectToAPI"
        type: "authentication"
        auth_type: "basic_http"
        fields:
          - name: "username"
            type: "string"
            value: "your_rivery_mail"
          - name: "password"
            type: "string"
            value: "look at 1password"
      - name: "time_period"
        type: "date_range"
        period_type: "date"
        format: "YYYY-mm-DD"
        fields:
          - name: "start_date"
            value: "2024-12-01"
          - name: "end_date"
            value: "2024-12-12"

Best Practices for Using Interface Parameters

1. Plan Your Variables – Define all necessary parameters before setting up the YAML configuration.
2. Ensure Secure Authentication – Use encrypted values for sensitive credentials.
3. Validate Steps Before Execution – Test each YAML configuration to ensure it retrieves and processes data correctly.
4. Use Retry Strategies – Handle intermittent API failures effectively.
5. Optimize Storage – Choose memory-based storage for temporary variables and file storage for long-term data retention.

By following these guidelines, users can efficiently define Blueprint interface parameters, enabling dynamic and reusable workflows for data ingestion in Rivery.

For further guidance, refer to the official Rivery documentation or reach out to support.