Module: SrFax

Defined in:
lib/srfax.rb,
lib/srfax/version.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 – Retrieves the account usage.
Update_Viewed_Status – Mark a inbound or outbound fax as read or unread.
Queue_Fax - Schedules a fax to be sent with or without cover page.
Get_Fax_Inbox - Returns a list of faxes received for a specified period of time.
Get_Fax_Outbox - Returns a list of faxes sent for a specified period of time.
Retrieve_Fax – Returns a specified sent or received fax file in PDF or TIFF format.
Delete_Fax - Deletes specified received or sent faxes.
Get_FaxStatus – Determines the status of a fax that has been scheduled for delivery.
Get_MultiFaxStatus – Determines the status of a multiple faxes that have been
   scheduled for delivery.
Stop_Fax - Removes a scheduled fax from the queue.

Unimplemented methods:

Delete_Pending_Fax - THIS DOESN'T EXIST - but is documented to exist.

Constant Summary collapse

BASE_URL =

Base URL for accessing SRFax API

'https://www.srfax.com/SRF_SecWebSvc.php'.freeze
VERSION = 
'0.5.5'.freeze
@@defaults =

Default values hash to use with all #execute commands

{
  access_id: '1234',
  access_pwd: 'password',
  sFaxFormat: 'PDF', # Default format, PDF or TIF
  sCallerID: '5555555555', # MUST be 10 digits
  sResponseFormat: 'JSON' # XML or JSON
}
@@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"=>"5555555555", "RemoteID"=>"", "Pages"=>"1",
"Size"=>"5000", "ViewedStatus"=>"N"} ]}

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



280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
 
# File 'lib/srfax.rb', line 280

def delete_fax(descriptor, direction)
  logger.debug "Deleting a fax in the cloud service in the direction of '#{direction}', Descriptor: '#{descriptor}'"
  faxname, faxid = descriptor.split('|')
  if faxname.nil? || faxid.nil?
    logger.debug "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)
  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



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

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

  logger.debug 'Retrieving fax from cloud service'
  postVariables = {
    action: 'Retrieve_Fax',
    sFaxFileName: descriptor,
    sFaxDetailsID: faxid,
    sDirection: direction.upcase,
    sMarkasViewed: 'N'
  }.merge!(options)
  res = execute(postVariables)
  res
end

.get_fax_status(faxids, options = {}) ⇒ Hash

Schedules a fax to be sent with or without cover page

Parameters:

  • faxids (String, Array) —

    Get the state of ‘id’ as given by the #queue_fax call

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

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

Options Hash (options):

  • :sResponseFormat (String) —

    The output response format for

Returns:

  • (Hash) —

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



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

def get_fax_status(faxids, options = {})
  logger.debug "Gathering fax status information for id(s): '#{faxids}'"

  if faxids.is_a? String
    action = 'Get_FaxStatus'
  elsif faxids.is_a? Array
    action = 'Get_MultiFaxStatus'
    faxids = faxids.join('|')
  else
    logger.warn "Error wth fax ids parameter id(s): '#{faxid}'"
    return { Status: 'Failure' }
  end

  postVariables = {
    action: action,
    sFaxDetailsID: faxids
  }.merge!(options)
  res = execute(postVariables)
  res
end

.queue_fax(senderEmail, receiverNumber, faxType, options = {}) ⇒ Hash

Determines the state of a fax that has been scheduled for delivery. Use queue fax to schedule a fax for delivery. Note: no validation is done on the fields prior to sending.

Example code (this will send a fax with ‘Sample Fax’ as the fileContent field):

SrFax.queue_fax "[email protected]", "18888888888", "SINGLE", {sFileName_1: "file1.txt", sFileContent_1: Base64.encode64("Sample Fax")}

Parameters:

  • senderEmail (String) —

    Email address of the sender

  • receiverNumber (String, Array) —

    Single 11 digit fax number or up to 50 x 11 fax numbers

  • faxType (String) —

    ‘SINGLE’ or ‘BROADCAST’

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

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

