Class: KineticSdk::Integrator

Inherits:
Object
  • Object
show all
Includes:
Utils::KineticHttpUtils
Defined in:
lib/kinetic_sdk/integrator/integrator-sdk.rb,
lib/kinetic_sdk/integrator/lib/metadata.rb,
lib/kinetic_sdk/integrator/lib/operations.rb,
lib/kinetic_sdk/integrator/lib/connections.rb

Overview

Integrator is a Ruby class that acts as a wrapper for the Kinetic Integrator REST API without having to make explicit HTTP requests.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Utils::KineticHttpUtils

#default_headers, default_headers, #default_jwt_headers, default_jwt_headers, #delete, #encode, #gateway_retry_delay, #gateway_retry_limit, #get, #head, #header_accept_json, header_accept_json, #header_basic_auth, header_basic_auth, header_bearer_auth, #header_bearer_auth, #header_content_json, header_content_json, header_user_agent, #header_user_agent, #max_redirects, #mimetype, #patch, #post, #post_multipart, #put, #redirect_url, #stream_download_to_file

Constructor Details

#initialize(opts) ⇒ Integrator

Initalize the Integrator SDK with the web server URL and configuration user credentials, along with any custom option values.

Example: using a configuration file

KineticSdk::Integrator.new({
  config_file: "/opt/config1.yaml"
})

Example: space user properties hash

KineticSdk::Integrator.new({
  space_server_url: "https://my-space.domain",
  space_slug: "my-space",
  username: "admin",
  password: "password",
  options: {
      log_level: "debug",
      oauth_client_id: "my-oauth-user-id",
      oauth_client_secret: "my-oauth-user-secret",
      ssl_verify_mode: "peer",
      ssl_ca_file: "/usr/local/self_signing_ca.pem"
  }
})

If the +config_file+ option is present, it will be loaded first, and any additional options will overwrite any values in the config file

Parameters:

  • opts (Hash) —

    Kinetic Integrator properties

Options Hash (opts):

  • :config_file (String) —

    optional - path to the YAML configuration file

    • Ex: /opt/config/integrator-configuration1.yaml
  • :app_server_url (String) —

    the URL to the integrator server

  • :space_server_url (String) —

    the URL to the Kinetic Request CE web space

  • :space_slug (String) —

    the slug that identifies the Space

  • :username (String) —

    the username for the user

  • :password (String) —

    the password for the user

  • :options (Hash<Symbol, Object>) — default: {} —

    optional settings

    • :export_directory (String) (_example: /opt/exports/integrator) directory to write files when exporting,
    • :gateway_retry_limit (FixNum) (defaults to: 5) max number of times to retry a bad gateway
    • :gateway_retry_delay (Float) (defaults to: 1.0) number of seconds to delay before retrying a bad gateway
    • :log_level (String) (defaults to: off) level of logging - off | error | warn | info | debug
    • :log_output (String) (defaults to: STDOUT) where to send output - STDOUT | STDERR
    • :max_redirects (Fixnum) (defaults to: 5) maximum number of redirects to follow
    • :oauth_client_id (String) id of the Kinetic Core oauth client
    • :oauth_client_secret (String) secret of the Kinetic Core oauth client
    • :ssl_ca_file (String) full path to PEM certificate used to verify the server
    • :ssl_verify_mode (String) (defaults to: none) - none | peer


71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/kinetic_sdk/integrator/integrator-sdk.rb', line 71

