Iron Bank

An opinionated Ruby interface to the Zuora REST API.

We who serve the Iron Bank face death full as often as you who serve the Iron Throne.

(A Dance with Dragons, Chapter 44, Jon IX)

This gem provides opinionated resources to interact with the Zuora API through their REST interface. It defines associations between them, as well as a simple declaration API (with_one, with_many) to extend them.

This gem is tested against Ruby >= 3.1.

Please use GitHub Issues to report bugs.

Getting Started

You will need:

• a Zuora tenant (apisandbox, services, performances or production)
• an administrator access to this tenant (to gain API access)
• and an OAuth client for this user (Zuora documentation)

IronBank is a pure Ruby client, but we do provide a generator (for the configuration) when using it within Rails.

Add the gem to your Gemfile with:

gem 'iron_bank'

And run the bundle command to install it. You then need to run the generator:

$ rails generate iron_bank:install

Use the client_id and client_secret from your Zuora OAuth client and add them to the generated config/initializers/iron_bank.rb file.

Configuration

# Configure Ironbank
IronBank.configure do |config|
  config.client_id         = 'client_id'
  config.client_secret     = 'client_secret'
  config.auth_type         = 'auth_type'
  config.domain            = 'zuora-domain'   # zuora doamin
  config.export_directory  = 'directory-path' # export directory path
  config.schema_directory  = 'directory-path' # schema drirectory path

  # Ironbank uses Faraday to send request to Zuora. Middlewares can be specified
  # by adding the class name and class options to the `middlewares`
  # configuration.
  # Faraday middlewares, we can send in an array with cutomer middleware class
  # and options
  config.middlewares << [DummyMiddlewareClass, {}]
end

Usage

# make a query to Zuora using ZOQL
IronBank::Query.call "select Name from Account where Id='zuora-account-id'"

# retrieve an account
account = IronBank::Account.find 'zuora-account-id'
# => #<IronBank::Resources::Account>

# access this resource attributes
account.name # => 'My Company Inc.'

# or associated objects
account.bill_to
# => #<IronBank::Resources::Contact>

account.active_subscriptions
# => [#<IronBank::Resources::Subscription>]

Local records

If your product catalog does not change often, you may want to export it locally so that product catalog and related object queries look for local records first, then fallback to the API if no records are found.

You can export your product catalog locally using the LocalRecords class:

# Save CSV files in the directory specified by `config.export_directory`
IronBank::LocalRecords.export

Then, making a query/looking for a record will first search through the local records, then default to the API if no records are found.

product = IronBank::Product.find 'zuora-product-id'
# => #<IronBank::Resources::Product>

product.plans[0].charges[0].tiers[0]
# => #<IronBank::Resources::ProductRatePlanChargeTier>

Without local records, the previous scenario will make 4 requests to Zuora to access the charge tiers. By exporting local records, you can significantly reduce your execution time, e.g., when building a SubscriptionRequest.

Development

1. After checking out the repo, run bin/setup to install dependencies
2. Edit the copied .env file with your Zuora credentials
3. Execute bundle exec rake to run the linters and tests
4. You can also run bin/console for an interactive prompt that will allow you to experiment with the Zuora APIs

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/zendesk/iron_bank.

Known issues

• AutoPay field on the Invoice object is not queryable using ZOQL despite the metadata showing <selectable>true</selectable>, hence it has been added to the excluded_fields method.
• Exporting the local records through IronBank::LocalRecords.export can take a long time (especially the ProductRatePlanChargeTier records). In case the task fails because the export is still processing, you can manually download the export from Zuora by going to Reporting -> Data Sources and looking for the ProductRatePlanChargeTier.csv export.

Copyright and license

Copyright 2018 Zendesk, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.