Module: SrFax

Defined in:
lib/srfax.rb

Overview

This class serves as the integration component between the application and the SRFax cloud service. API DOX available @ www.srfax.com/srf/media/SRFax-REST-API-Documentation.pdf.

This module currently Implements the following POST commands from the API:

Get_Usage

Constant Summary collapse

VERSION = 
'0.3.0pre'
BASE_URI =

Base URL for accessing SRFax API

"https://www.srfax.com/SRF_SecWebSvc.php"
@@defaults =

Default values hash to use with all #execute commands

{
  access_id: '1234',
  access_pwd: 'password',
  sFaxFormat: 'PDF', # Default format, PDF or TIF
  sResponseFormat: 'JSON' # XML or JSON
}
@@logger =

Logger object for use in standalone modeo or with Rails

defined?(Rails) ? Rails.logger : Logger.new(STDOUT)

Class Method Summary collapse

Class Method Details

.delete_fax(descriptor, direction) ⇒ Hash

Delete a particular fax from the SRFax cloud service

Example Payload for Return:

 {"Status"=>"Success", "Result"=>[{"FileName"=>"20150430124505-6104-19_1|20360095", "ReceiveStatus"=>"Ok", 
 "Date"=>"Apr 30/15 02:45 PM", "EpochTime"=>1430423105, "CallerID"=>"9056193547", "RemoteID"=>"", "Pages"=>"1", 
 "Size"=>"5000", "ViewedStatus"=>"N"} ]}
:direction is either 'IN' or 'OUT' for inbox or outbox
:descriptor is what is returns from the POST Filename field from the view_inbox result

Parameters:

  • descriptor (String) —

    THe descriptor provided by SRFax which identifies a unique fax

  • direction (String) —

    Either ‘IN’ or ‘OUT’ to specify the inbox or outbox

Returns:

  • (Hash) —

    A hash containing the return value (Success/Failure) and the payload where applicable



198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/srfax.rb', line 198

def delete_fax(descriptor, direction)
  logger.info "Deleting a fax in the cloud service in the direction of '#{direction}', Descriptor:'#{descriptor}'"
  faxname,faxid = descriptor.split('|')
  if (faxname.nil? or faxid.nil?)
    logger.info "Valid descriptor not provided to get_fax function call.  Descriptor:'#{descriptor}'"
    return nil
  end
  
  postVariables = {   
    :action => "Delete_Fax",
    :sFaxFileName_x => descriptor,
    :sFaxDetailsID_x => faxid,
    :sDirection => direction.upcase, 
  }
  res = execute(postVariables)
  return res
end

.get_fax(descriptor, direction, options = {}) ⇒ Hash

Uses POST Retrieve_Fax to retrieve a specified fax from the server. Returns it in the default specified format (PDF or TIFF)

Parameters:

  • descriptor (String) —

    Specify the status of the message you are listing (UNREAD, ALL, READ)

  • direction (String) —

    Either ‘IN’ or ‘OUT’ to specify the inbox or outbox

  • options (Hash) (defaults to: {}) —

    An optional hash paramter to ovveride any default values (ie., Account ID)

Options Hash (options):

  • :sMarkasViewed (String) —

    Update the fax status to viewed (or unviewed). Accepts ‘Y’ or ‘N’

  • :sFaxFormat (String) —

    Update the format to retrieve the file in (‘PDF’ or ‘TIFF’)

Returns:

  • (Hash) —

    A hash containing the return value (Success/Failure) and the payload where applicable



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/srfax.rb', line 140

def get_fax(descriptor, direction, options = {}) 
  logger.info "Retrieving fax from cloud service in the direction of '#{direction}', Descriptor:'#{descriptor}'"
  faxname,faxid = descriptor.split('|')
  if (faxname.nil? or faxid.nil?)
    logger.info "Valid descriptor not provided to get_fax function call.  Descriptor:'#{descriptor}'"
    return nil
  end
  
  logger.info "Retrieving fax from cloud service"
  postVariables = {   
    :action => "Retrieve_Fax",
    :sFaxFileName => descriptor,
    :sFaxDetailsID => faxid,
    :sDirection => direction.upcase, 
    :sMarkasViewed => 'N'
  }.merge!(options)
  res = execute(postVariables)
  return res
end

.setup { ... } ⇒ Object

Allow configuring Srfax with a block, these will be the methods default values for passing to each function and will be overridden by any methods locally posted variables (ex: :action)

Example:

Srfax.setup do |config|
  config.defaults[:access_id] = '1234'
  config.defaults[:access_pwd] = 'password'
end

Yields:

  • Accepts a block of valid configuration options to set or override default values



52
53
54
 
# File 'lib/srfax.rb', line 52

def setup(&block)
  yield self
end

.update_fax_status(descriptor, direction, options = {}) ⇒ Hash

Update the status (read/unread) for a particular fax

Parameters:

  • descriptor (String) —

    Specify the status of the message you are listing (UNREAD, ALL, READ)

  • direction (String) —

    Either ‘IN’ or ‘OUT’ to specify the inbox or outbox

  • options (Hash) (defaults to: {}) —

    An optional hash paramter to ovveride any default values (ie., Account ID)

Options Hash (options):

  • :sMarkasViewed (String) —

    Update the fax status to viewed (or unviewed). Accepts ‘Y’ or ‘N’. Defaults to Y

Returns:

  • (Hash) —

    A hash containing the return value (Success/Failure) and the payload where applicable



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/srfax.rb', line 167

