vcoworkflows 0.1.1

data/lib/vcoworkflows/vcosession.rb

@@ -0,0 +1,48 @@
+require_relative 'constants'
+require 'rest_client'
+
+# VcoWorkflows
+module VcoWorkflows
+  # VcoSession
+  class VcoSession
+    # Accessor for rest-client object, primarily for testing purposes
+    attr_reader :rest_resource
+
+    # Initialize the session
+    #
+    # @param [String] uri URI for the vCenter Orchestrator API endpoint
+    # @param [String] user User name for vCO
+    # @param [String] password Password for vCO
+    # @param [Boolean] verify_ssl Whether or not to verify SSL certificates
+    def initialize(uri, user: nil, password: nil, verify_ssl: true)
+      api_url = "#{uri.gsub(/\/$/, '')}/vco/api"
+      RestClient.proxy = ENV['http_proxy'] # Set a proxy if present
+      @rest_resource = RestClient::Resource.new(api_url,
+                                                user: user,
+                                                password: password,
+                                                verify_ssl: verify_ssl)
+    end
+
+    # Perform a REST GET operation against the specified endpoint
+    #
+    # @param [String] endpoint REST endpoint to use
+    # @param [Hash] headers Optional headers to use in request
+    # @return [String] JSON response body
+    def get(endpoint, headers = {})
+      headers = { accept: :json }.merge(headers)
+      @rest_resource[endpoint].get headers
+    end
+
+    # Perform a REST POST operation against the specified endpoint with the
+    # given data body
+    #
+    # @param [String] endpoint REST endpoint to use
+    # @param [String] body JSON data body to post
+    # @param [Hash] headers Optional headers to use in request
+    # @return [String] JSON response body
+    def post(endpoint, body, headers = {})
+      headers = { accept: :json, content_type: :json }.merge(headers)
+      @rest_resource[endpoint].post body, headers
+    end
+  end
+end

data/lib/vcoworkflows/version.rb

@@ -0,0 +1,4 @@
+# VcoWorkflows
+module VcoWorkflows
+  VERSION = '0.1.1'
+end

data/lib/vcoworkflows/workflow.rb