def initialize(opts)
  # initialize any variables
  options = {}

  # process the configuration file if it was provided
  unless opts[:config_file].nil?
    options.merge!(YAML::load_file opts[:config_file])
  end

  # process the configuration hash if it was provided
  options.merge!(opts)

  # allow one of :app_server_url, :space_server_url, or :integrator_server_url
  # but not more than one
  if options[:app_server_url] && options[:space_server_url]
    raise StandardError.new "Expecting either :app_server_url or :space_server_url, but not both."
  end

  if options[:app_server_url].nil? && options[:space_server_url].nil?
    raise StandardError.new "Expecting either :app_server_url or :space_server_url."
  end

  # process any individual options
  @options = options[:options] || {}
  # setup logging
  log_level = @options[:log_level] || @options["log_level"]
  log_output = @options[:log_output] || @options["log_output"]
  @logger = KineticSdk::Utils::KLogger.new(log_level, log_output)

  @username = options[:username]
  @space_slug = options[:space_slug]

  if options[:app_server_url]
    @server = options[:app_server_url].chomp("/")
    @api_url = "#{@server}/api"
  else
    raise StandardError.new "The :space_slug option is required when using the :space_server_url option" if @space_slug.nil?
    @server = options[:space_server_url].chomp("/")
    @api_url = "#{@server}/app/integrator/api"
  end
  @jwt = @space_slug.nil? ? nil : generate_jwt(options)
  @version = 1
end

Instance Attribute Details

#api_url ⇒ Object (readonly)

Returns the value of attribute api_url.



13
14
15
 
# File 'lib/kinetic_sdk/integrator/integrator-sdk.rb', line 13

def api_url
  @api_url
end

#jwt ⇒ Object (readonly)

Returns the value of attribute jwt.



13
14
15
 
# File 'lib/kinetic_sdk/integrator/integrator-sdk.rb', line 13

def jwt
  @jwt
end

#logger ⇒ Object (readonly)

Returns the value of attribute logger.



13
14
15
 
# File 'lib/kinetic_sdk/integrator/integrator-sdk.rb', line 13

def logger
  @logger
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



13
14
15
 
# File 'lib/kinetic_sdk/integrator/integrator-sdk.rb', line 13

def options
  @options
end

#server ⇒ Object (readonly)

Returns the value of attribute server.



13
14
15
 
# File 'lib/kinetic_sdk/integrator/integrator-sdk.rb', line 13

def server
  @server
end

#space_slug ⇒ Object (readonly)

Returns the value of attribute space_slug.



13
14
15
 
# File 'lib/kinetic_sdk/integrator/integrator-sdk.rb', line 13

def space_slug
  @space_slug
end

#username ⇒ Object (readonly)

Returns the value of attribute username.



13
14
15
 
# File 'lib/kinetic_sdk/integrator/integrator-sdk.rb', line 13

def username
  @username
end

#version ⇒ Object (readonly)

Returns the value of attribute version.



13
14
15
 
# File 'lib/kinetic_sdk/integrator/integrator-sdk.rb', line 13

def version
  @version
end

Instance Method Details

#add_connection(properties = {}, headers = default_jwt_headers) ⇒ KineticSdk::Utils::KineticHttpResponse

Add a Connection

Parameters:

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

    connection properties

    • +type+ [String]
    • +name+ [String]
    • +config+ [Hash]
      • +baseUrl+ [String] url to the server hosting the connection API
  • headers (Hash) (defaults to: default_jwt_headers) —

    hash of headers to send, default is bearer authentication and accept JSON content type

Returns:



13
14
15
16
 
# File 'lib/kinetic_sdk/integrator/lib/connections.rb', line 13

def add_connection(properties={}, headers=default_jwt_headers)
  @logger.info("Adding the #{properties['type']} connection named #{properties['name']}")
  post("#{@api_url}/connections", properties, headers)
end

#add_operation(connection_id, properties = {}, headers = default_jwt_headers) ⇒ KineticSdk::Utils::KineticHttpResponse

Add an Operation

Parameters:

  • connection_id (String) —

    id of the Connection

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

    operation properties

    • +name+ [String]
    • +type+ [String]
    • +name+ [String]
    • +config+ [Hash]
      • +baseUrl+ [String] url to the server hosting the connection API
  • headers (Hash) (defaults to: default_jwt_headers) —

    hash of headers to send, default is bearer authentication and accept JSON content type

Returns:



15
16
17
18
19
 
# File 'lib/kinetic_sdk/integrator/lib/operations.rb', line 15