def update_fax_status(descriptor, direction, options = {})
  logger.info "Updating a fax in the cloud service in the direction of '#{direction}', Descriptor:'#{descriptor}'"
  faxname,faxid = descriptor.split('|')
  if (faxname.nil? or faxid.nil?)
    logger.info "Valid descriptor not provided to get_fax function call.  Descriptor:'#{descriptor}'"
    return nil
  end

  postVariables = {   
    :action => "Update_Viewed_Status",
    :sFaxFileName => descriptor,
    :sFaxDetailsID => faxid,
    :sDirection => direction.upcase, 
    :sMarkasViewed => 'Y',
  }.merge!(options)
  res = execute(postVariables)
  return res
end

.view_inbox(status = 'UNREAD', options = {}) ⇒ Hash

Views the remote inbox. By default this call does NOT update the viewed or read status of the fax unless specified in options.

Example Payload for Return:

{"Status"=>"Success", "Result"=>[{"FileName"=>"20150430124505-6104-19_1|20360095", "ReceiveStatus"=>"Ok", 
"Date"=>"Apr 30/15 02:45 PM", "EpochTime"=>1430423105, "CallerID"=>"9056193547", "RemoteID"=>"", "Pages"=>"1", 
"Size"=>"5000", "ViewedStatus"=>"N"} ]}

Parameters:

  • status (String) (defaults to: 'UNREAD') —

    Specify the status of the message you are listing (UNREAD, ALL, READ)

  • options (Hash) (defaults to: {}) —

    An optional hash paramter to ovveride any default values (ie., Account ID)

Options Hash (options):

  • :sPeriod (String) —

    Specify the period to query. Accepts ‘ALL’ or ‘RANGE’

  • :sStatDate (String) —

    Used with :sPeriod and denotes the period to start at. Format is ‘YYYYMMDD’

  • :sEndDate (String) —

    Used with :sPeriod and denotes the period to endd at. Format is ‘YYYYMMDD’

  • :sIncludeSubUsers (String) —

    Include subuser accounts (‘Y’ or ‘N’)

Returns:

  • (Hash) —

    A hash containing the return value (Success/Failure) and the payload where applicable



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/srfax.rb', line 71

def view_inbox(status = 'UNREAD', options = {})
  logger.info("Checking fax inbox from cloud service")
  postVariables = { 
    :action => "Get_Fax_Inbox", 
    :sViewedStatus => status.upcase
  }.merge!(options)
  res = execute(postVariables)
  
  if res[:Status] != "Failure"
    faxcount = res["Result"].count
    faxcount > 0 ? logger.debug("Found #{faxcount} new fax(es)") : logger.debug("No faxes found matching that criteria")
  end
  
  return res
end

.view_outbox(options = {}) ⇒ Hash

Uses post Get_Fax_Outbox to retrieve the usage for the account (and all subaccounts)

Parameters:

  • options (Hash) (defaults to: {}) —

    An optional hash paramter to ovveride any default values (ie., Account ID)

Options Hash (options):

  • :sPeriod (String) —

    Specify the period to query. Accepts ‘ALL’ or ‘RANGE’

  • :sStatDate (String) —

    Used with :sPeriod and denotes the period to start at. Format is ‘YYYYMMDD’

  • :sEndDate (String) —

    Used with :sPeriod and denotes the period to endd at. Format is ‘YYYYMMDD’

  • :sIncludeSubUsers (String) —

    Include subuser accounts (‘Y’ or ‘N’)

Returns:

  • (Hash) —

    A hash containing the return value (Success/Failure) and the payload where applicable



118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/srfax.rb', line 118

def view_outbox(options = {})
  logger.info "Viewing fax outbox from cloud service"
  postVariables = { :action => "Get_Fax_Outbox" }
  res = execute(postVariables)
  
  if res[:Status] != "Failure"
    faxcount = res["Result"].count
    faxcount > 0 ? logger.debug("Found #{faxcount} new fax(es)") : logger.debug("No faxes found matching that criteria")
  end
  
  return res
end

.view_usage(options = {}) ⇒ Hash

Uses post Get_Usage to fetch the current account usage statistics (for all associated accounts)

Example Payload for Return:

{"Status"=>"Success", "Result"=>[{"UserID"=>1234, "Period"=>"ALL", 
"ClientName"=>nil, "SubUserID"=>0, "BillingNumber"=>"8669906402", "NumberOfFaxes"=>5, "NumberOfPages"=>8}]}

optional variables

sPeriod: (ALL or RANGE), sStartDate: YYYYMMDD, sEndDate: YYYYMMDD
sIncludeSubUsers: Y or N  (if you want to see all faxes on subaccounts as well)

Parameters:

  • options (Hash) (defaults to: {}) —

    An optional hash paramter to ovveride any default values (ie., Account ID)

Options Hash (options):

  • :sPeriod (String) —

    Specify the period to query. Accepts ‘ALL’ or ‘RANGE’

  • :sStatDate (String) —

    Used with :sPeriod and denotes the period to start at. Format is ‘YYYYMMDD’

  • :sEndDate (String) —

    Used with :sPeriod and denotes the period to endd at. Format is ‘YYYYMMDD’

  • :sIncludeSubUsers (String) —

    Include subuser accounts (‘Y’ or ‘N’)

Returns:

  • (Hash) —

    A hash containing the return value (Success/Failure) and the payload where applicable



103
104
105
106
107
108
 
# File 'lib/srfax.rb', line 103

def view_usage(options = {})
  logger.info "Viewing fax usage from cloud service"
  postVariables = { :action => "Get_Fax_Usage" }
  res = execute(postVariables)
  return res
end