WWW::OrangeHRM::Client(3pm)

1WWW::OrangeHRM::Client(U3s)er Contributed Perl DocumentatWiWoWn::OrangeHRM::Client(3)
2
3
4

NAME

6       WWW::OrangeHRM::Client - Client for OrangeHRM
7

DESCRIPTION

9       This module implements client for OrangeHRM
10       <http://en.wikipedia.org/wiki/OrangeHRM> information system. It has
11       been developed against Red Hat instance, so I cannot guarantee it works
12       with other instances. Author and this code have no business or personal
13       relation to OrangeHRM Inc.
14

SYNOPSIS

16           use WWW::OrangeHRM::Client;
17           my %configuration = (
18               url => 'https://redhat.orangehrm.com/',
19               samlidp => 'https://saml.redhat.com/',
20               samlout => 'https://example.redhat.com/bye',
21               username => 'foo',
22               password => 'bar'
23           );
24           my $debug = 0;
25           my $automaton = WWW::Mechanize->new();
26
27           # Log-in
28           if (!WWW::OrangeHRM::Client::log_in($automaton, \%configuration)) {
29               WWW::OrangeHRM::Client::fatal_error($automaton, $debug,
30                   'Could not log in!');
31           }
32           print "Logged in.\n";
33
34           if (!WWW::OrangeHRM::Client::time_sheet($automaton)) {
35               WWW::OrangeHRM::Client::fatal_error($automaton, $debug,
36                   'Could not get time sheet!');
37           }
38
39           WWW::OrangeHRM::Client::time_sheet_show($automaton);
40
41           # Log-out
42           if (!WWW::OrangeHRM::Client::log_out($automaton)) {
43               WWW::OrangeHRM::Client::fatal_error($automaton, $debug,
44                   'Could not log out!');
45           }
46           print "Logged out.\n";
47

API