@@ -0,0 +1,304 @@
+require_relative 'constants'
+require_relative 'workflowservice'
+require_relative 'workflowpresentation'
+require_relative 'workflowtoken'
+require_relative 'workflowparameter'
+require 'json'
+
+# VcoWorkflows
+module VcoWorkflows
+  # rubocop:disable ClassLength
+
+  # Class to represent a Workflow as presented by vCenter Orchestrator.
+  class Workflow
+    attr_reader :id
+    attr_reader :name
+    attr_reader :version
+    attr_reader :description
+    attr_reader :input_parameters
+    attr_reader :output_parameters
+    attr_accessor :service
+    attr_reader :execution_id
+
+    attr_reader :source_json
+
+    # rubocop:disable CyclomaticComplexity, PerceivedComplexity, MethodLength, LineLength
+
+    # Create a Workflow object given vCenter Orchestrator's JSON description
+    #
+    # When passed `url`, `username` and `password` the necessary session and
+    # service objects will be created behind the scenes. Alternatively you can
+    # pass in a VcoSession object or a WorkflowService object if you have
+    # constructed them yourself.
+    # @param [String] name Name of the requested workflow
+    # @param [Hash] options Hash of options, see README.md for details
+    # @return [VcoWorkflows::Workflow]
+    def initialize(name = nil, options = {})
+      @options = {
+        id: nil,
+        url: nil,
+        username: nil,
+        password: nil,
+        verify_ssl: true,
+        service: nil
+      }.merge(options)
+
+      @service = nil
+      @execution_id = nil
+
+      # -------------------------------------------------------------
+      # Figure out how to get a workflow service. If I can't, I die.
+      # (DUN dun dun...)
+
+      if options[:service]
+        @service = options[:service]
+      elsif @options[:url] && @options[:username] && @options[:password]
+        session = VcoWorkflows::VcoSession.new(@options[:url],
+                                               user: @options[:username],
+                                               password: @options[:password],
+                                               verify_ssl: @options[:verify_ssl])
+        @service = VcoWorkflows::WorkflowService.new(session)
+      end
+
+      fail(IOError, 'Unable to create/use a WorkflowService!') if @service.nil?
+
+      # -------------------------------------------------------------
+      # Retrieve the workflow and parse it into a data structure
+      # If we're given both a name and ID, prefer the id
+      if @options[:id]
+        workflow_json = @service.get_workflow_for_id(@options[:id])
+      else
+        workflow_json = @service.get_workflow_for_name(name)
+      end
+      workflow_data = JSON.parse(workflow_json)
+
+      # Set up the attributes if they exist in the data json, otherwise nil them
+      @id          = workflow_data.key?('id')          ? workflow_data['id']          : nil
+      @name        = workflow_data.key?('name')        ? workflow_data['name']        : nil
+      @version     = workflow_data.key?('version')     ? workflow_data['version']     : nil
+      @description = workflow_data.key?('description') ? workflow_data['description'] : nil
+
+      # Process the input parameters
+      if workflow_data.key?('input-parameters')
+        @input_parameters = Workflow.parse_parameters(workflow_data['input-parameters'])
+      else
+        @input_parameters = {}
+      end
+
+      # Identify required input_parameters
+      wfpres = VcoWorkflows::WorkflowPresentation.new(@service, @id)
+      wfpres.required.each do |req_param|
+        @input_parameters[req_param].required(true)
+      end
+
+      # Process the output parameters
+      if workflow_data.key?('output-parameters')
+        @output_parameters = Workflow.parse_parameters(workflow_data['output-parameters'])
+      else
+        @output_parameters = {}
+      end
+    end
+    # rubocop:enable CyclomaticComplexity, PerceivedComplexity, MethodLength, LineLength
+
+    def url
+      options[:url]
+    end
+
+    def username
+      options[:username]
+    end
+
+    def password
+      options[:password]
+    end
+
+    def verify_ssl?
+      options[:verify_ssl]
+    end
+
+    # rubocop:disable MethodLength, LineLength
+
+    # Parse json parameters and return a nice hash
+    # @param [Array] parameter_data JSON document of parameters as defined
+    # by vCO
+    # @return [Hash]
+    def self.parse_parameters(parameter_data = [])
+      wfparams = {}
+      parameter_data.each do |parameter|
+        wfparam = VcoWorkflows::WorkflowParameter.new(parameter['name'], parameter['type'])
+        if parameter['value']
+          if wfparam.type.eql?('Array')
+            value = []
+            begin
+              parameter['value'][wfparam.type.downcase]['elements'].each do |element|
+                value << element[element.keys.first]['value']
+              end
+            rescue StandardError => error
+              parse_failure(error)
+            end
+          else
+            begin
+              value = parameter['value'][parameter['value'].keys.first]['value']
+            rescue StandardError => error
+              parse_failure(error)
+            end
+          end
+          value = nil if value.eql?('null')
+          wfparam.set(value)
+        end
+        wfparams[parameter['name']] = wfparam
+      end
+      wfparams
+    end
+    # rubocop:enable MethodLength, LineLength
+
+    # rubocop:disable LineLength
+
+    # Process exceptions raised in parse_parameters by bravely ignoring them
+    # and forging ahead blindly!
+    # @param [Exception] error
+    def self.parse_failure(error)
+      $stderr.puts "\nWhoops!"
+      $stderr.puts "Ran into a problem parsing parameter #{wfparam.name} (#{wfparam.type})!"
+      $stderr.puts "Source data: #{JSON.pretty_generate(parameter)}\n"
+      $stderr.puts error.message
+      $stderr.puts "\nBravely forging on and ignoring parameter #{wfparam.name}!"
+    end
+    # rubocop:enable LineLength
+
+    # rubocop:disable LineLength
+
+    # Get an array of the names of all the required input parameters
+    # @return [Hash] Hash of WorkflowParameter input parameters which are required for this workflow
+    def required_parameters
+      required = {}
+      @input_parameters.each_value { |v| required[v.name] = v if v.required? }
+      required
+    end
+    # rubocop:enable LineLength
+
+    # Get the value of a specific input parameter
+    # @param [String] parameter_name Name of the parameter whose value to get
+    # @return [VcoWorkflows::WorkflowParameter]
+    def parameter(parameter_name)
+      @input_parameters[parameter_name]
+    end
+
+    # rubocop:disable LineLength
+
+    # Set a parameter to a value
+    # @param [String] parameter_name name of the parameter to set
+    # @param [Object] value value to set
+    def set_parameter(parameter_name, value)
+      if @input_parameters.key?(parameter_name)
+        @input_parameters[parameter_name].set value
+      else
+        $stderr.puts "\nAttempted to set a value for a non-existent WorkflowParameter!"
+        $stderr.puts "It appears that there is no parameter \"#{parameter}\"."
+        $stderr.puts "Valid parameter names are: #{@input_parameters.keys.join(', ')}"
+        $stderr.puts ''
+        fail(IOError, ERR[:no_such_parameter])
+      end
+    end
+    # rubocop:enable LineLength
+
+    # rubocop:disable LineLength
+
+    # Get the value for an input parameter
+    # @param [String] parameter_name Name of the input parameter whose value to get
+    # @return [Object]
+    def get_parameter(parameter_name)
+      @input_parameters[parameter_name].value
+    end
+    # rubocop:enable LineLength
+
+    # rubocop:disable LineLength
+
+    # Verify that all mandatory input parameters have values
+    private def verify_parameters
+      required_parameters.each do |name, wfparam|
+        if wfparam.required? && (wfparam.value.nil? || wfparam.value.size == 0)
+          fail(IOError, ERR[:param_verify_failed] << "#{name} required but not present.")
+        end
+      end
+    end
+    # rubocop:enable LineLength
+
+    # rubocop:disable LineLength
+
+    # Execute this workflow
+    # @param [VcoWorkflows::WorkflowService] workflow_service
+    # @return [String] Workflow Execution ID
+    def execute(workflow_service = nil)
+      # If we're not given an explicit workflow service for this execution
+      # request, use the one defined when we were created.
+      workflow_service = @service if workflow_service.nil?
+      # If we still have a nil workflow_service, go home.
+      fail(IOError, ERR[:no_workflow_service_defined]) if workflow_service.nil?
+      # Make sure we didn't forget any required parameters
+      verify_parameters
+      # Let's get this thing running!
+      @execution_id = workflow_service.execute_workflow(@id, input_parameter_json)
+    end
+    # rubocop:enable LineLength
+
+    # Get a list of all the executions of this workflow. Wrapper for
+    # VcoWorkflows::WorkflowService#get_execution_list
+    # @return [Hash]
+    def executions
+      @service.get_execution_list(@id)
+    end
+
+    # Return a WorkflowToken
+    # @param [String] execution_id optional execution id to get logs for
+    # @return [VcoWorkflows::WorkflowToken]
+    def token(execution_id = nil)
+      execution_id = @execution_id if execution_id.nil?
+      VcoWorkflows::WorkflowToken.new(@service, @id, execution_id)
+    end
+
+    # Return logs for the given execution
+    # @param [String] execution_id optional execution id to get logs for
+    # @return [VcoWorkflows::WorkflowExecutionLog]
+    def log(execution_id = nil)
+      execution_id = @execution_id if execution_id.nil?
+      log_json = @service.get_log(@id, execution_id)
+      VcoWorkflows::WorkflowExecutionLog.new(log_json)
+    end
+
+    # rubocop:disable MethodLength
+
+    # Stringify the workflow
+    # @return [String]
+    def to_s
+      string =  "Workflow:    #{@name}\n"
+      string << "ID:          #{@id}\n"
+      string << "Description: #{@description}\n"
+      string << "Version:     #{@version}\n"
+
+      string << "\nInput Parameters:\n"
+      if @input_parameters.size > 0
+        @input_parameters.each_value { |wf_param| string << " #{wf_param}" }
+      end
+
+      string << "\nOutput Parameters:" << "\n"
+      if @output_parameters.size > 0
+        @output_parameters.each_value { |wf_param| string << " #{wf_param}" }
+      end
+
+      # Assert
+      string
+    end
+    # rubocop:enable MethodLength
+
+    # Convert the input parameters to a JSON document
+    # @return [String]
+    private def input_parameter_json
+      tmp_params = []
+      @input_parameters.each_value { |v| tmp_params << v.as_struct if v.set? }
+      param_struct = { parameters: tmp_params }
+      param_struct.to_json
+    end
+  end
+  # rubocop:enable ClassLength
+end