def add_operation(connection_id, properties={}, headers=default_jwt_headers)
  @logger.info("Adding the #{properties['name']} operation")
  @logger.info("Operation properties: #{properties.inspect}")
  post("#{@api_url}/connections/#{connection_id}/operations", properties, headers)
end

#app_version(headers = header_accept_json) ⇒ KineticSdk::Utils::KineticHttpResponse

Retrieve Integrator application version

Parameters:

  • headers (Hash) (defaults to: header_accept_json) —

    hash of headers to send, default is accept JSON content type

Returns:



8
9
10
11
 
# File 'lib/kinetic_sdk/integrator/lib/metadata.rb', line 8

def app_version(headers=header_accept_json)
  @logger.info("Retrieving Integrator version.")
  get("#{@api_url}/version", {}, headers)
end

#delete_connection(connection_id, headers = default_jwt_headers) ⇒ KineticSdk::Utils::KineticHttpResponse

Delete a connection

Parameters:

  • connection_id (String) —

    id of the connection

  • headers (Hash) (defaults to: default_jwt_headers) —

    hash of headers to send, default is bearer authentication

Returns:



23
24
25
26
 
# File 'lib/kinetic_sdk/integrator/lib/connections.rb', line 23

def delete_connection(connection_id, headers=default_jwt_headers)
  @logger.info("Deleting Connection \"#{connection_id}\"")
  delete("#{@api_url}/connections/#{connection_id}", headers)
end

#delete_operation(connection_id, operation_id, headers = default_jwt_headers) ⇒ KineticSdk::Utils::KineticHttpResponse

Delete an operation

Parameters:

  • connection_id (String) —

    id of the connection the operation belongs to

  • operation_id (String) —

    id of the operation

  • headers (Hash) (defaults to: default_jwt_headers) —

    hash of headers to send, default is bearer authentication

Returns:



27
28
29
30
 
# File 'lib/kinetic_sdk/integrator/lib/operations.rb', line 27

def delete_operation(connection_id, operation_id, headers=default_jwt_headers)
  @logger.info("Deleting Operation \"#{operation_id}\"")
  delete("#{@api_url}/connections/#{connection_id}/operations/#{operation_id}", headers)
end

#execute_operation(connection_id, operation_id, parameters = {}, debug = false, headers = default_jwt_headers) ⇒ KineticSdk::Utils::KineticHttpResponse

Execute an Operation

Parameters:

  • connection_id (String) —

    id of the Connection

  • operation_id (String) —

    id of the Operation

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

    operation execution parameters

  • debug (boolean) (defaults to: false) —

    execute in debug mode

  • headers (Hash) (defaults to: default_jwt_headers) —

    hash of headers to send, default is bearer authentication and accept JSON content type

Returns:



76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/kinetic_sdk/integrator/lib/operations.rb', line 76

def execute_operation(connection_id, operation_id, parameters={}, debug=false, headers=default_jwt_headers)
  @logger.info("Executing operation #{operation_id}")
  payload = {
    "connectionId" => connection_id,
    "operationId" => operation_id,
    "parameters" => parameters
  }
  url = "#{@api_url}/execute"
  url = "#{url}?debug=true" if debug
  post(url, payload, headers)
end

#find_connection(connection_id, params = {}, headers = default_jwt_headers) ⇒ KineticSdk::Utils::KineticHttpResponse

Find a Connection

Parameters:

  • connection_id (String) —

    id of the Connection

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

    Query parameters that are added to the URL

  • headers (Hash) (defaults to: default_jwt_headers) —

    hash of headers to send, default is bearer authentication and accept JSON content type

Returns:



44
45
46
47
 
# File 'lib/kinetic_sdk/integrator/lib/connections.rb', line 44

def find_connection(connection_id, params={}, headers=default_jwt_headers)
  @logger.info("Finding Connection \"#{connection_id}\"")
  get("#{@api_url}/connections/#{connection_id}", params, headers)
end

#find_connections(params = {}, headers = default_jwt_headers) ⇒ KineticSdk::Utils::KineticHttpResponse