49       $automaton is "WWW::Mechanize" object.
50
51   %configuration
52           my %configuration = (
53               url => 'https://redhat.orangehrm.com/',
54               samlidp => 'https://saml.redhat.com/',
55               samlout => 'https://example.redhat.com/bye',
56               username => 'foo',
57               password => undef
58           );
59
60   debug_http($automaton)
61       Call this after creating $automaton if you want to see HTTP request in
62       dump_state() or fatal_error() dump.
63
64   dump_state($automaton)
65       Print details about last request and response.
66
67   fatal_error($automaton, $debug, $message)
68       Call this function, if you encounter fatal error.
69
70       $message will be printed. Automaton state will be dumped if $debug is
71       true.
72
73       This function does not return, it exits program with an error exit
74       code.
75
76   get_text_status($automaton)
77       Return text in *[@id='messageBalloonContainer']/div element of current
78       HTML document or undef.
79
80       The @id specified element exists always. It always contains white space
81       text node. But the error message is stored in div sub-element children
82       and the sub-element exists when reporting error.
83
84       User interface widgets mixed into the status message are ignored.
85
86   get_maintenance_status($automaton)
87       Return text in /html/body/h2 element of current HTML document or return
88       undef.
89
90       If time sheet sub-system is down, server returns 200, but there is a h2
91       element just under body instead of any form or tabular data.
92
93   get_saml_status($automaton)
94       Return text in /html/body/section/div element of current HTML document
95       or undef.
96
97   press_continue_saml_button($automaton)
98       A private function.
99
100       Press a CONTINUE button in the only form of the page and check we get
101       successfully a new page. Return true on success, otherwise false.
102
103   follow_finishlogin_saml_link($automaton)
104       A private function.
105
106       Follow a //a[@id="finishLoginLink"] link a form-less page and check we
107       get successfully a new page. Return true on success, otherwise false.
108
109   do_saml_login($automaton, \%configuration, $prompt_callback)
110       This private function implements Red Hat SAML IDP client.
111
112       Input is the automaton with log-in page. In case of successfull
113       authorization, output automaton will be back on service provider URL
114       domain. See log_in() for $prompt_callback description.
115
116       Returns true on success, false on failure.
117
118   log_in($automaton, \%configuration, $prompt_callback)
119       Log into system as defined in %configuration. If user name or password
120       are needed, $prompt_callback subroutine will be called to obtain the
121       values.
122
123       The $prompt_callback expects two arguments: prompt string without a new
124       line, or any other separator and a boolean indicating if a password is
125       requested. The function must return the value or "undef" to dismiss the
126       request.
127
128       Return false in case of failure, true in case of success.
129
130   do_saml_logout($automaton, %configuration)
131       This private function implements Red Hat SAML IDP client.
132
133       Input is the automaton with a log-out page.
134
135       Returns true on success, false on failure.
136
137   log_out($automaton)
138       Log out the system.
139
140       Return false in case of failure, true in case of success.
141
142   time_sheet_year_month($automaton)
143       Return time identification of current time sheet as (year, month)
144       numbers pair.  E.g. "(2012, 12)".  Return undef in case of error or
145       partial list, e.g. "(2012, undef)".
146
147   year_month2date($year, $month)
148       Return year and month formated to string. E.g. "2012-12".  Return undef
149       in case of error or partial string, e.g. "2012-<unknown month>".
150
151   time_sheet_date($automaton)
152       Return time identification of current time sheet as string. E.g.
153       "2012-12".  Return undef in case of error or partial string, e.g.
154       "2012-<unknown month>".
155
156   time_sheet($automaton)
157       Retrieve current time sheet.
158
159       Return false in case of failure, true in case of success.
160
161   time_sheet_change($automaton, $year, $month)
162       Retrieve time sheet for month specified by $year and $month. Month
163       counts from 1, year is in Gregorian calendar.
164
165       Return false in case of failure, true in case of success.
166
167   time_sheet_parse($automaton)
168       Parse current time sheet.
169
170       Return undef in case of failure, parsed time sheet as a hash reference
171       in case of success:
172
173           {
174               year    => STRING,
175               month   => STRING,
176
177               days    => {
178                   STRING  => {    # day number as a string
179                       label   => STRING,      # pretty name for the day
180                       type    => STRING,      # leave, weekend, holiday etc.
181                       where   => STRING,      # trip, work
182                       from    => DateTime,    # HH::MM accuracy
183                       to      => DateTime,    # HH::MM accuracy
184                       break   => DateTime::Duration,
185                       doctor  => DateTime::Duration,
186                       comment => STRING
187                   },
188                   ...
189               },
190
191               total_entered   => DateTime::Duration,
192               total_leave     => DateTime::Duration,
193               total_holiday   => DateTime::Duration,
194               total_expected  => DateTime::Duration,
195               submission_status   => STRING
196           }
197
198       Any of the values can be "undef".
199
200   time_sheet_show($automaton)
201       Show current time sheet.
202
203       Return false in case of failure, true in case of success.
204
205   normalize_time($time)
206       Return $time value normalized to HH:MM format.
207
208       Return undef if $time is invalid.
209
210       This function can differ from web interface.
211
212   string2time($time)
213       Return HH:MM $time string as a DateTime object. Only hours and minutes
214       are meaningful. Other members are dummy.
215
216       If $time is invalid, return undef.
217
218       This function can differ from web interface.
219
220   time2string ($time)
221       Return DateTime value formated to HH:MM string.
222
223   normalize_duration($duration)
224       Return string $duration value normalized to HH:MM format.
225
226       If $duration is invalid, return original value.
227
228       This function can differ from web interface.
229
230   string2time_duration($duration, strict)
231       Return $duration string as DateTime::Duration in HH:MM units.
232
233       If $duration is invalid, return original value if $strict is false,
234       return undef if $strict is true.
235
236       This function can differ from web interface.
237
238   time_duration2string ($duration)
239       Return DateTime::Duration value formated to HH:MM string.
240
241   set_if_not_amend_or_defined($amend, $field, $value)
242       Return list ($field, $value) if $amend is false or $value is defined.
243       Otherwise return empty list.
244
245   time_sheet_set($automaton, $day, $from, $to, $break, $doctor, $comment,
246       $trip, $amend)
247       This function is deprecated. Please use time_sheet_set_day() followed
248       by time_sheet_save() instead.
249
250       Fill a day into time sheet as if you worked from $from to $to with
251       $break and $doctor hours. $day of month counts from 1. Time format is
252       HH:MM. $comment is free text, $trip is true for bussines trip,
253       otherwise standard work.
254
255       If #amend is false, the day will be overwritten, i.e undefined
256       arguments will empty the day records. If $amend is true, only defined
257       arguments will set, keeping records with undefined arguments untouched.
258
259       Return false in case of failure, true in case of success.
260
261   time_sheet_set_day($automaton, $day, $from, $to, $break, $doctor, $comment,
262       $trip, $amend)
263       Fill a day into time sheet as if you worked from $from to $to with
264       $break and $doctor hours. $day of month counts from 1. Time format is
265       HH:MM. $comment is free text, $trip is true for bussines trip,
266       otherwise standard work.
267
268       If #amend is false, the day will be overwritten, i.e undefined
269       arguments will empty the day records. If $amend is true, only defined
270       arguments will set, keeping records with undefined arguments untouched.
271
272       Return false in case of failure, true in case of success.
273
274       You have to call time_sheet_save() to store modified time sheet into
275       the server. time_sheet_set_day() does the changes locally only.
276
277   time_sheet_update_total_times($automaton)
278       Recalculate totalWork column in a time sheet passed by the argument.
279
280       Return true on success, false otherwise.
281
282   time_sheet_save($automaton)
283       Save current time sheet as obtained by time_sheet() or
284       time_sheet_change() or modified by time_sheet_set_day() into the
285       server.  Total work times are updated automatically.
286
287       Return false in case of failure, true in case of success.
288
289   time_sheet_submit($automaton, $comment)
290       Submit current time sheet for review to your manager. You can set
291       submission $comment. Total work times are updated automatically.
292
293       Return false in case of failure, true in case of success.
294

COPYRIGHT

296       Copyright © 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019  Petr Písař
297       <ppisar@redhat.com>.
298

LICENSE

300       This is free software.  You may redistribute copies of it under the
301       terms of the GNU General Public License
302       <http://www.gnu.org/licenses/gpl.html>.  There is NO WARRANTY, to the
303       extent permitted by law.
304
305
306
307perl v5.38.0                      2023-07-21         WWW::OrangeHRM::Client(3)