Ruby Fiix CMMS Client

A Ruby gem for the Fiix CMMS REST API with HMAC-SHA256 authentication. Zero runtime dependencies.

Supports all core API operations: find, find by ID, create, update, delete, RPC, batch, and file uploads.

Installation

Add to your Gemfile:

gem "ruby-fiix-cmms-client"

Then run bundle install.

Or install directly:

gem install ruby-fiix-cmms-client

Usage

Direct instantiation

require "ruby/fiix/cmms/client"

client = Ruby::Fiix::Cmms::Client::ApiClient.new(
  subdomain: "mycompany",
  api_key: "your-app-key",
  access_key: "your-access-key",
  api_secret: "your-api-secret"
)

# Find records
response = client.find(className: "Account", fields: "id,strCode,strDescription")
response.body     # => parsed Hash
response.success? # => true
response.status   # => 200

# Find by ID
response = client.find_by_id(className: "Asset", id: 12345, fields: "id,strName")

# Create
response = client.create(
  className: "WorkOrder",
  fields: "id",
  object: { "strDescription" => "Fix pump" }
)

# Update
response = client.update(
  className: "WorkOrder",
  object: { "id" => 1, "strDescription" => "Fix pump - urgent" }
)

# Delete
response = client.delete(className: "WorkOrder", objects: [{ "id" => 1 }])

# RPC (remote procedure call)
response = client.rpc(className: "User", action: "getPermissions")

# Batch (multiple operations in one request)
response = client.batch(
  requests: [
    { "_maCn" => "FindRequest", "className" => "Account", "fields" => "id,strCode" },
    { "_maCn" => "FindRequest", "className" => "PurchaseOrder", "fields" => "id,intCode" }
  ]
)

# File upload
file = File.open("document.pdf")
response = client.upload_file(
  className: "CMAFileContainer",
  file: file,
  description: "Maintenance report"
)

Rails initializer pattern

# config/initializers/fiix.rb
Ruby::Fiix::Cmms::Client.configure do |c|
  c.subdomain  = ENV["FIIX_SUBDOMAIN"]
  c.api_key    = ENV["FIIX_API_KEY"]
  c.access_key = ENV["FIIX_ACCESS_KEY"]
  c.api_secret = ENV["FIIX_API_SECRET"]
end

# Anywhere in your app
client = Ruby::Fiix::Cmms::Client::ApiClient.new  # uses global config

Response object

All operations return a Ruby::Fiix::Cmms::Client::Response:

response = client.find(className: "Account", fields: "id")

response.body          # => parsed JSON as Hash
response.success?      # => true/false (based on HTTP status)
response.status        # => 200 (integer)
response["key"]        # => shorthand for response.body["key"]
response.to_h          # => Hash (empty hash if body isn't JSON)
response.http_response # => raw Net::HTTPResponse

Error handling

begin
  client.find(className: "Account")
rescue Ruby::Fiix::Cmms::Client::ConfigurationError => e
  # Missing or invalid credentials
rescue Ruby::Fiix::Cmms::Client::ConnectionError => e
  # Network connectivity issues
rescue Ruby::Fiix::Cmms::Client::ApiError => e
  # API-level errors (e.response holds the Response object)
rescue Ruby::Fiix::Cmms::Client::Error => e
  # Catch-all for any gem error
end

Development

bin/setup          # Install dependencies
rake test          # Run tests
bin/console        # Interactive console

Contributing

Bug reports and pull requests are welcome on GitHub.

License

MIT License. See LICENSE.txt.