WWW::Or...:Client(3)

πŸ“¦
version 0.12.0 Β· 2 versions
, in fedora 43

🍊 NAME 🍊

WWW::OrangeHRM::Client β€” bestie, it's the client for OrangeHRM πŸ’–

πŸ’« DESCRIPTION πŸ’«

Okay so real talk: this module is a client for the OrangeHRM <http://en.wikipedia.org/wiki/OrangeHRM> information system. It was built against a Red Hat instance specifically, so I cannot guarantee it works with other instances 😭. Also important: the author and this code have no business or personal relation to OrangeHRM Inc. β€” just so we're clear, no cap.

✨ SYNOPSIS ✨

use WWW::OrangeHRM::Client;
my %configuration = (
    url => 'https://redhat.orangehrm.com/',
    samlidp => 'https://saml.redhat.com/',
    samlout => 'https://example.redhat.com/bye',
    username => 'foo',
    password => 'bar'
);
my $debug = 0;
my $automaton = WWW::Mechanize->new();

# Log-in
if (!WWW::OrangeHRM::Client::log_in($automaton, \%configuration)) {
    WWW::OrangeHRM::Client::fatal_error($automaton, $debug,
        'Could not log in!');
}
print "Logged in.\n";

if (!WWW::OrangeHRM::Client::time_sheet($automaton)) {
    WWW::OrangeHRM::Client::fatal_error($automaton, $debug,
        'Could not get time sheet!');
}

WWW::OrangeHRM::Client::time_sheet_show($automaton);

# Log-out
if (!WWW::OrangeHRM::Client::log_out($automaton)) {
    WWW::OrangeHRM::Client::fatal_error($automaton, $debug,
        'Could not log out!');
}
print "Logged out.\n";

πŸ‘‘ API πŸ‘‘

$automaton is a WWW::Mechanize object. That's the whole vibe. πŸ’…

πŸŽ€ %configuration πŸŽ€

my %configuration = (
    url => 'https://redhat.orangehrm.com/',
    samlidp => 'https://saml.redhat.com/',
    samlout => 'https://example.redhat.com/bye',
    username => 'foo',
    password => undef
);

πŸ¦‹ debug_http($automaton)

Call this after you've made $automaton, bestie, if you wanna actually see the HTTP request when dump_state() or fatal_error() dumps stuff. Iconic for debugging fr fr πŸ”₯

🌸 dump_state($automaton)

Prints all the deets about the last request and response. Receipts, basically. 🧾

πŸ’€ fatal_error($automaton, $debug, $message)

Call this one when you hit a fatal error, like when everything is lowkey falling apart.

$message gets printed. And the automaton state gets dumped if $debug is true.

⚠️ Heads up bestie: this function does not return β€” it exits the program with an error exit code. It's giving main character exit. Periodt.

🫢 get_text_status($automaton)

Returns the text inside the *[@id='messageBalloonContainer']/div element of the current HTML document, or undef.

The @id specified element always exists, okay? It always contains a white space text node. But the actual error message is stored in the div sub-element children β€” and that sub-element only exists when reporting an error. Sneaky.

Also: user interface widgets mixed into the status message? Ignored. Not our problem.

🌈 get_maintenance_status($automaton)

Returns the text in the /html/body/h2 element of the current HTML document, or returns undef.

Why does this exist? Because if the time sheet sub-system is down, the server returns 200 like everything's fine πŸ™ˆ but there's an h2 element just under body instead of any form or tabular data. Rude.

⭐ get_saml_status($automaton)

Returns the text in the /html/body/section/div element of the current HTML document, or undef.

πŸŽ€ press_continue_saml_button($automaton)

A private function πŸ’…

It presses a CONTINUE button in the only form of the page, then checks we successfully got a new page. Returns true on success, otherwise false.

A private function πŸ’…

Follows a //a[@id="finishLoginLink"] link on a form-less page and checks we successfully get a new page. Returns true on success, otherwise false.

πŸ”₯ do_saml_login($automaton, \%configuration, $prompt_callback)

This private function implements the Red Hat SAML IDP client.

Input is the automaton with the log-in page. In case of successful authorization, the output automaton will be back on the service provider URL domain. See log_in() for the $prompt_callback description.

Returns true on success, false on failure.

πŸ’– log_in($automaton, \%configuration, $prompt_callback)

Logs into the system as defined in %configuration. If a user name or password is needed, the $prompt_callback subroutine gets called to obtain the values. ✨

The $prompt_callback expects two arguments: the prompt string without a new line, or any other separator, and a boolean indicating if a password is requested. The function must return the value, or undef to dismiss the request.

Returns false on failure, true on success.

πŸ‘‘ do_saml_logout($automaton, %configuration)

This private function implements the Red Hat SAML IDP client.

Input is the automaton with a log-out page.

Returns true on success, false on failure.

🌸 log_out($automaton)

Logs out of the system. Bye bestie πŸ‘‹

Returns false on failure, true on success.

🧚 time_sheet_year_month($automaton)

Returns the time identification of the current time sheet as a (year, month) numbers pair. E.g. (2012, 12). Returns undef in case of error or a partial list, e.g. (2012, undef).

πŸ“ year_month2date($year, $month)

Returns year and month formatted to a string. E.g. 2012-12. Returns undef in case of error or a partial string, e.g. 2012-<unknown month>.