Options Hash (options):

  • :sResponseFormat (String) —

    The output response format for

  • :sAccountCode (String) —

    Internal reference number (Max of 20 Characters)

  • :sRetries (String) —

    Number of times the system is to retry a number if busy or an error is encountered – number from 0 to 6.

  • :sCoverPage (String) —

    If you want to use one of the cover pages on file, specify the cover page you wish to use “Basic”, “Standard” , “Company” or “Personal”. If a cover page is not provided then all cover page variable will be ignored. NOTE: If the default cover page on the account is set to “Attachments ONLY” the cover page will NOT be created irrespective of this variable.

  • :sFaxFromHeader (String) —

    From: On the Fax Header Line (max 30 Char)

  • :sCPFromName (String) —

    Sender’s name on the Cover Page

  • :sCPToName (String) —

    Recipient’s name on the Cover Page

  • :sCPOrganization (String) —

    Organization on the Cover Page

  • :sCPSubject (String) —

    Subject line on the Cover Page**

  • :sCPComments (String) —

    Comments placed in the body of the Cover Page

  • :sFileName_x (String) — default: See supported file types @ https://www.srfax.com/faqs
  • :sFileContent_x (String) —

    Base64 encoding of file contents.

  • :sNotifyURL (String) —

    Provide an absolute URL (beginning with http:// or https://) and the SRFax system will POST back the fax status record when the fax completes. See the ‘NOTIFY URL POST’ section below for details of what is posted.

Returns:

  • (Hash) —

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



240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/srfax.rb', line 240

def queue_fax(senderEmail, receiverNumber, faxType, options = {})
  logger.debug 'Attempting to queue fax'
  receiverNumber = receiverNumber.join('|') if receiverNumber.is_a? Array

  postVariables = {
    action: 'Queue_Fax',
    sSenderEmail: senderEmail,
    sFaxType: faxType,
    sToFaxNumber: receiverNumber
  }.merge!(options)
  res = execute(postVariables)
  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'
  config.defaults[:sCallerID] = '5555555555'
end

Yields:

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



59
60
61
 
# File 'lib/srfax.rb', line 59

def setup
  yield self
end

.stop_fax(faxid, options = {}) ⇒ Hash

Attempt to stop a fax from being delivered. See the result payload for possible conditions in fax status

Parameters:

  • faxid (String) —

    Stop fax with ‘id’ as given by the #queue_fax call.

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

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

Returns:

  • (Hash) —

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



259
260
261
262
263
264
265
266
267
268
 
# File 'lib/srfax.rb', line 259

def stop_fax(faxid, options = {})
  logger.debug "Sending stop fax command for id: '#{faxid}'"

  postVariables = {
    action: 'Stop_Fax',
    sFaxDetailsID: faxid
  }.merge!(options)
  res = execute(postVariables)
  res
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



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

def update_fax_status(descriptor, direction, options = {})
  logger.debug "Updating a fax in the cloud service in the direction of '#{direction}', Descriptor: '#{descriptor}'"
  faxname, faxid = descriptor.split('|')
  if faxname.nil? || faxid.nil?
    logger.debug "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)
  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"=>"5555555555", "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



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/srfax.rb', line 78

def view_inbox(status = 'UNREAD', options = {})
  logger.debug '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'].length
    faxcount > 0 ? logger.debug("Found #{faxcount} new fax(es)") : logger.debug('No faxes found matching that criteria')
  end

  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



121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/srfax.rb', line 121

def view_outbox(options = {})
  logger.debug 'Viewing fax outbox from cloud service'
  postVariables = { action: 'Get_Fax_Outbox' }
  res = execute(postVariables)

  if res[:Status] != 'Failure'
    faxcount = res['Result'].length
    faxcount > 0 ? logger.debug("Found #{faxcount} new fax(es)") : logger.debug('No faxes found matching that criteria')
  end

  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"=>"8888888888", "NumberOfFaxes"=>5, "NumberOfPages"=>8}]}

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



106
107
108
109
110
111
 
# File 'lib/srfax.rb', line 106

def view_usage(options = {})
  logger.debug 'Viewing fax usage from cloud service'
  postVariables = { action: 'Get_Fax_Usage' }
  res = execute(postVariables)
  res
end