Class: MxHero::API::Client

Inherits:
Object
  • Object
show all
Includes:
Communication, Urls
Defined in:
lib/mxhero-api.rb

Overview

A client to interact with mxhero engine API

Instance Method Summary collapse

Methods included from Urls

#domain_by_id_url, #domains_url, #service_url

Methods included from Communication

#call, #headers, #json_parse

Constructor Details

#initialize(config = {}) ⇒ Client

Returns a new instance of Client.

Options Hash (config):

  • :api_url (String) —

    The URL to consume the API

  • :username (String) —

    The username for access the API

  • :password (String) —

    The password for the user that access the API

  • :verbose (Boolean) — default: false —

    If true puts information about http operations

  • :as_user (String) —

    Send to the API to indentify the end user (app user email)



34
35
36
37
38
39
40
 
# File 'lib/mxhero-api.rb', line 34

def initialize(config = {})
  @service_url = config[:api_url]
  @username = config[:username]
  @password = config[:password]
  @verbose = config[:verbose] || false
  @as_user = config[:as_user]
end

Instance Method Details

#account_properties(domain, account) ⇒ MxHero::API::Response 



340
341
342
343
344
345
346
347
348
349
 
# File 'lib/mxhero-api.rb', line 340

def (domain, )
  url = (domain, )
  response = call(:get, url)
  if response.status == 200
    props = {}
    json_parse(response.content).each { |property| props[property[:name]] = property[:value] }
    return Response.new(response.code, props)
  end
  parse_response(response)
end

#accounts_by_domain(domain, refinement = {}) ⇒ Hash

Retrive all the account from one domain

Options Hash (refinement):

  • :limit (Fixnum) —

    of elements per page

  • :offset (Fixnum) —

    number of page (start in 1)

  • :account (String) —

    filter accounts that start with this value

  • :without_group (Boolean) —

    filter accounts without group

Raises:

  • an exception when the status code isn’t 200



244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/mxhero-api.rb', line 244

def accounts_by_domain(domain, refinement = {}) #filter_account = nil, pagination = {})
  params = refinement.dup
   = params.delete(:account)
   = CGI::escape() if 
  without_group = params.delete(:without_group) || false
  limit, offset = params.values_at(:limit, :offset)

  if without_group
    url = accounts_without_group_url(domain, )
  else
    url = paginate accounts_by_domain_url(domain, ), { limit: limit, offset: offset }
  end
  response = call(:get, url)
  json_parse(response.content)
end

#accounts_without_group_url(domain, filter_account) ⇒ Object 



260
261
262
 
# File 'lib/mxhero-api.rb', line 260

def accounts_without_group_url(domain, )
  domain_by_id_url(domain) + "/groups/accounts/available?account=#{filter_account}"
end

#add_feature(domain_name, feature_component) ⇒ Boolean

Create a new domain base on domain_obj hash

Hash

with detailed domain

* :domain [String]
* :server [String]
* :inbound [Boolean]
* :outbound [Boolean]
* :features [Array<Hash>]
* :cos [Hash]
* :source [String] (gapps|on_premise|ms_agent|office365)
* :aliases [Array<String>]
* :ldap [Hash]



161
162
163
164
165
166
167
168
 
# File 'lib/mxhero-api.rb', line 161

def add_feature(domain_name, feature_component)
  feature = {
    feature: feature_component,
    maxRulesAmount: 1
  }
  response = call(:post, features_url(domain_name), feature.to_json, throw_exception: false)
  response.status == 200
end

#associate_user_domain(user, domain) ⇒ Object

Associate domains with an existing user



479
480
481
482
483
 
# File 'lib/mxhero-api.rb', line 479

def associate_user_domain(user, domain)
  domain_obj = { domain: domain }
  response = call(:post, user_domains_url(user), domain_obj.to_json, throw_exception: false)
  response.status == 200
end

#create_domain(domain_obj = {}) ⇒ Boolean

Create a new domain base on domain_obj hash

Hash

with detailed domain

