Class: Bloomy::Scorecard

Inherits:
Object
  • Object
show all
Includes:
Utilities::Transform, Utilities::UserIdUtility
Defined in:
lib/bloomy/operations/scorecard.rb

Overview

Note:

This class is already initialized via the client and usable as ‘client.scorecard.method`

Class to handle all the operations related to scorecards

Constant Summary

Constants included from Utilities::Transform

Utilities::Transform::DATE_FIELDS

Instance Method Summary collapse

Methods included from Utilities::Transform

#transform_array, #transform_response

Methods included from Utilities::UserIdUtility

#user_id

Constructor Details

#initialize(conn) ⇒ Scorecard

Initializes a new Scorecard instance

Parameters:

  • conn (Object) —

    the connection object to interact with the API



17
18
19
 
# File 'lib/bloomy/operations/scorecard.rb', line 17

def initialize(conn)
  @conn = conn
end

Instance Method Details

#current_week ⇒ HashWithIndifferentAccess

Retrieves the current week details

Examples:

client.scorecard.current_week
#=> { id: 123, week_number: 24, week_start: "2024-06-10", week_end: "2024-06-16" }

Returns:

  • (HashWithIndifferentAccess) —

    a hash containing current week details

Raises:

  • (ApiError) —

    when the API request fails



28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/bloomy/operations/scorecard.rb', line 28

def current_week
  response = @conn.get("weeks/current")
  data = handle_response(response, context: "get current week")

  transform_response({
    id: data.dig("Id"),
    week_number: data.dig("ForWeekNumber"),
    week_start: data.dig("LocalDate", "Date"),
    week_end: data.dig("ForWeek")
  })
end

#get(measurable_id:, user_id: nil, week_offset: 0) ⇒ HashWithIndifferentAccess?

Retrieves a single scorecard item by measurable ID

Examples:

client.scorecard.get(measurable_id: 123)
#=> { id: 1, measurable_id: 123, title: "Sales", target: 100, value: 95, ... }

Parameters:

  • measurable_id (Integer) —

    the ID of the measurable item

  • user_id (Integer, nil) (defaults to: nil) —

    the ID of the user (defaults to initialized user_id)

  • week_offset (Integer) (defaults to: 0) —

    offset for the week number to filter scores (default: 0)

Returns:

  • (HashWithIndifferentAccess, nil) —

    the scorecard hash if found, nil otherwise

Raises:



110
111
112
113
 
# File 'lib/bloomy/operations/scorecard.rb', line 110

def get(measurable_id:, user_id: nil, week_offset: 0)
  scorecards = list(user_id: user_id, show_empty: true, week_offset: week_offset)
  scorecards.find { |s| s[:measurable_id] == measurable_id }
end

#list(user_id: nil, meeting_id: nil, show_empty: false, week_offset: nil) ⇒ Array<HashWithIndifferentAccess>

Note:

The ‘week_offset` parameter is useful when fetching scores for previous or future weeks. For example, to fetch scores for the previous week, you can set `week_offset` to -1. To fetch scores for a future week, you can set `week_offset` to a positive value.

Retrieves the scorecards for a user or a meeting.

Examples:

# Fetch scorecards for the current user
client.scorecard.list

# Fetch scorecards for a specific user
client.scorecard.list(user_id: 42)

# Fetch scorecards for a specific meeting
client.scorecard.list(meeting_id: 99)

Parameters:

  • user_id (Integer, nil) (defaults to: nil) —

    the ID of the user (defaults to initialized user_id)

  • meeting_id (Integer, nil) (defaults to: nil) —

    the ID of the meeting

  • show_empty (Boolean) (defaults to: false) —

    whether to include scores with nil values (default: false)

  • week_offset (Integer, nil) (defaults to: nil) —

    offset for the week number to filter scores

Returns:

  • (Array<HashWithIndifferentAccess>) —

    an array of scorecard hashes

Raises:

  • (ArgumentError) —

    if both ‘user_id` and `meeting_id` are provided

  • (NotFoundError) —

    when user or meeting is not found

  • (ApiError) —

    when the API request fails



63
64
65
66
67
68
69
70
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
 
# File 'lib/bloomy/operations/scorecard.rb', line 63

def list(user_id: nil, meeting_id: nil, show_empty: false, week_offset: nil)
  raise ArgumentError, "Please provide either `user_id` or `meeting_id`, not both." if user_id && meeting_id

  if meeting_id
    response = @conn.get("scorecard/meeting/#{meeting_id}")
    data = handle_response(response, context: "get meeting scorecard")
  else
    user_id ||= self.user_id
    response = @conn.get("scorecard/user/#{user_id}")
    data = handle_response(response, context: "get user scorecard")
  end

  scorecards = transform_array((data.dig("Scores") || []).map do |scorecard|
    {
      id: scorecard.dig("Id"),
      measurable_id: scorecard.dig("MeasurableId"),
      accountable_user_id: scorecard.dig("AccountableUserId"),
      title: scorecard.dig("MeasurableName"),
      target: scorecard.dig("Target"),
      value: scorecard.dig("Measured"),
      week: scorecard.dig("Week"),
      week_id: scorecard.dig("ForWeek"),
      updated_at: scorecard.dig("DateEntered")
    }
  end)

  if week_offset
    week_data = current_week
    week_id = week_data[:week_number] + week_offset
    scorecards.select! { |scorecard| scorecard[:week_id] == week_id }
  end

  scorecards.reject! { |scorecard| scorecard[:value].nil? } unless show_empty
  scorecards
end

#score(measurable_id:, score:, week_offset: 0) ⇒ Boolean

Updates the score for a measurable item for a specific week.

Examples:

client.scorecard.score(measurable_id: 123, score: 5)
#=> true

Parameters:

  • measurable_id (Integer) —

    the ID of the measurable item

  • score (Numeric) —

    the score to be assigned to the measurable item

  • week_offset (Integer) (defaults to: 0) —

    the number of weeks to offset from the current week (default: 0)

Returns:

  • (Boolean) —

    true if the score was successfully updated

Raises:



126
127
128
129
130
131
132
 
# File 'lib/bloomy/operations/scorecard.rb', line 126

def score(measurable_id:, score:, week_offset: 0)
  week_data = current_week
  week_id = week_data[:week_number] + week_offset

  response = @conn.put("measurables/#{measurable_id}/week/#{week_id}", {value: score}.to_json)
  handle_response!(response, context: "update scorecard score")
end