tyler_efm_client

Tyler EFM Client - Ruby SDK

A production-ready Ruby SDK for integrating with Tyler Technologies Electronic Filing Manager (EFM) services. This gem simplifies authentication and SOAP service calls for Electronic Court Filing (ECF) systems.

🚀 Features

• Simple Authentication: One method to authenticate with Tyler EFM services
• Flexible SOAP Operations: Call any Tyler EFM SOAP operation with automatic security handling
• WS-Security Support: Automatic RSA-SHA1/SHA1 digital signatures (Tyler legacy compatibility)
• Certificate Management: Automatic PFX certificate handling and cleanup
• Response Formats: Choose between XML and JSON response formats
• Production Ready: Built from working Tyler ECF 5.0 integration code
• Ruby Idiomatic: Follows Ruby conventions and best practices

📦 Installation

Add this line to your application's Gemfile:

gem 'tyler_efm_client'

And then execute:

bundle install

Or install it directly:

gem install tyler_efm_client

Requirements

• Ruby 2.7+
• Valid Tyler EFM PFX certificate
• Access to Tyler EFM services (staging or production)

🔧 Quick Start

Basic Authentication

require 'tyler_efm_client'

# Initialize client
client = TylerEfmClient::Client.new

# Authenticate
auth_result = client.authenticate(
  base_url: "https://your-tyler-server.com/EFM/EFMUserService.svc",
  pfx_file: "path/to/certificate.pfx",
  pfx_password: "certificate_password",
  user_email: "[e-mail]",
  user_password: "your_password"
)

if auth_result.success?
  puts "Password Hash: #{auth_result.password_hash}"
  puts "User: #{auth_result.first_name} #{auth_result.last_name}"
else
  puts "Error: #{auth_result.error_message}"
end

Service Operations

# Call GetCaseList operation
soap_body = <<~SOAP
  <wrappers:GetCaseListRequest xmlns:wrappers="https://docs.oasis-open.org/legalxml-courtfiling/ns/v5.0/wrappers">
    <!-- Your SOAP body content -->
  </wrappers:GetCaseListRequest>
SOAP

response = client.call_service(
  base_url: "https://your-tyler-server.com/efm/v5/CourtRecordService.svc",
  password_hash: auth_result.password_hash,
  operation: "GetCaseList",
  soap_body: soap_body,
  user_email: "[e-mail]",
  return_json: true  # Get JSON response instead of XML
)

if response.success?
  puts "Service call successful!"
  if response.json_data
    # Work with JSON data
    pp response.json_data
  else
    # Work with raw XML
    puts response.raw_xml
  end
end

📚 API Reference

TylerEfmClient::Client

The main client class for Tyler EFM operations.

#authenticate(base_url:, pfx_file:, pfx_password:, user_email:, user_password:)

Authenticate with Tyler EFM User Service.

Parameters:

• base_url (String): Base URL for the EFM User Service
• pfx_file (String): Path to the PFX certificate file
• pfx_password (String): Password for the PFX certificate
• user_email (String): User's email address
• user_password (String): User's password

Returns: TylerEfmClient::AuthenticationResult object with:

• success? (Boolean): Whether authentication succeeded
• password_hash (String): Password hash for subsequent service calls
• user_id (String): User's unique identifier
• first_name (String): User's first name
• last_name (String): User's last name
• email (String): User's email
• expiration_date (String): Token expiration date
• error_code (String): Error code if authentication failed
• error_message (String): Error message if authentication failed

#call_service(base_url:, password_hash:, operation:, soap_body:, **options)

Call any Tyler EFM SOAP service operation.

Parameters:

• base_url (String): Base URL for the EFM service
• password_hash (String): Password hash from authentication
• operation (String): Name of the SOAP operation
• soap_body (String): SOAP body content as XML string
• user_email (String, optional): User's email (required for Court Record Service)
• pfx_file (String, optional): Path to PFX certificate if not from authentication
• pfx_password (String, optional): PFX password if not from authentication
• return_json (Boolean, optional): Return JSON instead of XML (default: false)
• soap_action (String, optional): Custom SOAP action header

Returns: TylerEfmClient::ServiceResponse object with:

• success? (Boolean): Whether the service call succeeded
• status_code (Integer): HTTP status code
• raw_xml (String): Raw XML response
• json_data (Hash, optional): JSON representation of response if requested
• error_message (String, optional): Error message if call failed

🏗️ Architecture

This SDK implements Tyler's exact ECF 5.0 requirements:

Authentication (User Service)

• WS-Security: Digital signatures using RSA-SHA1/SHA1 (Tyler legacy requirement)
• Certificate Auth: Mutual TLS using PFX certificates
• SOAP Structure: Exact Tyler-compatible XML namespace handling

Court Record Service Operations

• UserNameHeader: Special header structure required by Court Record Service
• No Namespace Prefix: Critical requirement - UserNameHeader must not have namespace prefix
• Header Order: UserNameHeader must be first header element
• Password Hash: Uses hashed password from authentication, not plain password

🔒 Security Features

• Automatic Certificate Handling: PFX files are processed and cleaned up automatically
• WS-Security Signatures: RSA-SHA1 digital signatures for message integrity
• Legacy Algorithm Support: SHA1 and RSA-SHA1 for Tyler compatibility
• HTTPS Only: All communications use HTTPS with certificate verification

📖 Examples

The examples/ directory contains complete working examples:

• authentication_example.rb - Basic authentication
• getcaselist_example.rb - GetCaseList operation
• complete_workflow_example.rb - Full workflow with multiple operations

Run examples:

cd examples
ruby authentication_example.rb
ruby getcaselist_example.rb
ruby complete_workflow_example.rb

🐛 Error Handling

The SDK provides specific exception types:

begin
  auth_result = client.authenticate(...)
rescue TylerEfmClient::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
rescue TylerEfmClient::CertificateError => e
  puts "Certificate error: #{e.message}"
rescue TylerEfmClient::ServiceError => e
  puts "Service error: #{e.message}"
rescue TylerEfmClient::Error => e
  puts "EFM client error: #{e.message}"
end

🧪 Testing

The SDK is built from working Tyler ECF integration code and tested against:

• Tyler Georgia staging environment
• Production Tyler ECF 5.0 systems
• Multiple certificate types and configurations

Run tests:

bundle exec rake spec

Run linting:

bundle exec rake rubocop

📋 Requirements

System Requirements

• Ruby 2.7 or higher
• OpenSSL for certificate processing
• Network access to Tyler EFM services

Tyler Requirements

• Valid Tyler EFM account and credentials
• PFX certificate file from Tyler Technologies
• Appropriate service URLs (staging or production)

🔧 Development

After checking out the repo, run:

bin/setup

To install dependencies. Then, run:

rake spec

To run the tests. You can also run:

bin/console

For an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run:

bundle exec rake install

🚀 Releases & Versioning

This gem uses automated version management through GitHub Actions. The system automatically handles version conflicts and increments alpha releases.

Quick Release Guide

Alpha/Development Releases (Most Common):

• Go to GitHub Actions → "Publish Ruby Gem" → "Run workflow"
• Leave version input blank - system will auto-increment to next available version
• Perfect for continuous integration and testing

Production Releases:

# Create a version tag and GitHub release
git tag v1.0.0
git push origin v1.0.0
# Then create GitHub Release using the tag

Manual Version Override:

• Use GitHub Actions workflow with specific version input
• Example: 1.0.0.pre.alpha.10 or 1.1.0.pre.beta.1

📖 See VERSIONING.md for complete versioning guide

Current Version Strategy

• Auto-increment: System automatically finds next available alpha version
• Conflict Resolution: Handles "version already exists" errors automatically
• No Manual File Editing: Version files updated during CI/CD process

🤝 Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/tyler-technologies/cj-esol-efm-client-ruby.

• Fork it
• Create your feature branch (git checkout -b my-new-feature)
• Commit your changes (git commit -am 'Add some feature')
• Push to the branch (git push origin my-new-feature)
• Create new Pull Request

📄 License

This gem is available as open source under the terms of the MIT License.

🏢 About Tyler Technologies

Tyler Technologies is a leading provider of integrated software and technology services to the public sector. Learn more at tylertech.com.

Built with ❤️ for the Tyler ECF community