Find Connections

Parameters:

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

    Query parameters that are added to the URL

  • headers (Hash) (defaults to: default_jwt_headers) —

    hash of headers to send, default is bearer authentication and accept JSON content type

Returns:



33
34
35
36
 
# File 'lib/kinetic_sdk/integrator/lib/connections.rb', line 33

def find_connections(params={}, headers=default_jwt_headers)
  @logger.info("Finding Connections")
  get("#{@api_url}/connections", params, headers)
end

#find_operation(connection_id, operation_id, params = {}, headers = default_jwt_headers) ⇒ KineticSdk::Utils::KineticHttpResponse

Find an Operation

Parameters:

  • connection_id (String) —

    id of the Connection

  • operation_id (String) —

    id of the Operation

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

    Query parameters that are added to the URL

  • headers (Hash) (defaults to: default_jwt_headers) —

    hash of headers to send, default is bearer authentication and accept JSON content type

Returns:



50
51
52
53
 
# File 'lib/kinetic_sdk/integrator/lib/operations.rb', line 50

def find_operation(connection_id, operation_id, params={}, headers=default_jwt_headers)
  @logger.info("Finding Operation \"#{operation_id}\"")
  get("#{@api_url}/connections/#{connection_id}/operations/#{operation_id}", params, headers)
end

#find_operations(connection_id, params = {}, headers = default_jwt_headers) ⇒ KineticSdk::Utils::KineticHttpResponse

Find Operations for a Connection

Parameters:

  • connection_id (String) —

    id of the connection the operation belongs to

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

    Query parameters that are added to the URL

  • headers (Hash) (defaults to: default_jwt_headers) —

    hash of headers to send, default is bearer authentication and accept JSON content type

Returns:



38
39
40
41
 
# File 'lib/kinetic_sdk/integrator/lib/operations.rb', line 38

def find_operations(connection_id, params={}, headers=default_jwt_headers)
  @logger.info("Finding Operations")
  get("#{@api_url}/connections/#{connection_id}/operations", params, headers)
end

#generate_jwt(options = {}) ⇒ Object

Generate a JWT for bearer authentication based on the user credentials, and oauth client configuration.



117
118
119
120
121
122
 
# File 'lib/kinetic_sdk/integrator/integrator-sdk.rb', line 117

def generate_jwt(options = {})
  oauth_client_id = options[:options][:oauth_client_id]
  oauth_client_secret = options[:options][:oauth_client_secret]
  jwt_response = kinetic_core_sdk(options).jwt_token(oauth_client_id, oauth_client_secret)
  jwt_response.content["access_token"]
end

#health(headers = header_accept_json) ⇒ KineticSdk::Utils::KineticHttpResponse

Check Integrator health

Parameters:

  • headers (Hash) (defaults to: header_accept_json) —

    hash of headers to send, default is accept JSON content type

Returns:



17
18
19
20
 
# File 'lib/kinetic_sdk/integrator/lib/metadata.rb', line 17

def health(headers=header_accept_json)
  @logger.info("Retrieving Integrator health.")
  get("#{@api_url}/healthz", {}, headers)
end

#inspect_operation(operation_id, headers = default_jwt_headers) ⇒ KineticSdk::Utils::KineticHttpResponse

Inspect an Operation

Parameters:

  • operation_id (String) —

    id of the Operation

  • headers (Hash) (defaults to: default_jwt_headers) —

    hash of headers to send, default is bearer authentication and accept JSON content type

Returns:



93
94
95
96
97
98
99
100
 
# File 'lib/kinetic_sdk/integrator/lib/operations.rb', line 93

def inspect_operation(operation_id, headers=default_jwt_headers)
  @logger.info("Inspecting operation #{operation_id}")
  payload = {
    "operationId" => operation_id
  }
  url = "#{@api_url}/inspect"
  post(url, payload, headers)
end

#kinetic_core_sdk(options) ⇒ Object

Creates a reference to the Kinetic Request CE SDK



