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.

Parameters:

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

    the options of configuration

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

Returns reponse the key :msg contains a Hash with the key, value of any property. Example:

{ 'email': '[email protected]', 'name': 'John', 'lastname': 'Doe', ... }.

Parameters:

  • domain (String)
  • account (String) —

    Ex.: test or mxhero (the user name)

Returns:



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

Parameters:

  • refinement (Hash) (defaults to: {})

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

Returns:

  • (Hash) —

    with the following elements:

    • :elements [Array<Hash>] the list of accounts as a Hash, when any element contains:

      • :account [String] example: alex

      • :domain [String] example: mxhero.com

      • :createdDate [Fixnum] example: 1375909565000 (epoch format)

      • :updatedDate [Fixnum]

      • :group [String]

      • :aliases [Array<Hash>] the list of aliases of one account

        • :name [String]

        • :domain [String]

        • :dataSource [String]

      • :dataSource [String]

    • :totalElements [Fixnum]

    • :totalPages [Fixnum]

    • :actualPage [Fixnum]

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=#{}"
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]

Parameters:

  • domain_obj —

    The domain to be created. For example:

Returns:

  • (Boolean) —

    true if was successfully created



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

Parameters:

  • user (String)
  • domains (String) 


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]

Parameters:

  • domain_obj (defaults to: {}) —

    The domain to be created. For example:

Returns:

  • (Boolean) —

    true if was successfully created



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

Parameters:

  • domain (String)
  • msg (Hash)

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)

Returns:



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

Parameters:

  • user_info (Hash)
  • domains (Array<String>)

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

Returns true when operation it’s ok.

Returns:

  • (Boolean) —

    true when operation it’s ok



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

Returns:

  • MxHero::API::Directories



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

Parameters:

  • name —

    The domain name or id. For example: ‘mydomain.com’

Returns:

  • (Domain) —

    or nil if not found

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

Parameters:

  • domain (String)
  • id (Integer) —

    the rule id

Returns:

  • (Hash, nil) —

    the Rule information or nil if not exist

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?

Returns:

  • (Hash) —

    with the list of domains

    • :elements [Array<Hash>] the list of domains as a Hash, when any element contains:

      • :domain [String]

      • :server [String]

      • :creationDate [Fixnum]

      • :updateDate [Fixnum]

      • :aliases

      • :ldap

    • :totalElements

    • :totalPages

    • :actualPage

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

Returns:



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

Returns:

  • (Hash) —

    with

    • :domain

    • :directoryType

    • :addres

    • :port

    • :sslFlag [Boolean]

    • :user

    • :password

    • :filter

    • :base

    • :nextUpdate

    • :lastUpdate

    • :error

    • :overrideFlag

    • :dnAuthenticate

    • :properties [Array]



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

Returns:

  • true | false



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

Parameters:

  • domain (String)
  • component (String) (defaults to: nil) —

    Filter the list of rules by this component [optional]

Returns:



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

Returns can return a hash with the key and value of any system property. If use a parameter (key) return the string of this value. In the two cases return nil when not found values.

Returns:

  • (Hash|String|nil) —

    can return a hash with the key and value of any system property. If use a parameter (key) return the string of this value. In the two cases return nil when not found values



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

Parameters:

  • user (String)
  • domain (String) 


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

Returns . On success not return msg.

Parameters:

  • domain (String)
  • account (String)
  • properties (Hash) —

    The properties of the account. Ex.: { ‘email’: ‘[email protected]’, ‘name’: ‘John’, ‘lastname’: ‘Doe’, … }

Returns:



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

Parameters:

  • domain (String)
  • accounts. (Array<Hash>) —

    An array of hash with :account and :properties. The :properties contains a Hash with the equivalent of name and value.

  • scope (String) (defaults to: :properties) —

    :groups, :properties or :both (default: properties)



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

Returns:

  • (MxHero::API::Response) —

    When the rule is update correctly then return MxHero::API::Response object without msg (msg nil) In case of error, the message is completed with the cause of error



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

Parameters:

  • user (Hash) —

    retrieve to update

  • user_name (String) 


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

Returns:

  • (Array<String>|nil) —

    when the user exist but don’t have domains the list is empty. If the user isn’t exist then return nil



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

Returns:

  • (Array<UserVO>|nil) —

    when there is no users for that domain. If the domain doesn’t exist then return nil



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

Returns:

  • (Boolean) 


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

Returns:

  • (Boolean) 


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

def verbose?
	@verbose
end