Product UpdatesStatus PageAutomation Institute
English
Get a trial
Connector SDK
CLI

# Getting Started with the SDK Gem

In this guide, we'll show you how to:

  • Install and run the SDK gem
  • Create a new connector project
  • Set up testing for your connector
  • Push your local connector to your Workato workspace

# Prerequisites

To complete this tutorial, you'll need:

  • A Ruby version manager. Depending on your operating system, you'll need to install a version of Ruby or a Ruby version manager.

    For Mac users, you can use RVM (Ruby Version Manager) (opens new window) or another manager of your choice.

    For Windows users, you can use Ruby Installer (opens new window).

    Learn more here (opens new window) in Ruby's official docs.

  • A supported version of Ruby. We prefer 2.7.X, but you can use versions 3.0.X or 3.1.X. If you don't have Ruby installed, follow these instructions to install it (opens new window).

    You can verify your Ruby version by running the following command, or the appropriate command for your Ruby version manager (for example: rvm current):

    $ ruby -v
ruby 2.7.X

    This command returns the version of Ruby currently installed on your computer. In this example, we're using 2.7.X.

# Step 1: Install and run the SDK Gem

Installation of the SDK gem is done through the command line. Run the following command to install the gem from rubygems.org (opens new window):

$ gem install workato-connector-sdk

Verify that your gem is correctly installed by typing in the command workato in terminal.

$ workato

Commands:
  workato edit <PATH>            # Edit encrypted file, e.g. settings.yaml.enc
  workato exec <PATH>            # Execute connector defined block
  workato generate <SUBCOMMAND>  # Generates code from template
  workato help [COMMAND]         # Describe available commands or one specific command
  workato new <CONNECTOR_PATH>   # Inits new connector folder
  workato push <FOLDER>          # Upload and release connector's code

Options:
  [--verbose], [--no-verbose]

TIP

For Windows users, you may need to install tzinfo-data gem by running the command gem install tzinfo-data.

To check the exact location of the gem, use gem which:

$ gem which workato-connector-sdk

Additionally, you can use the workato command to view the commands that are available during development. Find out more about individual keys by using workato help edit, etc.

# Step 2: Create a new connector project

Now that you're all set up, let's dive into the exciting stuff: Making connectors.

1

Create a new connector project using the workato new command, replacing <PATH> with the path you'd like to use for the project:

$ workato new <PATH>

This creates the project in the directory you're currently in.

2

Next, you may be prompted about HTTP mocking behavior:

Please select default HTTP mocking behavior suitable for your project?

1 - secure. Cause an error to be raised for any unknown requests, all request recordings are encrypted.
            To record a new cassette you need set VCR_RECORD_MODE environment variable

            Example: VCR_RECORD_MODE=once bundle exec rspec spec/actions/test_action_spec.rb

2 - simple. Record new interaction if it is a new request, requests are stored as plain text and expose secret tokens.

Enter your choice using 1 or 2:

  • 1 - secure - Recommended. All HTTP requests are encrypted and recorded via VCR to ensure stability. We'll also provide you with an easy way to encrypt the recordings so credentials are not stored in plain text.
  • 2 - simple - All HTTP requests are stored in plain text.

Refer to the project directory reference for more info about the files the workato new command creates.

# Step 3: Build and test your connector

In this step, you'll build and test your connector. As how and what you build is up to you, we're only going to cover testing in this section:

# Step 3.1: Provide test credentials

Credentials are stored in your project's settings.yaml.enc or settings.yaml file.

1

If you opted to encrypt your files, run the workato edit command and replace <EDITOR> with your preferred editor:

Example - Mac users 
$ EDITOR="<EDITOR>" workato edit settings.yaml.enc
Example - Windows users 
$ set EDITOR=notepad
$ workato edit settings.yaml.enc

When you run this command for the first time, the settings.yaml.enc and master.key files will be created.

2

In your project's settings.yaml.enc or settings.yaml file, add your credentials.

We're going to use a single set of credentials for this example, so we can define them at the root level:

## settings.yaml.enc

api_key: [api_key]
domain: [domain]

Refer to the settings file reference for more info, including how to provide multiple sets of credentials.

3

If committing your project, add master.key to your project's .gitignore or other similar file(s). This prevents your credentials from being checked into a repository, where anyone might have access to them.

# Step 3.2: Test the connector

Test your connector's connection, triggers, or actions with workato exec. This executes a connector's lambda block at the PATH you provide.

For example:

# Executes the execute block of the new_record action
$ workato exec actions.new_record.execute

# Invokes a polling trigger for the updated_record trigger
$ workato exec triggers.updated_record.poll

# Executes the get_record method with parameters from input.json
$ workato exec methods.get_record --args=input.json

Check out the Running test lambda on CLI guide and for a detailed look testing on the CLI.

# Step 4: Push to your Workato workspace

When you're ready, push your connector code from your local environment to your Workato workspace. Pushing to your Workato workspace allows you to test the functionality and UX of your connector, ensuring you can iterate quickly.

API CLIENT PERMISSIONS

This command requires your API client to be assigned a Client role with the Get details permission enabled.

ENABLE THE GET DETAILS PERMISSION
1

If this permission is not already enabled for your API client, you can enable it by navigating to Workspace admin > API Clients > Client roles.

2

From here you can edit an existing client role or create a new one.

3

Then, navigate to Admin > Workspace details and select Get details.

Enable the get details permissionEnable the Get details permission

Run the workato push command:

$ workato push

Test in your Workato workspace, making changes locally and pushing to your Workato workspace as needed. You will need to supply your workspace's api-token and api-email for authorization.

# Step 5: Run RSpec tests for your connector

Using unit test is a great way to ensure that each iteration of your connector is performing as expected. Learn more about writing test your connectors.

To run RSpec, you should have the project structure setup. Running RSpec is as easy as running the Workato Gem in CLI. You simply use bundle exec rspec in your project home directory.

You may also run only specific tests at a time. Otherwise, RSpec will run all spec files in your spec folder by default.

# Runs the test(s) at line 16 of your spec file.
$ bundle exec rspec ./spec/connector_spec.rb:16

ENSURE RSPEC GEM VERSION MATCHES YOUR GEMFILE

It is possible to use the command rspec in place of bundle exec rspec, however, using bundle exec rspec ensures that the rspec Gem version you use for tests matches the version specified in your Gemfile.

# 5.1 Configuring VCR

The Workato SDK Gem works with RSpec and VCR to provide you a way to write unit tests, store HTTP interactions (requests and responses) so that you can continue to run these unit tests without constantly having to send the request to the API. This also has the benefit of replaying the same responses so you needn't have to worry about changes of the actual data in the Application.

When you generate a project using Workato, these settings are automatically generated for you in the spec_helper.rb with some default VCR configurations. These VCR recordings also depend on your chosen security settings when you first setup the project. If you selected secure, your VCR recordings would be encrypted using your master.key.

Learn more about using VCR.

# What's next?

← CLI
CLI - test: lambda →


Last updated: 2/28/2025, 4:03:18 PM

On this page