vcoworkflows-ruby2 0.2.3

data/lib/vcoworkflows/workflowexecutionlog.rb

@@ -0,0 +1,42 @@
+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
+    # Log messages
+    # @return [String[]] Array of log message lines
+    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).to_s
+        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,150 @@
+require_relative 'constants'
+require 'json'
+
+module VcoWorkflows
+  # WorkflowParameter is an object wrapper for workflow input and output
+  # parameters.
+  class WorkflowParameter
+    # Parameter name
+    # @return [String] parameter name
+    attr_reader :name
+
+    # Parameter type
+    # @return [String] parameter type
+    attr_reader :type
+
+    # Parameter subtype (used when type is 'Array')
+    # @return [String] parameter subtype
+    attr_reader :subtype
+
+    # Parameter value
+    # @return [Object] parameter value
+    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 %r{\/}
+        @type = type.gsub(%r{\/.*$}, '')
+        @subtype = type.gsub(%r{^.*\/}, '')
+      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.
+      @value = if options[:value].nil?
+                 @type.eql?('Array') ? [] : nil
+               else
+                 set(options[:value])
+               end
+    end
+    # rubocop:enable MethodLength
+
+    # Set the parameter value
+    # @param [Object] value Value for the parameter
+    def set(value)
+      # Do some basic checking for Arrays.
+      unless value.nil?
+        case @type
+        when 'Array'
+          raise(IOError, ERR[:param_verify_failed]) unless value.is_a?(Array)
+        end
+      end
+      @value = value
+    end
+    # rubocop:enable CyclomaticComplexity
+
+    # Has a value been set for this parameter?
+    # @return [Boolean]
+    def set?
+      case value.class
+      when Array
+        value.empty? ? false : true
+      else
+        value.nil? ? false : true
+      end
+    end
+
+    # 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:disable CyclomaticComplexity, PerceivedComplexity, MethodLength
+
+    # Return a string representation of the parameter
+    # @return [String] Pretty-formatted string
+    def to_s
+      string = @name.to_s
+      # If value is either nil or an empty array
+      if @value.nil? || @value.is_a?(Array) && @value.empty?
+        string << " (#{@type}"
+        string << "/#{@subtype}" if @subtype
+        string << ')'
+        string << ' [required]' if @required
+      elsif @type.eql?('Array')
+        string << ' ='
+        @value.each { |v| string << "\n  - #{v}" }
+      else
+        string << " = #{@value}"
+      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')
+        raise(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

data/lib/vcoworkflows/workflowpresentation.rb

@@ -0,0 +1,62 @@
+require_relative 'constants'
+require_relative 'workflowservice'
+require_relative 'workflow'
+require_relative 'workflowtoken'
+require_relative 'workflowparameter'
+require 'json'
+
+# VcoWorkflows
+module VcoWorkflows
+  # WorkflowPresentation is a helper class for Workflow and is primarily used
+  # internally to apply additional constraints to WorkflowParameters. Currently
+  # WorkflowPresentation examines the presentation JSON from vCO to determine
+  # whether input parameters for the workflow are required or not.
+  class WorkflowPresentation
+    # Accessor for the data structure
+    # @return [Hash] parsed JSON
+    attr_reader :presentation_data
+
+    # Get the list of required parameters for the workflow
+    # @return [String[]] Array of strings (names of parameters)
+    attr_reader :required
+
+    # rubocop:disable MethodLength
+
+    # Create a new WorkflowPresentation
+    # @param [VcoWorkflows::WorkflowService] workflow_service workflow service to use
+    # @param [String] workflow_id workflow GUID
+    # @return [VcoWorkflows::WorkflowPresentation]
+    def initialize(workflow_service, workflow_id)
+      @required = []
+      @presentation_data = JSON.parse(workflow_service.get_presentation(workflow_id))
+
+      # Determine if there are any required input parameters
+      # We're parsing this because we specifically want to know if any of
+      # the input parameters are marked as required. This is very specifically
+      # in the array of hashes in:
+      # presentation_data[:steps][0][:step][:elements][0][:fields]
+      fields = @presentation_data['steps'][0]['step']['elements'][0]['fields']
+      fields.each do |attribute|
+        next unless attribute.key?('constraints')
+        attribute['constraints'].each do |const|
+          if const.key?('@type') && const['@type'].eql?('mandatory')
+            @required << attribute['id']
+          end
+        end
+      end
+    end
+
+    # String representation of the presentation
+    # @return [String]
+    def to_s
+      @presentation_data.to_s
+    end
+
+    # JSON document
+    # @return [String] JSON Document
+    def to_json
+      JSON.pretty_generate(@presentation_data)
+    end
+  end
+  # rubocop:enable ClassLength
+end

data/lib/vcoworkflows/workflowservice.rb

@@ -0,0 +1,109 @@
+require_relative 'constants'
+require_relative 'vcosession'
+require_relative 'workflow'
+require_relative 'workflowexecutionlog'
+require 'json'
+require 'erb'
+
+include ERB::Util
+
+module VcoWorkflows
+  # WorkflowService is the object which acts as the interface to the vCO
+  # API, and is loosely modeled from the vCO API documentation.
+  class WorkflowService
+    # The VcoSession used by this service
+    # @return [VcoWorkflows::VcoSession]
+    attr_reader :session
+
+    # Create a new WorkflowService
+    # @param [VcoWorkflows::VcoSession] session Session object for the API endpoint
+    # @return [VcoWorkflows::WorkflowService]
+    def initialize(session)
+      @session = session
+    end
+    # rubocop:enable LineLength
+
+    # Get a workflow by GUID
+    # @param [String] id Workflow GUID
+    # @return [String] the JSON document of the requested workflow
+    def get_workflow_for_id(id)
+      @session.get("/workflows/#{id}").body
+    end
+
+    # Get the presentation for the given workflow GUID
+    # @param [String] workflow_id workflow GUID
+    # @return [String] JSON document representation of Workflow Presentation
+    def get_presentation(workflow_id)
+      @session.get("/workflows/#{workflow_id}/presentation/").body
+    end
+
+    # Get one workflow with a specified name.
+    # @param [String] name Name of the workflow
+    # @return [String] the JSON document of the requested workflow
+    def get_workflow_for_name(name)
+      path = "/workflows?conditions=name=#{url_encode(name)}"
+      response = JSON.parse(@session.get(path).body)
+
+      # barf if we got anything other than a single workflow
+      raise(IOError, ERR[:too_many_workflows]) if response['total'] > 1
+      raise(IOError, ERR[:no_workflow_found]) if response['total'].zero?
+
+      # yank out the workflow id and name from the result attributes
+      workflow_id = nil
+      response['link'][0]['attributes'].each do |a|
+        workflow_id = a['value'] if a['name'].eql?('id')
+      end
+
+      # Get the workflow by GUID
+      get_workflow_for_id(workflow_id)
+    end
+
+    # Get a WorkflowToken for the requested workflow_id and execution_id
+    # @param [String] workflow_id Workflow GUID
+    # @param [String] execution_id Execution GUID
+    # @return [String] JSON document for workflow token
+    def get_execution(workflow_id, execution_id)
+      path = "/workflows/#{workflow_id}/executions/#{execution_id}"
+      @session.get(path).body
+    end
+
+    # Get a list of executions for the given workflow GUID
+    # @param [String] workflow_id Workflow GUID
+    # @return [Hash] workflow executions, keyed by execution ID
+    def get_execution_list(workflow_id)
+      path = "/workflows/#{workflow_id}/executions/"
+      relations = JSON.parse(@session.get(path).body)['relations']
+      # The first two elements of the relations['link'] array are URLS,
+      # so scrap them. Everything else is an execution.
+      executions = {}
+      relations['link'].each do |link|
+        next unless link.key?('attributes')
+        attributes = {}
+        link['attributes'].each { |a| attributes[a['name']] = a['value'] }
+        executions[attributes['id']] = attributes
+      end
+      executions
+    end
+
+    # Get the log for a specific execution
+    # @param [String] workflow_id Workflow GUID
+    # @param [String] execution_id Workflow execution ID
+    # @return [String] JSON log document
+    def get_log(workflow_id, execution_id)
+      path = "/workflows/#{workflow_id}/executions/#{execution_id}/logs/"
+      @session.get(path).body
+    end
+
+    # Submit the given workflow for execution
+    # @param [String] id Workflow GUID for the workflow we want to execute
+    # @param [String] parameter_json JSON document of input parameters
+    # @return [String] Execution ID
+    def execute_workflow(id, parameter_json)
+      path = "/workflows/#{id}/executions/"
+      response = @session.post(path, parameter_json)
+      # Execution ID is the final component in the Location header URL, so
+      # chop off the front, then pull off any trailing /
+      response.headers[:location].gsub(%r{^.*/executions/}, '').gsub(%r{\/$}, '')
+    end
+  end
+end

data/lib/vcoworkflows/workflowtoken.rb

@@ -0,0 +1,154 @@
+require_relative 'constants'
+require_relative 'workflow'
+require_relative 'workflowservice'
+require 'json'
+
+module VcoWorkflows
+  # WorkflowToken is used for workflow execution results, and contains as much
+  # data on the given workflow execution instance as vCO can provide.
+  class WorkflowToken
+    # rubocop:disable LineLength
+
+    # Workflow execution ID
+    # @return [String] the execution id for this token
+    attr_reader :id
+
+    # Workflow ID
+    # @return [String] the GUID for this workflow
+    attr_reader :workflow_id
+
+    # Workflow name
+    # @return [String] name of the workflow
+    attr_reader :name
+
+    # Execution state
+    # @return [String] current state of the workflow execution
+    attr_reader :state
+
+    # Execution href
+    # @return [String] link to this execution via the REST API
+    attr_reader :href
+
+    # Execution start date
+    # @return [String] date and time the workflow execution started
+    attr_reader :start_date
+
+    # Execution end date
+    # @return [String] date and time the workflow execution ended
+    attr_reader :end_date
+
+    # Execution started by
+    # @return [String] vCO user who started this execution
+    attr_reader :started_by
+
+    # @return [String]
+    attr_reader :current_item_name
+
+    # @return [String]
+    attr_reader :current_item_state
+
+    # @return [String]
+    attr_reader :content_exception
+
+    # @return [String]
+    attr_reader :global_state
+
+    # Workflow execution input parameters
+    # @return [VcoWorkflows::WorkflowParameter{}] Hash of input parameters which were given when the workflow was executed
+    attr_reader :input_parameters
+
+    # Workflow execution output parameters
+    # @return [VcoWorkflows::WorkflowParameter{}] Hash of output parameters set by the workflow execution
+    attr_reader :output_parameters
+
+    # Source JSON
+    # @return [String] source JSON document returned by vCO for this execution
+    attr_reader :json_content
+
+    # rubocop:enable LineLength
+
+    # rubocop:disable CyclomaticComplexity, PerceivedComplexity, MethodLength, LineLength
+
+    # Create a new workflow token
+    # @param [VcoWorkflows::WorkflowService] workflow_service Workflow service to use
+    # @param [String] workflow_id GUID of the workflow
+    # @param [String] execution_id GUID of execution
+    # @return [VcoWorkflows::WorkflowToken]
+    def initialize(workflow_service, workflow_id, execution_id)
+      @service = workflow_service
+      @workflow_id = workflow_id
+      @json_content = @service.get_execution(workflow_id, execution_id)
+
+      token = JSON.parse(@json_content)
+      @id                 = token.key?('id')                        ? token['id']                        : nil
+      @name               = token.key?('name')                      ? token['name']                      : nil
+      @state              = token.key?('state')                     ? token['state']                     : nil
+      @href               = token.key?('href')                      ? token['href']                      : nil
+      @start_date         = token.key?('start-date')                ? token['start-date']                : nil
+      @end_date           = token.key?('end-date')                  ? token['end-date']                  : nil
+      @started_by         = token.key?('started-by')                ? token['started-by']                : nil
+      @current_item_name  = token.key?('current-item-display-name') ? token['current-item-display-name'] : nil
+      @current_item_state = token.key?('current-item-state')        ? token['current-item-state']        : nil
+      @global_state       = token.key?('global-state')              ? token['global-state']              : nil
+      @content_exception  = token.key?('content-exeption')          ? token['content-exception']         : nil
+
+      if token.key?('input-parameters')
+        @input_parameters = VcoWorkflows::Workflow.parse_parameters(token['input-parameters'])
+      else
+        @input_parameters = {}
+      end
+
+      if token.key?('output-parameters')
+        @output_parameters = VcoWorkflows::Workflow.parse_parameters(token['output-parameters'])
+      else
+        @output_parameters = {}
+      end
+    end
+    # rubocop:enable CyclomaticComplexity, PerceivedComplexity, MethodLength, LineLength
+
+    # Is the workflow execution still alive?
+    # @return [Boolean]
+    def alive?
+      running? || waiting?
+    end
+
+    # Is the workflow actively running?
+    # @return [Boolean]
+    def running?
+      state.eql?('running')
+    end
+
+    # Is the workflow in a waiting state?
+    # @return [Boolean]
+    def waiting?
+      state.match(/waiting/).nil? ? false : true
+    end
+
+    # rubocop:disable MethodLength, LineLength
+
+    # Convert this object to a string representation
+    # @return [String]
+    def to_s
+      string =  "Execution ID:      #{@id}\n"
+      string << "Name:              #{@name}\n"
+      string << "Workflow ID:       #{@workflow_id}\n"
+      string << "State:             #{@state}\n"
+      string << "Start Date:        #{Time.at(@start_date / 1000)}\n"
+      string << "End Date:          #{end_date.nil? ? '' : Time.at(@end_date / 1000)}\n"
+      string << "Started By:        #{@started_by}\n"
+      string << "Content Exception: #{@content_exception}\n" unless @content_exception.nil?
+      string << "\nInput Parameters:\n"
+      @input_parameters.each_value { |wf_param| string << " #{wf_param}" if wf_param.set? } unless @input_parameters.empty?
+      string << "\nOutput Parameters:" << "\n"
+      @output_parameters.each_value { |wf_param| string << " #{wf_param}" } unless @output_parameters.empty?
+      string
+    end
+    # rubocop:enable MethodLength, LineLength
+
+    # Convert this object to a JSON document (string)
+    # @return [String] JSON representation of the workflow token
+    def to_json
+      JSON.pretty_generate(JSON.parse(@json_content))
+    end
+  end
+end