Class: Postini::AutomatedBatchService

Inherits:
Handsoap::Service
  • Object
show all
Includes:
ConfigurationCheck
Defined in:
lib/postini/automated_batch_service.rb

Instance Method Summary collapse

Methods included from ConfigurationCheck

included

Instance Method Details

#add_alias(user_address, alias_address, confirm = true) ⇒ Object

Associates an additional address with a user’s primary email address. The alias receives the same filtering and shares the same User Ouarantine as the user’s primary email address.

  • confirm - If an existing user address is being overwritten to

    become an alias address, use confirm

Raises a Postini::BatchError if something goes wrong



32
33
34
35
36
37
38
39
40
41
 
# File 'lib/postini/automated_batch_service.rb', line 32

def add_alias( user_address, alias_address, confirm = true )
  response = invoke("aut:addalias") do |message|
    build_auth!( message )
    message.add('userAddressOrId', user_address)
    message.add('aliasAddress', alias_address)
    message.add('confirm', 'confirm') if confirm
  end

  true
end

#add_domain(orgid, name) ⇒ Object

Adds the domain record name to the organization orgid. Enclose orgid in double quotes or preceded with a ‘' symbol if it contains a quote (’), double quote (“), backslash (), apostrophe, commas, #, = symbols.

Raises a Postini::BatchException if something goes wrong



50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/postini/automated_batch_service.rb', line 50

def add_domain( orgid, name )
  response = invoke( "aut:adddomain" ) do |message|
    build_auth!( message )
    message.add('orgNameOrId', orgid )
    message.add('args') do |args|
      args.add('domain', name)
    end
  end

  true
end

#add_user(orgid, address, welcome = false) ⇒ Object

Adds a user (address) to an organization (org). Enclose orgid in double quotes or preceded with a ‘' symbol if it contains a quote (’), double quote (“), backslash (), apostrophe, commas, #, = symbols.

Raises a Postini::BatchException if something foes wrong



69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/postini/automated_batch_service.rb', line 69

def add_user( orgid, address, welcome = false )
  response = invoke("aut:adduser") do |message|
    build_auth!( message )
    message.add('userAddress', address)
    message.add('args') do |args|
      args.add('org', orgid)
      args.add('welcome', welcome)
    end
  end

  true
end

#check_auth(email = nil, password = nil, api_key = nil) ⇒ Object

This operation is an Service Management API’s AutomatedBatch utility. It checks the user’s email, API license key, and password authentication tokens used for connection and authorization validation between the web service and the client.

  • email - The email address entered by the user.

  • apiKey - A unique customer and product ID.

  • password – The PMP password entered by the user.

If the organization is configured for POP authorization, always use the administrator’s email login and password which will be in the PMP format. An end user’s POP password will fail.



95
96
97
98
99
100
101
 
# File 'lib/postini/automated_batch_service.rb', line 95

def check_auth( email = nil, password = nil, api_key = nil )
  response = invoke("aut:checkauth") do |message|
    build_auth!( message, email, password, api_key )
  end

  return true
end

#delete_alias(alias_address) ⇒ Object

Removes the specified alias completely from the email security service.



106
107
108
109
110
111
112
113
 
# File 'lib/postini/automated_batch_service.rb', line 106

def delete_alias( alias_address )
  response = invoke("aut:deletealias") do |message|
    build_auth!( message )
    message.add('aliasAddress', alias_address)
  end

  return true
end

#delete_domain(name) ⇒ Object

Removes the domain from the organizational hierarchy. All the users for the domain needs to be removed first by #delete_user.

Raises a Postini::BatchException if something goes wrong



120
121
122
123
124
125
126
127
 
# File 'lib/postini/automated_batch_service.rb', line 120

def delete_domain( name )
  response = invoke("aut:deletedomain") do |message|
    build_auth!( message )
    message.add('domainNameOrId', name)
  end

  true
end

#delete_user(address) ⇒ Object

Delete a user record from the email security service.

Raises a Postini::BatchExceptio if something goes wrong



133
134
135
136
137
138
139
140
 
# File 'lib/postini/automated_batch_service.rb', line 133

def delete_user( address )
  response = invoke("aut:deleteuser") do |message|
    build_auth!( message )
    message.add('userAddressOrId', address)
  end

  true
end

#display_domain(name) ⇒ Object

Retrieve the details of the domain from the email security service as a hash with the following keys:

:org => string - Name of the parent org :substrip => true/false - Whether sub domain stripping in enabled :aliased_to => nil/string - Alias of another domain :aliased_as => array - List of domain aliases :id => integer - Domain id :name => string - Domain name



152
153
154
155
156
157
158
159
 
# File 'lib/postini/automated_batch_service.rb', line 152

def display_domain( name )
  response = invoke("aut:displaydomain") do |message|
    build_auth!( message )
    message.add('domainNameOrId', name )
  end

  parse_display_domain_results( response.document.xpath('//tns:displaydomainResponse', tns).first )
end

#display_user(address) ⇒ Object

Retrieve the details of the user from the email securty service as a hash with following keys:

:active => bool :address => string :approved_recipients => array :approved_senders => array :blocked_senders => array :create_method => integer :created_date => Time :filter_adult => string :filter_bulk => string :filter_getrich => string :filter_offers => string :filter_racial => string :initial_password => string :junkmail_filter => bool :lang_locale => string :lastmod_date => Time :message_encryption => string :message_limit => string :message_limited => bool :message_count => integer :notice_address => string :org => string :password => string :timezone => string :id => integer :virus_notify => string :virus_state => bool :weblocked => bool :welcome_count => integer :wireless_state => string



195
196
197
198
199
200
201
202
 
# File 'lib/postini/automated_batch_service.rb', line 195

def display_user( address )
  response = invoke("aut:displayuser") do |message|
    build_auth!( message )
    message.add('userAddressOrId', address)
  end

  parse_display_user_results( response.document.xpath('//tns:displayuserResponse', tns).first )
end

#list_orgs(query_string = 'ALL', options = {}) ⇒ Object

Return a list of orgs, possibly filtered and sorted. Refer to the Postini Automated Batch Service Manual for an explanation of each field.

Possible options are:

:targetOrg => string :childorgs => boolean :sort => string :fields => array (strings) :start => integer :end => integer

Postini will return a maximum of 15,000 results



218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/postini/automated_batch_service.rb', line 218

def list_orgs( query_string = 'ALL', options = {} )
  valid_options = {}

  # vanilla copes
  [ :targetOrg, :sort, :start, :end ].each do |k|
    valid_options[k] = options[k] if options.has_key?(k)
  end

  # boolean copies
  valid_options[:childorgs] = ( options[:childorgs] ? '1' : '0' ) if options.has_key?(:childorgs)

  valid_options[:fields] = options[:fields].join('|') if options.has_key?(:fields)

  response = invoke("aut:listorgs") do |message|
    build_auth!( message )
    message.add('queryString', query_string)
    message.add('queryParams') do |q|
      valid_options.each do |k,v|
        q.add( k.to_s, v )
      end
    end
  end

  parse_list_orgs_results( response.document.xpath('//tns:listorgsResponse', tns).first )
end

#list_users(query_string = 'ALL', options = {}) ⇒ Object

Return a list of users, possibly filtered and sorted. Refer to the Postini Automated Batch Service Manual for an explanation of each field.

Possible options are:

:aliases => boolean :childorgs => boolean :start => integer :end => integer :fields => array (strings) :orgtagqs => string :primaryqs => string :targetOrg => string :type_of_user => string

The call returns a giant hash, keys are the addresses returned by the operation, and the values are hashes of key-value pairs are returned by the remote service.



264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/postini/automated_batch_service.rb', line 264

def list_users( query_string = 'ALL', options = {} )

  valid_options = {}

  # vanilla copies
  [ :start, :end, :orgtagqs, :primaryqs, :targetOrg, :type_of_user ].each do |k|

    valid_options[k] = options[k] if options.has_key?(k)
  end

  # boolean copies
  [ :aliases, :childorgs ].each do |k|

    if options.has_key?(k)
      valid_options[k] = ( options[k] == true ? '1' : '0' )
    end
  end

  valid_options[:fields] = options[:fields].join('|') if options.has_key?(:fields)

  response = invoke("aut:listusers") do |message|
    build_auth!( message )
    message.add('queryString', query_string)
    message.add('queryParams') do |q|
      valid_options.each do |k,v|
        q.add( k.to_s, v )
      end
    end
  end

  parse_list_users_results( response.document.xpath('//tns:listusersResponse', tns).first )
end

#modify_domain(name, changes = {}) ⇒ Object