πŸ’œ time_sheet_date($automaton)

Returns the time identification of the current time sheet as a string. E.g. 2012-12. Returns undef in case of error or a partial string, e.g. 2012-<unknown month>.

⭐ time_sheet($automaton)

Retrieves the current time sheet. Slay.

Returns false on failure, true on success.

🌈 time_sheet_change($automaton, $year, $month)

Retrieves the time sheet for the month specified by $year and $month. Month counts from 1, and year is in the Gregorian calendar.

Returns false on failure, true on success.

πŸŽ€ time_sheet_parse($automaton)

Parses the current time sheet.

Returns undef on failure, or the parsed time sheet as a hash reference on success:

{
    year    => STRING,
    month   => STRING,

    days    => {
        STRING  => {    # day number as a string
            label   => STRING,      # pretty name for the day
            type    => STRING,      # leave, weekend, holiday etc.
            where   => STRING,      # trip, work
            from    => DateTime,    # HH::MM accuracy
            to      => DateTime,    # HH::MM accuracy
            break   => DateTime::Duration,
            doctor  => DateTime::Duration,
            comment => STRING
        },
        ...
    },

    total_entered   => DateTime::Duration,
    total_leave     => DateTime::Duration,
    total_holiday   => DateTime::Duration,
    total_expected  => DateTime::Duration,
    submission_status   => STRING
}

Any of those values can be undef. It's giving mystery box, honestly πŸ™ˆ

πŸ’… time_sheet_show($automaton)

Shows the current time sheet.

Returns false on failure, true on success.

πŸ¦‹ normalize_time($time)

Returns the $time value normalized to HH:MM format.

Returns undef if $time is invalid.

Heads up: this function can differ from the web interface.

🌸 string2time($time)

Returns the HH:MM $time string as a DateTime object. Only hours and minutes are meaningful β€” other members are just dummy.

If $time is invalid, returns undef.

Also can differ from the web interface.

🧚 time2string ($time)

Returns the DateTime value formatted to an HH:MM string.

πŸ“ normalize_duration($duration)

Returns the string $duration value normalized to HH:MM format.

If $duration is invalid, returns the original value.

Can differ from the web interface, yep.

πŸ’œ string2time_duration($duration, strict)

Returns the $duration string as a DateTime::Duration in HH:MM units.

If $duration is invalid: returns the original value if $strict is false, and returns undef if $strict is true.

Can differ from the web interface. Again. 😭

⭐ time_duration2string ($duration)

Returns the DateTime::Duration value formatted to an HH:MM string.

🌈 set_if_not_amend_or_defined($amend, $field, $value)

Returns a list ($field, $value) if $amend is false or $value is defined. Otherwise returns an empty list.

πŸ”₯ time_sheet_set($automaton, $day, $from, $to, $break, $doctor, $comment, $trip, $amend)

⚠️ This function is deprecated. Please use time_sheet_set_day() followed by time_sheet_save() instead. We're moving on, bestie.

Fills a day into the time sheet as if you worked from $from to $to with $break and $doctor hours. $day of month counts from 1. Time format is HH:MM. $comment is free text, $trip is true for a business trip, otherwise standard work.

If #amend is false, the day will be overwritten β€” i.e. undefined arguments will empty the day records. If $amend is true, only defined arguments will set, keeping records with undefined arguments untouched. Choose wisely πŸ’…

Returns false on failure, true on success.

πŸŽ€ time_sheet_set_day($automaton, $day, $from, $to, $break, $doctor, $comment, $trip, $amend)

Fills a day into the time sheet as if you worked from $from to $to with $break and $doctor hours. $day of month counts from 1. Time format is HH:MM. $comment is free text, $trip is true for a business trip, otherwise standard work.

If #amend is false, the day will be overwritten β€” i.e. undefined arguments will empty the day records. If $amend is true, only defined arguments will set, keeping records with undefined arguments untouched.

Returns false on failure, true on success.

πŸ“Œ PSA: you have to call time_sheet_save() to store the modified time sheet into the server. time_sheet_set_day() only does the changes locally. Don't forget, bestie, or nothing saves 😭

πŸ¦‹ time_sheet_update_total_times($automaton)

Recalculates the totalWork column in a time sheet passed by the argument.

Returns true on success, false otherwise.

🌸 time_sheet_save($automaton)

Saves the current time sheet β€” as obtained by time_sheet() or time_sheet_change(), or modified by time_sheet_set_day() β€” into the server. Total work times are updated automatically. So convenient. ✨

Returns false on failure, true on success.

πŸ‘‘ time_sheet_submit($automaton, $comment)

Submits the current time sheet for review to your manager. You can set the submission $comment. Total work times are updated automatically.

Returns false on failure, true on success.

Copyright Β© 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Petr PΓ­saΕ™ <ppisar@redhat.com>.

πŸŽ€ LICENSE πŸŽ€

This is free software. You may redistribute copies of it under the terms of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent permitted by law.

okay that's the whole page bestie, you ate it up πŸ’…βœ¨ this was perl v5.42.0, dated 2025-07-25, from WWW::Or...:Client(3) β€” love u, go log some hours πŸ“πŸ¦‹πŸ’–

πŸ“¦ where this page comes from