125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/kinetic_sdk/integrator/integrator-sdk.rb', line 125

def kinetic_core_sdk(options)
  kinetic_core_options = {
    space_slug: options[:space_slug],
    username: options[:username],
    password: options[:password],
    options: options[:options] || {},
  }
  if options[:app_server_url]
    kinetic_core_options[:app_server_url] = options[:app_server_url]
  else
    kinetic_core_options[:space_server_url] = options[:space_server_url]
  end
  KineticSdk::Core.new(kinetic_core_options)
end

#oas(headers = header_accept_json) ⇒ KineticSdk::Utils::KineticHttpResponse

OpenApi Specification

Parameters:

  • headers (Hash) (defaults to: header_accept_json) —

    hash of headers to send, default is accept JSON content type

Returns:



26
27
28
29
 
# File 'lib/kinetic_sdk/integrator/lib/metadata.rb', line 26

def oas(headers=header_accept_json)
  @logger.info("Retrieving OpenAPI Specification.")
  get("#{@api_url}/oas", {}, headers)
end

#test_saved_connection(connection_id, properties = {}, headers = default_jwt_headers) ⇒ KineticSdk::Utils::KineticHttpResponse

Test a saved Connection

Parameters:

  • connection_id (String) —

    id of the Connection

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

    connection properties to test

  • headers (Hash) (defaults to: default_jwt_headers) —

    hash of headers to send, default is bearer authentication and accept JSON content type

Returns:



77
78
79
80
 
# File 'lib/kinetic_sdk/integrator/lib/connections.rb', line 77

def test_saved_connection(connection_id, properties={}, headers=default_jwt_headers)
   @logger.info("Testing saved connection: #{connection_id}")
   post("#{@api_url}/connections/#{connection_id}/test", properties, headers)
end

#test_unsaved_connection(properties = {}, headers = default_jwt_headers) ⇒ KineticSdk::Utils::KineticHttpResponse

Test an unsaved Connection

Parameters:

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

    connection properties to test

  • headers (Hash) (defaults to: default_jwt_headers) —

    hash of headers to send, default is bearer authentication and accept JSON content type

Returns:



66
67
68
69
 
# File 'lib/kinetic_sdk/integrator/lib/connections.rb', line 66

def test_unsaved_connection(properties={}, headers=default_jwt_headers)
   @logger.info("Testing unsaved connection")
   post("#{@api_url}/test", properties, headers)
end

#update_connection(connection_id, properties = {}, headers = default_jwt_headers) ⇒ KineticSdk::Utils::KineticHttpResponse

Update a Connection

Parameters:

  • connection_id (String) —

    id of the Connection

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

    form properties to update

    • +name+ [String]
  • headers (Hash) (defaults to: default_jwt_headers) —

    hash of headers to send, default is bearer authentication and accept JSON content type

Returns:



56
57
58
59
 
# File 'lib/kinetic_sdk/integrator/lib/connections.rb', line 56

def update_connection(connection_id, properties={}, headers=default_jwt_headers)
  @logger.info("Updating Connection \"#{connection_id}\"")
  put("#{@api_url}/connections/#{connection_id}", properties, headers)
end

#update_operation(connection_id, operation_id, properties = {}, headers = default_jwt_headers) ⇒ KineticSdk::Utils::KineticHttpResponse

Update an Operation

Parameters:

  • connection_id (String) —

    id of the Connection

  • operation_id (String) —

    id of the Operation

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

    form properties to update

    • +name+ [String]
  • headers (Hash) (defaults to: default_jwt_headers) —

    hash of headers to send, default is bearer authentication and accept JSON content type

Returns:



63
64
65
66
 
# File 'lib/kinetic_sdk/integrator/lib/operations.rb', line 63

def update_operation(connection_id, operation_id, properties={}, headers=default_jwt_headers)
  @logger.info("Updating Operation \"#{operation_id}\"")
  put("#{@api_url}/connections/#{connection_id}/operations/#{operation_id}", properties, headers)
end