data/lib/vcoworkflows/workflowexecutionlog.rb

@@ -0,0 +1,40 @@
+require_relative 'workflowservice'
+require 'json'
+
+# VcoWorkflows
+module VcoWorkflows
+  # WorkflowExecutionLog is a simple object to contain the log for an
+  # execution of a workflow.
+  class WorkflowExecutionLog
+    attr_reader :messages
+
+    # Create an execution log object
+    # @param [String] log_json JSON document as string
+    # @return [VcoWorkflows::WorkflowExecutionLog]
+    def initialize(log_json)
+      @messages = {}
+      JSON.parse(log_json)['logs'].each do |log_entry|
+        messages[log_entry['entry']['time-stamp']] = log_entry['entry']
+      end
+    end
+
+    # rubocop:disable MethodLength, LineLength
+
+    # Stringify the log
+    # @return [String]
+    def to_s
+      message = ''
+      @messages.keys.sort.each do |timestamp|
+        message << "#{Time.at(timestamp / 1000)}"
+        message << " #{@messages[timestamp]['severity']}: #{@messages[timestamp]['user']}:"
+        message << " #{@messages[timestamp]['short-description']}"
+        unless @messages[timestamp]['short-description'].eql?(@messages[timestamp]['long-description'])
+          message << "; #{@messages[timestamp]['long-description']}"
+        end
+        message << "\n"
+      end
+      message
+    end
+    # rubocop:enable MethodLength, LineLength
+  end
+end

