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 //div[@id="login-message"] element of current HTML
95       document 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   do_saml_login($automaton, \%configuration, $prompt_callback)
104       This private function implements Red Hat SAML IDP client.
105
106       Input is the automaton with log-in page. In case of successfull
107       authorization, output automaton will be back on service provider URL
108       domain. See log_in() for $prompt_callback description.
109
110       Returns true on success, false on failure.
111
112   log_in($automaton, \%configuration, $prompt_callback)
113       Log into system as defined in %configuration. If user name or password
114       are needed, $prompt_callback subroutine will be called to obtain the
115       values.
116
117       The $prompt_callback expects two arguments: prompt string without a new
118       line, or any other separator and a boolean indicating if a password is
119       requested. The function must return the value or "undef" to dismiss the
120       request.
121
122       Return false in case of failure, true in case of success.
123
124   do_saml_logout($automaton, %configuration)
125       This private function implements Red Hat SAML IDP client.
126
127       Input is the automaton with log-out page.
128
129       Returns true on success, false on failure.
130
131   log_out($automaton)
132       Log out the system.
133
134       Return false in case of failure, true in case of success.
135
136   time_sheet_year_month($automaton)
137       Return time identification of current time sheet as (year, month)
138       numbers pair.  E.g. "(2012, 12)".  Return undef in case of error or
139       partial list, e.g. "(2012, undef)".
140
141   year_month2date($year, $month)
142       Return year and month formated to string. E.g. "2012-12".  Return undef
143       in case of error or partial string, e.g. "2012-<unknown month>".
144
145   time_sheet_date($automaton)
146       Return time identification of current time sheet as string. E.g.
147       "2012-12".  Return undef in case of error or partial string, e.g.
148       "2012-<unknown month>".
149
150   time_sheet($automaton)
151       Retrieve current time sheet.
152
153       Return false in case of failure, true in case of success.
154
155   time_sheet_change($automaton, $year, $month)
156       Retrieve time sheet for month specified by $year and $month. Month
157       counts from 1, year is in Gregorian calendar.
158
159       Return false in case of failure, true in case of success.
160
161   time_sheet_parse($automaton)
162       Parse current time sheet.
163
164       Return undef in case of failure, parsed time sheet as a hash reference
165       in case of success:
166
167           {
168               year    => STRING,
169               month   => STRING,
170
171               days    => {
172                   STRING  => {    # day number as a string
173                       label   => STRING,      # pretty name for the day
174                       type    => STRING,      # leave, weekend, holiday etc.
175                       where   => STRING,      # trip, work
176                       from    => DateTime,    # HH::MM accuracy
177                       to      => DateTime,    # HH::MM accuracy
178                       break   => DateTime::Duration,
179                       doctor  => DateTime::Duration,
180                       comment => STRING
181                   },
182                   ...
183               },
184
185               total_entered   => DateTime::Duration,
186               total_leave     => DateTime::Duration,
187               total_holiday   => DateTime::Duration,
188               total_expected  => DateTime::Duration,
189               submission_status   => STRING
190           }
191
192       Any of the values can be "undef".
193
194   time_sheet_show($automaton)
195       Show current time sheet.
196
197       Return false in case of failure, true in case of success.
198
199   normalize_time($time)
200       Return $time value normalized to HH:MM format.
201
202       Return undef if $time is invalid.
203
204       This function can differ from web interface.
205
206   string2time($time)
207       Return HH:MM $time string as a DateTime object. Only hours and minutes
208       are meaningful. Other members are dummy.
209
210       If $time is invalid, return undef.
211
212       This function can differ from web interface.
213
214   time2string ($time)
215       Return DateTime value formated to HH:MM string.
216
217   normalize_duration($duration)
218       Return string $duration value normalized to HH:MM format.
219
220       If $duration is invalid, return original value.
221
222       This function can differ from web interface.
223
224   string2time_duration($duration, strict)
225       Return $duration string as DateTime::Duration in HH:MM units.
226
227       If $duration is invalid, return original value if $strict is false,
228       return undef if $strict is true.
229
230       This function can differ from web interface.
231
232   time_duration2string ($duration)
233       Return DateTime::Duration value formated to HH:MM string.
234
235   set_if_not_amend_or_defined($amend, $field, $value)
236       Return list ($field, $value) if $amend is false or $value is defined.
237       Otherwise return empty list.
238
239   time_sheet_set($automaton, $day, $from, $to, $break, $doctor, $comment,
240       $trip, $amend)
241       This function is deprecated. Please use "time_sheet_set_day()" followed
242       by "time_sheet_save()" instead.
243
244       Fill a day into time sheet as if you worked from $from to $to with
245       $break and $doctor hours. $day of month counts from 1. Time format is
246       HH:MM. $comment is free text, $trip is true for bussines trip,
247       otherwise standard work.
248
249       If #amend is false, the day will be overwritten, i.e undefined
250       arguments will empty the day records. If $amend is true, only defined
251       arguments will set, keeping records with undefined arguments untouched.
252
253       Return false in case of failure, true in case of success.
254
255   time_sheet_set_day($automaton, $day, $from, $to, $break, $doctor, $comment,
256       $trip, $amend)
257       Fill a day into time sheet as if you worked from $from to $to with
258       $break and $doctor hours. $day of month counts from 1. Time format is
259       HH:MM. $comment is free text, $trip is true for bussines trip,
260       otherwise standard work.
261
262       If #amend is false, the day will be overwritten, i.e undefined
263       arguments will empty the day records. If $amend is true, only defined
264       arguments will set, keeping records with undefined arguments untouched.
265
266       Return false in case of failure, true in case of success.
267
268       You have to call "time_sheet_save()" to store modified time sheet into
269       the server. "time_sheet_set_day()" does the changes locally only.
270
271   time_sheet_update_total_times($automaton)
272       Recalculate totalWork column in a time sheet passed by the argument.
273
274       Return true on success, false otherwise.
275
276   time_sheet_save($automaton)
277       Save current time sheet as obtained by "time_sheet()" or
278       "time_sheet_change()" or modified by "time_sheet_set_day()" into the
279       server.  Total work times are updated automatically.
280
281       Return false in case of failure, true in case of success.
282
283   time_sheet_submit($automaton, $comment)
284       Submit current time sheet for review to your manager. You can set
285       submission $comment. Total work times are updated automatically.
286
287       Return false in case of failure, true in case of success.
288

COPYRIGHT

290       Copyright © 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019  Petr Písař
291       <ppisar@redhat.com>.
292

LICENSE

294       This is free software.  You may redistribute copies of it under the
295       terms of the GNU General Public License
296       <http://www.gnu.org/licenses/gpl.html>.  There is NO WARRANTY, to the
297       extent permitted by law.
298
299
300
301perl v5.28.1                      2019-03-06         WWW::OrangeHRM::Client(3)