usps-imis-api

USPS iMIS API for Ruby

Installation

Run this command:

gem install usps-imis-api

or add this line to your Gemfile:

gem 'usps-imis-api', '>= 0.3.0'

Setup

Include the library, and set the configuration:

require 'dotenv/load' # Optionally load environment variables from `.env` file
require 'usps/imis'

Usps::Imis.configure do |config|
  config.environment = :development # Rails.env
  config.imis_id_query_name = ENV['IMIS_ID_QUERY_NAME']

  config.username = ENV['IMIS_USERNAME']
  config.password = ENV['IMIS_PASSWORD']
end

When using bin/console, this configuration will be run by default.

Instantiate the API object:

api = Usps::Imis::Api.new

Authentication

If a token is not available, this will automatically fetch one when needed. As long as that token should still be valid, it will reuse the same token. If the token should expire, this will automatically request a new token.

Usage

iMIS ID

To act on member data, you need to have the iMIS ID. If you already have access to that from the database, you can skip this step.

To convert a member's certificate number into their iMIS ID, run the following method:

api.get_imis_id(certificate)

This will both return the ID, and store it for use with other requests. If you need to change which member you are working with, just run this method again with the new certificate number.

General API Requests

GET

To fetch member data, run e.g.:

api.imis_id = 31092

data = api.get('ABC_ASC_Individual_Demog')

PUT

To update member data, run e.g.:

api.imis_id = 31092

data = { 'MMS_Updated' => Time.now.strftime('%Y-%m-%dT%H:%M:%S'), 'TotMMS' => new_total }
update = api.put_object_fields('ABC_ASC_Individual_Demog', data)

This method fetches the current data structure, and filters it down to just what you want to update, to reduce the likelihood of update collisions or type validation failures.

Public Methods

Convert a member's certificate number into an iMIS ID number

api.get_imis_id(certificate)

Manually set the current ID, if you already have it for a given member

api.imis_id = imis_id

GET a business object for the current member

api.get(business_object_name)

Update only specific fields on a business object for the current member

fields is a hash of shape: { field_name => new_value }

api.put_fields(business_object_name, fields)

Run an IQA Query

query_params is a hash of shape: { param_name => param_value }

api.query(query_name, query_params)

Field Mapper

For fields that have already been mapped between the ITCom database and iMIS, you can use the Mapper class to further simplify the update interface:

api.mapper.update(mm: 15)

For simplicity, you can also call update on the Api class directly:

api.update(mm: 15)

If there is no known mapping for the requested field, the Mapper will give up, but will provide you with the standard API call syntax, and will suggest you inform ITCom leadership of the new mapping you need.

Panels

For supported panels (usually, business objects with composite identity keys), you can interact with them in the same general way:

vsc = Usps::Imis::Panel::Vsc.new

vsc.api.imis_id = 6374

vsc.get(1417)

created = vsc.create(certificate: 'E136924', year: 2024, count: 42)
ordinal = created['Properties']['$values'][1]['Value']['$value']

vsc.update(certificate: 'E136924', year: 2024, count: 43, ordinal: ordinal)

vsc.destroy(ordinal)

Panels are also accessible directly from the API object:

api.panels.vsc.get(1417)

DSL Mode

Instead of manually setting the current iMIS ID, then running individual queries, you can instead run queries in DSL mode. This specifies the iMIS ID for the scope of the block, then reverts to the previous value.

api.with(31092) do
  # These three requests are identical:

  put('ABC_ASC_Individual_Demog', { 'TotMMS' => 15 })

  mapper.update(mm: 15)

  update(mm: 15)

  panels.vsc.get(1417)
end

Exception Handling

Exception and error response handling will be added later.

Automated Testing and Linting

Testing is available by running:

bundle exec rspec

Linting is available by running:

bundle exec rubocop

GitHub Actions

Testing and linting are automatically run on every push.

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. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

PHP

This same API is available for PHP.