* :domain [String]
* :server [String]
* :inbound [Boolean]
* :outbound [Boolean]
* :features [Array<Hash>]
* :cos [Hash]
* :source [String] (gapps|on_premise|ms_agent|office365)
* :aliases [Array<String>]
* :ldap [Hash]



135
136
137
138
 
# File 'lib/mxhero-api.rb', line 135

def create_domain(domain_obj = {})
  response = call(:post, domains_url, domain_obj.to_json, throw_exception: false)
  response.status == 201
end

#create_rule_for_domain(domain, msg) ⇒ MxHero::API::Response

Options Hash (msg):

  • :domain (String)
  • :twoWays (Boolean)
  • :enabled (Boolean)
  • :name (String)
  • :created (Integer) —

    in epoch format

  • :fromDirection (Hash)
  • :toDirection (Hash)
  • :properties (Array<Hash>)
  • :component (String) 


285
286
287
288
289
 
# File 'lib/mxhero-api.rb', line 285

def create_rule_for_domain(domain, msg)
  url = rules_for_domain_url(domain)
  response = call(:post, url, msg.to_json, throw_exception: false)
  parse_response(response)
end

#create_user(user_info, *domains) ⇒ Object

Create a new user

Options Hash (user_info):

  • :name (String)
  • :lastName (String)
  • :notifyEmail (String)
  • :userName (String)
  • :locale (String)
  • :password (String) 


462
463
464
465
466
467
468
469
470
471
472
473
 
# File 'lib/mxhero-api.rb', line 462

def create_user(, *domains)
  user = {
    name: "", lastName: "", notifyEmail: "",
    userName: "", locale: "en_US", password: "1234",
    authorities: ["ROLE_DOMAIN_ADMIN"],
    created: DateTime.now.strftime('%Q'),
    domains: domains.map { |domain| { domain: domain } }
  }
  user.merge!()
  response = call(:post, users_url, user.to_json, throw_exception: false)
  response.status == 201
end

#delete_rule(domain, id) ⇒ Boolean 



325
326
327
328
329
330
 
# File 'lib/mxhero-api.rb', line 325

def delete_rule(domain, id)
  url = domain_rule_url(domain, id)
  response = call(:delete, url)
  return true if response.status == 200
  return false
end

#directories(domain) ⇒ Object

Expose directories api



45
46
47
48
49
 
# File 'lib/mxhero-api.rb', line 45

def directories(domain)
  @directories ||= Directories.new(domain, api_url: @service_url,
                                   username: @username, password: @password,
                                   verbose: @verbose, as_user: @as_user)
end

#domain(name) ⇒ Domain

Retrive the domain information

Raises:

  • an exception when the status code is not 200 (ok) or 404 (not found)



177
178
179
180
181
 
# File 'lib/mxhero-api.rb', line 177

def domain(name)
  domain_info = fetch domain_by_id_url(name), on_error: "An error ocurred when try to fetch the domain #{name}."
  return nil unless domain_info
  Domain.new domain_info
end

#domain_rule(domain, id) ⇒ Hash?

Find a rule by domain and ID

Raises:

  • an exception when the status code isn’t 200



59
60
61
62
63
64
 
# File 'lib/mxhero-api.rb', line 59

def domain_rule(domain, id)
  url = domain_rule_url(domain, id)
  response = call(:get, url)
  raise 'an error ocurred when try to communicate with the API' if response.status != 200
  json_parse(response.content)
end

#domains(params = {}) ⇒ Hash

Retrive all the domains

TODO: Improve the response. We really need manage pagination here?

Raises:

  • an exception when the status code isn’t 200



99
100
101
102
103
104
105
106
107
 
# File 'lib/mxhero-api.rb', line 99

def domains(params = {})
  url = domains_url
  limit, offset = params.values_at(:limit, :offset)
  url = paginate(domains_url, { limit: limit, offset: offset }) if limit && offset
  response = call(:get, url)
  raise 'an error ocurred when try to communicate with the API' if response.status != 200
  response_as_a_hash = json_parse(response.content)
  response_as_a_hash