data/lib/vcoworkflows/workflowparameter.rb

@@ -0,0 +1,145 @@
+require_relative 'constants'
+require 'json'
+
+module VcoWorkflows
+  # WorkflowParameter is an object wrapper for workflow input and output
+  # parameters.
+  class WorkflowParameter
+    attr_reader :name
+    attr_reader :type
+    attr_reader :subtype
+    attr_reader :value
+
+    # rubocop:disable MethodLength
+
+    # Create a new workflow parameter object
+    # @param [String] name Name of the workflow parameter
+    # @param [String] type Data type of the parameter (according to vCO)
+    # @return [VcoWorkflows::WorkflowParameter]
+    def initialize(name = nil, type = nil, options = {})
+      # Merge provided options with our defaults
+      options = {
+        required: false,
+        value: nil
+      }.merge(options)
+
+      @name = name
+
+      case type
+      when /\//
+        @type = type.gsub(/\/.*$/, '')
+        @subtype = type.gsub(/^.*\//, '')
+      else
+        @type = type
+        @subtype = nil
+      end
+
+      @required = options[:required]
+
+      # If value is supposed to be an array but we dont' have a value yet,
+      # create an empty array. If it's not supposed to be an array, just
+      # set the value, even if it's still nil.
+      if options[:value].nil?
+        @type.eql?('Array') ? @value = [] : @value = nil
+      else
+        @value = set(options[:value])
+      end
+    end
+    # rubocop:enable MethodLength
+
+    # rubocop:disable CyclomaticComplexity
+
+    # Set the parameter value
+    # @param [Object] value Value for the parameter
+    def set(value)
+      # Do some basic checking for Arrays.
+      case @type
+      when 'Array'
+        fail(IOError, ERR[:param_verify_failed]) unless value.is_a?(Array)
+      end unless value.nil?
+      @value = value
+    end
+    # rubocop:enable CyclomaticComplexity
+
+    # Has a value been set for this parameter?
+    # @return [Boolean]
+    def set?
+      case value.class
+      when Array
+        value.size == 0 ? false : true
+      else
+        value.nil? ? false : true
+      end
+    end
+
+    # rubocop:disable TrivialAccessors
+    # rubocop:disable LineLength
+
+    # Set whether or not this WorkflowParameter is required
+    # @param [Boolean] required Set this parameter as required (if not specified)
+    def required(required = true)
+      @required = required
+    end
+    # rubocop:enable LineLength
+
+    # Determine whether or not this WorkflowParameter has been marked as
+    # required
+    # @return [Boolean]
+    def required?
+      @required
+    end
+    # rubocop:enable TrivialAccessors
+
+    # rubocop:disable CyclomaticComplexity, PerceivedComplexity, MethodLength
+
+    # Return a string representation of the parameter
+    # @return [String] Pretty-formatted string
+    def to_s
+      string = "#{@name}"
+      # If value is either nil or an empty array
+      if @value.nil? || @value.is_a?(Array) && @value.size == 0
+        string << " (#{@type}"
+        string << "/#{@subtype}" if @subtype
+        string << ')'
+        string << ' [required]' if @required
+      else
+        if @type.eql?('Array')
+          string << ' ='
+          @value.each { |v| string << "\n  - #{v}" }
+        else
+          string << " = #{@value}"
+        end
+      end
+      string << "\n"
+    end
+    # rubocop:enable CyclomaticComplexity, PerceivedComplexity, MethodLength
+
+    # Public
+    # Return a JSON document representation of this object
+    # @return [String] JSON representation
+    def to_json
+      as_struct.to_json
+    end
+
+    # rubocop:disable LineLength
+
+    # Hashify the parameter (primarily useful for converting to JSON or YAML)
+    # @return [Hash] Contents of this object as a hash
+    def as_struct
+      attributes = { type: @type, name: @name, scope: 'local' }
+
+      # If the value is an array, we need to build it in the somewhat silly
+      # manner that vCO requires it to be presented. Otherwise, just paste
+      # it on the end of the hash.
+      if @type.eql?('Array')
+        fail(IOError, ERR[:wtf]) unless @value.is_a?(Array)
+        attributes[:value] = { @type.downcase => { elements: [] } }
+        @value.each { |val| attributes[:value][@type.downcase][:elements] << { @subtype => { value: val } } }
+      else
+        attributes[:value] = { @type => { value: @value } }
+      end
+      attributes
+    end
+    # rubocop:enable LineLength
+  end
+end