Modify a domain by moving it to a new organization, setting or removing aliases, or enabling/disabling subdomain stripping. Changes are passed as a hash with the following keys:

:org => string - New organization to move domain to :substrip => bool - New new value for substrip :aliases => array - Add new domain aliases to the array, to

remove an existing domain alias prepend the name
with a hyphen (-)



307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
 
# File 'lib/postini/automated_batch_service.rb', line 307

def modify_domain( name, changes = {} )
  valid_changes = {}
  valid_changes['neworg'] = changes[:org] if changes.has_key?(:org)
  if changes.has_key?(:substrip)
    valid_changes['substrip'] = ( changes[:substrip] == true ? 'yes' : 'no' )
  end
  valid_changes['alias'] = changes[:aliases].to_a.join(', ') if changes.has_key?(:aliases)

  response = invoke("aut:modifydomain") do |message|
    build_auth!( message )
    message.add('domainNameOrId', name)
    message.add('domainModifications') do |mods|
      valid_changes.each do |k,v|
        mods.add( k, v )
      end
    end
  end

  display_domain( name )
end

#modify_user(address, changes = {}) ⇒ Object

Modify a user extensively by providing any of the following keys in the changes hash

:active => bool :address => string (change the email address) :approved_recipients => array (full or changes) :approved_senders => array (full or changes) :blocked_senders => array (full or changes) :filter_adult => string :filter_bulk => string :filter_getrich => string :filter_offers => string :filter_racial => string :initial_password => string :junkemail_filter => bool :lang_locale => string :message_limit => integer :message_limited => bool :notice_address => string :org => string :password => string :virus_notify => bool :virus_state => bool :weblocked => bool :wireless_state => string

Notes on array parameters: Provide the full set of values, or an array of diffs (new entries prepended with a plus (+) and entries to be removed prepended with a hyphen (-).

Notes on all parameters: I don’t use all of these, nor will I ever, so please test them well and report any bugs to me.



361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
 
# File 'lib/postini/automated_batch_service.rb', line 361

def modify_user( address, changes = {} )
  valid_changes = {}
  valid_changes[:orgid] = changes[:org] if changes.has_key?(:org)

  # Vanilla string copies
  [ :active, :address, :filter_adult, :filter_bulk, :filter_getrich,
    :filter_offers, :filter_racial, :initial_password, :lang_locale,
    :notice_address, :password, :wireless_state, :message_limit
  ].each do |k|

    valid_changes[k] = changes[k] if changes.has_key?(k)
  end

  # Booleans need some special handling
  [ :active, :junkemail_filter, :message_limited, :virus_notify,
    :virus_state, :weblocked
  ].each do |k|

    if changes.has_key?(k)
      valid_changes[k] = ( changes[k] == true ? 'yes' : 'no' )
    end
  end

  # Join the arrays
  [ :approved_senders, :approved_recipients, :blocked_senders ].each do |k|

    if changes.has_key?( k )
      valid_changes[k] = changes[k].join(', ')
    end
  end

  # pray
  response = invoke("aut:modifyuser") do |message|
    build_auth!( message )
    message.add('userAddressOrId', address)
    message.add('userModifications') do |mods|
      valid_changes.each do |k,v|
        mods.add( k.to_s, v )
      end
    end
  end

  address = valid_changes[:address] || address

  display_user( address )
end

#on_fault(fault) ⇒ Object 



13
14
15
16
17
18
19
20
 
# File 'lib/postini/automated_batch_service.rb', line 13

def on_fault( fault )
  exception = RemoteException.delegate( fault.reason )

  # Handle specifics, translate to higher level exception

  # or raise
  raise exception
end

#test(pass = true) ⇒ Object

Determines if connections to the web service and the web service client are not blocked. It is a simple round trip test.

  • true - The connection is successful. If it fails, the

    development tool will throw either an error, or warning
depending upon the type of failure.

  • false - To test the exception handling between the web service

    and the application, use test<false> which will
complete the roundtrip between the servers and return
a StatusException.

The Endpoint Resolver web service is not used with the test command.



421
422
423
424
425
426
427
 
# File 'lib/postini/automated_batch_service.rb', line 421

def test( pass = true )
  response = invoke("aut:test") do |message|
    message.add('should_work', pass)
  end

  parse_test_results( response.document.xpath('//tns:testResponse', tns).first )
end