end

#fetch_user(user) ⇒ MxHero::API::Response | nil

Fetch the user



442
443
444
445
446
447
448
 
# File 'lib/mxhero-api.rb', line 442

def fetch_user(user)
  response = call(:get, user_url(user))
  if response.status == 200
    return parse_response(response)
  end
  nil
end

#ldap_info(domain) ⇒ Hash

Fetch the LDAP information of the domain



208
209
210
211
 
# File 'lib/mxhero-api.rb', line 208

def ldap_info(domain)
  fetch domain_by_id_url(domain) + '/adldap',
    on_error: "An error was ocurred when try to fecht the ldap information of #{domain}"
end

#move_to_trial(domain) ⇒ Object

Move COS to trial



112
113
114
115
116
 
# File 'lib/mxhero-api.rb', line 112

def move_to_trial(domain)
  url = domain_by_id_url(domain) + '/cos/trial'
  response = call(:put, url)
  response.status == 200
end

#regex_tester(test_msg) ⇒ Object

test_msg example: { “matching”:{ “matcher”: [ { “default”:false, “type”:“regex”, “regex”:“(.*)@(.*)”, “toValue”:“$2/$1/$0” } ], “placeholder”:“email” }, “value”:“[email protected]”, “key”:“email” }

Response HTTP: 200 OK MxHero::API::Client.“result”:“example“result”:“example.org/smith/smith@example“result”:“example.org/smith/[email protected]”

On error, response: HTTP Status 500 

"status": 500,
"code": 500,
"developerMessage": "Dangling meta character '*' near index 0\n*.(.*)@(.*)\n^",
"moreInfoUrl": "mailto:[email protected]"




552
553
554
555
 
# File 'lib/mxhero-api.rb', line 552

def regex_tester(test_msg)
  response = call(:put, service_url + '/regex/check/pattern', test_msg.to_json, throw_exception: false)
  parse_response(response)
end

#reset_password(user_name) ⇒ Object 



518
519
520
521
 
# File 'lib/mxhero-api.rb', line 518

def reset_password(user_name)
  response = call(:get, user_url_reset_password(user_name), throw_exception: false)
  response.status == 200
end

#rule_status(domain, rule_id, enabled = true) ⇒ Object

In case of error, the message is completed with the cause of error



76
77
78
79
80
 
# File 'lib/mxhero-api.rb', line 76

def rule_status(domain, rule_id, enabled = true)
  url = domain_rule_url(domain, rule_id)+"/status?enabled=#{enabled}"
  response = call(:put, url)
  parse_response(response)
end

#rules_for_domain(domain, component = nil) ⇒ MxHero::API::Response

Retrieve all the rules for one domain



317
318
319
320
321
322
 
# File 'lib/mxhero-api.rb', line 317

def rules_for_domain(domain, component = nil)
  url = rules_for_domain_url(domain)
  url << "?component=#{component}" if component
  response = call(:get, url)
  parse_response(response, on_empty: [])
end

#save_system_property(key, value) ⇒ Object

Update or create a system property



404
405
406
407
408
409
410
411
412
413
 
# File 'lib/mxhero-api.rb', line 404

def save_system_property(key, value)
  property = { key: key, value: value }.to_json
  response = if system_properties(key).nil?
    call(:post, system_properties_url, property)
  else
    call(:put, system_properties_url(key), property)
  end

  parse_response(response).success?
end

#set_new_password(user_name, new_password) ⇒ Object 



513
514
515
516
 
# File 'lib/mxhero-api.rb', line 513

def set_new_password(user_name, new_password)
  response = call(:put, user_url_set_password(user_name, new_password), throw_exception: false)
  response.status == 200
end

#system_properties(key = nil) ⇒ Hash|String|nil 



387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
 
# File 'lib/mxhero-api.rb', line 387

def system_properties(key = nil)
  response = call(:get, system_properties_url(key))
  if response.status == 200
    parsed = json_parse(response.content)
    if parsed.is_a? Array
      props = {}
      parsed.each { |property| props[property[:key]] = property[:value] }
      return props
    else
      return parsed[:value]
    end
  end

  nil
