Module: Ontraport

Defined in:
lib/ontraport.rb,
lib/ontraport/version.rb,
lib/ontraport/response.rb,
lib/ontraport/exceptions.rb,
lib/ontraport/configuration.rb

Overview

See Also:

Author:

  • Hamza Tayeb

Defined Under Namespace

Classes: APIError, Configuration, ObjectNotFoundError, Response

Constant Summary collapse

BASE_URL = 
'https://api.ontraport.com/'
API_VERSION = 
'1'
VERSION = 
'0.1'

Accessor methods collapse

Modifier methods collapse

Configuration methods collapse

Class Method Summary collapse

Class Method Details

.clear_describe_cache! ⇒ nil

Clear the cache of object metadata generated by the describe call. Use this if you make changes to custom fields or objects in your ONTRAPORT instance and don’t want to reload the Ontraport module.

Examples:

Ontraport.clear_describe_cache!

Returns:

  • (nil) 


43
44
45
 
# File 'lib/ontraport.rb', line 43

def self.clear_describe_cache!
  @objects_meta_cache = nil
end

.configuration ⇒ Configuration

Getter method for the module config.

Returns:



6
7
8
 
# File 'lib/ontraport/configuration.rb', line 6

def self.configuration
  @configuration ||= Configuration.new
end

.configure {|configuration| ... } ⇒ nil

Used to enable a configuration block in the application the Gem being used by.

Examples:

Ontraport.configure do |config|
  config.api_id = 'foo'
  config.api_key = 'bar'
end

Yields:

Returns:

  • (nil) 


19
20
21
 
# File 'lib/ontraport/configuration.rb', line 19

def self.configure
  yield configuration
end

.describe(object) ⇒ Hash{String=>String,Hash}

Describe a given object type, including the numeric object Id and the available fields.

Examples:

Ontraport.describe :contact

Parameters:

  • object (Symbol) —

    the type of object you want to describe

Returns:

  • (Hash{String=>String,Hash}) —

    object metadata. Keys are:

    • ‘name’ - name of the object

    • ‘fields’ - Hash containing the object’s fields

    • ‘schema_object_id’ - numeric Id of the object, as a String

Raises:

  • (ArgumentError) —

    if the argument is not a Symbol

  • (ObjectNotFoundError) —

    if the argument does not match any object defined in the schema



23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/ontraport.rb', line 23

def self.describe object
  unless object.class.eql? Symbol
    raise ArgumentError.new "Must provide a symbol for the object name."
  end

  unless metadata = objects_meta.data.find{ |k, v| v['name'].downcase.to_sym.eql? object }
    raise ObjectNotFoundError.new "No object matching #{object.inspect} could be found."
  end

  metadata.second.update 'schema_object_id' => metadata.first
end

.get_object(object_type, id) ⇒ Response

Retrieve a single object of the specified type.

Examples:

Ontraport.get_object :contact, 12345
#=> #<Ontraport::Response @data=...>

Parameters:

  • object_type (Symbol) —

    the type of object, for instance :contact

  • id (Integer) —

    Id of the record you want

Returns:



58
59
60
 
# File 'lib/ontraport.rb', line 58

def self.get_object object_type, id
  objects_call :get, object_type, endpoint: '/object', data: { id: id }
end

.get_objects(object_type, params = {}) ⇒ Response

Retrieve a collection of objects of the specified type, matching the query specified by the parameters.

Examples:

Ontraport.get_objects :contact, { condition: "email like '%@foo.com'", sort: 'lastname' }

Parameters:

  • object_type (Symbol) —

    the type of object

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

    hash containing request parameters

Returns:

See Also:



73
74
75
 
# File 'lib/ontraport.rb', line 73

def self.get_objects object_type, params={}
  objects_call :get, object_type, endpoint: '/objects', data: params
end

.save_or_update(object_type, params) ⇒ Response

Create an object with the given data, or merge if the unique field matches another row.

Examples:

Ontraport.save_or_update :contact, { email: '[email protected]', firstname: 'Foo' }
#=> #<Ontraport::Response @data=...>

Parameters:

  • object_type (Symbol) —

    the type of object

  • params (Hash) —

    input data

Returns:

See Also:



91
92
93
 
# File 'lib/ontraport.rb', line 91

def self.save_or_update object_type, params
  objects_call :post, object_type, endpoint: '/objects/saveorupdate', data: params
end

.tag_objects(object_type, params) ⇒ Response

Note:

The add_list and ids parameters should be strings comprised of comma-delimeted Integers.

Add tags to objects matching the supplied conditions. In addition to various conditionals, you may supply a list of Ids for objects you wish to tag (ids). The add_list parameter (which contains the Ids of the tags you want to add) is required.

Examples:

Ontraport.tag_objects :contact, { add_list: '11111,22222', ids: '33333,44444' }
#=> #<Ontraport::Response @data=...>

Parameters:

  • object_type (Symbol) —

    the type of object

  • params (Hash) —

    parameters describing the conditions of the tag operation.

Returns:

See Also:



123
124
125
126
 
# File 'lib/ontraport.rb', line 123

def self.tag_objects object_type, params

  objects_call :put, object_type, endpoint: '/objects/tag', data: params
end

.untag_objects(object_type, object:, tag:) ⇒ Response

Remove tags from objects matching the supplied conditions. Interface is identical to #tag_objects

Parameters:

  • object_type (Symbol) —

    the type of object

  • params (Hash) —

    parameters describing the conditions of the tag operation.

Returns:

See Also:



136
137
138
 
# File 'lib/ontraport.rb', line 136

def self.untag_objects object_type, object:, tag:
  objects_call :delete, object_type, endpoint: '/objects/tag', data: params
end

.update_object(object_type, id, params) ⇒ Response

Given an object type, Id, and a Hash of changes, update an single row.

Examples:

Ontraport.update_object :contact, 12345, { firstname: 'ChangeMe' }
#=> #<Ontraport::Response @data=...>

Parameters:

  • object_type (Symbol) —

    the type of object

  • params (Hash) —

    update data. Use .describe to get a list of available fields.

Returns:



104
105
106
 
# File 'lib/ontraport.rb', line 104

def self.update_object object_type, id, params
  objects_call :put, object_type, endpoint: '/objects', data: params.update(id: id)
end