end

#unassociate_user_domain(user, domain) ⇒ Object

Unassociate specific domain from an user admin



489
490
491
492
 
# File 'lib/mxhero-api.rb', line 489

def unassociate_user_domain(user, domain)
  response = call(:delete, user_with_domain_url(user,domain), throw_exception: false)
  response.status == 200
end

#update_account_properties(domain, account, properties) ⇒ MxHero::API::Response 



356
357
358
359
360
 
# File 'lib/mxhero-api.rb', line 356

def (domain, , properties)
  url = (domain, )
  response = call(:put, url, (properties))
  parse_response(response)
end

#update_accounts(domain, accounts, scope = :properties) ⇒ Object 



368
369
370
371
372
373
374
375
376
377
378
379
380
381
 
# File 'lib/mxhero-api.rb', line 368

def update_accounts(domain, accounts, scope = :properties)
  scope_param = scope == :both ? 'groups,properties' : scope.to_s
  #url = "/domains/#{domain}/accounts/upload?scope=#{scope_param}"
  url = accounts_by_domain_url(domain) + "/upload?scope=#{scope_param}"

  message = []
  accounts.each do ||
    properties = remap_properties([:properties])
    message << { account: [:account], properties: properties, group: [:group], domain: domain }
    #message << { account: account[:account], properties: properties, group: account[:group] }
  end
  response = call(:put, url, message.to_json) # accounts to json
  parse_response(response)
end

#update_domain(domain, domain_obj = {}) ⇒ Object 



140
141
142
143
 
# File 'lib/mxhero-api.rb', line 140

def update_domain(domain, domain_obj = {})
  response = call(:put, domain_by_id_url(domain), domain_obj.to_json, throw_exception: false)
  response.status == 200
end

#update_rule(rule) ⇒ MxHero::API::Response

Update a rule



69
70
71
72
73
 
# File 'lib/mxhero-api.rb', line 69

def update_rule(rule)
  url = domain_rule_url(rule[:domain], rule[:id])
  response = call(:put, url, rule.to_json)
  parse_response(response)
end

#update_user(user, user_name) ⇒ Object

Update user



500
501
502
503
 
# File 'lib/mxhero-api.rb', line 500

def update_user(user, user_name)
  response = call(:put, user_url(user_name), user.to_json, throw_exception: false)
  parse_response(response)
end

#user_domains(user) ⇒ Array<String>|nil

Obtain the list of domains to one user



430
431
432
433
434
435
436
437
438
 
# File 'lib/mxhero-api.rb', line 430

def user_domains(user)
  domains = nil
  response = call(:get, user_domains_url(user))
  if response.status == 200
    content = json_parse(response.content)
    domains = content.map { |info| info[:domain] }
  end
  domains
end

#users_for_domain(domain) ⇒ Array<UserVO>|nil

Obtain the list of users admin in a specific domain



418
419
420
421
422
423
424
425
 
# File 'lib/mxhero-api.rb', line 418

def users_for_domain(domain)
  users = nil
  response = call(:get, users_for_domain_url(domain), throw_exception: false)
  if response.status == 200
    users = json_parse(response.content)
  end
  users
end

#valid_user_credentials?(user, password) ⇒ Boolean

Validate if the an user and password match



507
508
509
510
511
 
# File 'lib/mxhero-api.rb', line 507

def valid_user_credentials?(user, password)
  validate_user_credential_url = user_url(user) + "/password/check"
  response = call(:post, validate_user_credential_url, password, { content_type: 'text/plain' })
  response.status == 204
end

#verbose=(verbose) ⇒ Object 



268
269
270
 
# File 'lib/mxhero-api.rb', line 268

def verbose=(verbose)
  @verbose = verbose
end

#verbose? ⇒ Boolean 



264
265
266
 
# File 'lib/mxhero-api.rb', line 264

def verbose?
  @verbose
end