Internals: report.pm

This module provides various tools for notification and error reports in every Sympa interface (mail diffusion, mail command and web command).

For a requested service, there are four kinds of reports to users:

• success notification
  when the action does not involve any specific mail report or else, the user is notified of the well done of the processus.
• non authorization(auth)
  a user is not allowed to perform an action, Sympa provides reason of rejecting. The template used to provides this information is mail_tt2/authorization_reject.tt2. It contains a list of reasons, indexed by keywords that are mentioned in reject action scenario (see rules, page )
• user error(user)
  a error caused by the user, the user is informed about the error reason
• internal server error(intern)
  an error independent from the user, the user is succintly informed about the error reason but a mail with more information is sent to listmaster using template mail_tt2/listmaster_notification.tt2(If it is not necessary, keyword used is 'intern_quiet'.

For other reports than non authorizations templates used depends on the interface:

• message diffusion: mail_tt2/message_report.tt2
• mail commands: mail_tt2/command_report.tt2
• web commands: web_tt2/notice.tt2 for positive notifications and web_tt2/error.tt2 for rejects.

These reports use template mail_tt2/message_report.tt2 and there are two functions: reject_report_msg() and notice_report_msg().

Sends a notification to the user about an error rejecting his requested message diffusion.

IN:

1. type(+): 'intern'|'intern_quiet'|'user'|'auth' - the error type
2. error: SCALAR - depends on $type:
   • 'intern': string error sent to listmaster
   • 'user': $entry in message_report.tt2
   • 'auth': $reason in authorization_reject.tt2
3. user(+): SCALAR - the user to notify
4. param: ref(HASH) - for variable instantiation message_report.tt2 (key msgid(+) is required if type == 'intern')
5. robot: SCALAR - robot
6. msg_string: SCALAR - rejected message
7. list: ref(List) - in a list context

OUT: 1 undef

Sends a notification to the user about a success about his requested message diffusion.

IN:

1. entry(+): $entry in message_report.tt2
2. user(+): SCALAR - the user to notify
3. param: ref(HASH) - for variable instantiation message_report.tt2
4. robot(+): SCALAR - robot
5. list: ref(List) - in a list context

OUT: 1 undef

A mail can contains many commands. Errors and notices are stored in module global arrays before sending (intern_error_cmd, user_error_cmd, global_error_cmd, auth_reject_cmd, notice_cmd). Moreover used errors here we can have global errors on mail containing commands, so there is a function for that. These reports use template mail_tt2/command_report.tt2 and there are many functions:

Inits global arrays for mail command reports.

IN: -

OUT: -

Looks for some mail command reports in one of global arrays.

IN: -

OUT: 1 if there are some reports to send

Concerns global reports of mail commands. There are many uses cases:

1. internal server error for a differed sending at the end of the mail processing:
   • global_report_cmd('intern',$error,$data,$sender,$robot)
   • global_report_cmd('intern_quiet',$error,$data): the listmaster won't be noticied
2. internal server error for sending every reports directly (by calling send_report_cmd()):
   • global_report_cmd('intern',$error,$data,$sender,$robot,1)
   • global_report_cmd('intern_quiet',$error,$data,$sender,$robot,1): the listmaster won't be noticied
3. user error for a differed sending at the end of the mail processing:
   global_report_cmd('user',$error,$data
4. user error for sending every reports directly (by calling send_report_cmd()):
   global_report_cmd('user',$error,$data,$sender,$robot,1)

IN:

1. type(+): 'internintern_quietuser'
2. error: SCALAR - depends on $type:
   • 'intern': string error sent to listmaster
   • 'user': $glob.entry in command_report.tt2
3. data: ref(HASH) - for variable instantiation in command_report.tt2
4. sender: SCALAR - the user to notify
5. robot: SCALAR - robot
6. now: BOOLEAN - send reports now if true

OUT: 1 undef

Concerns reject reports of mail commands. These informations are sent at the end of the mail processing. There are many uses cases:

1. internal server error:
   • reject_report_cmd('intern',$error,$data,$cmd,$sender,$robot)
   • reject_report_cmd('intern_quiet',$error,$data,$cmd): the listmaster won't be noticied
2. user error:
   reject_report_cmd('user',$error,$data,$cmd)
3. non authorization:
   reject_report_cmd('auth',$error,$data,$cmd)

IN:

1. type(+): 'intern'|'intern_quiet'|'user'|'auth'
2. error: SCALAR - depends on $type:
   • 'intern': string error sent to listmaster
   • 'user': $u_err.entry in command_report.tt2
   • 'auth': $reason in authorization_reject.tt2
3. data: ref(HASH) - for variable instantiation in command_report.tt2
4. cmd: SCALAR - the rejected command, $xx.cmd in command_report.tt2
5. sender: SCALAR - the user to notify
6. robot: SCALAR - robot

OUT: 1 undef

Concerns positive notices of mail commands. These informations are sent at the end of the mail processing.

IN:

1. entry: $notice.entry in command_report.tt2
2. data: ref(HASH) - for variable instantiation in command_report.tt2
3. cmd: SCALAR - the rejected command, $xx.cmd in command_report.tt2

OUT: 1 undef

Sends the template command_report.tt2 to $sender with global arrays and then calls to init_report_command.tt2 function. (It is used by sympa.pl at the end of mail process if there are some reports in gloal arrays)

IN:

1. sender(+): SCALAR - the user to notify
2. robot(+): SCALAR - robot

OUT: 1

It can have many errors and notices so they are stored in module global arrays before html sending. (intern_error_web, user_error_web, auth_reject_web, notice_web). These reports use web_tt2/notice.tt2 template for notices and web_tt2/error.tt2 template for rejects.

Inits global arrays for web command reports.

IN: -

OUT: -

Looks for some rejected web command reports in one of global arrays for reject.

IN: -

OUT: 1 if there are some reject reports to send (not notice)

Return array of web intern error

IN: -

OUT: ref(ARRAY) - clone of intern_error_web

Return array of web user error

IN: -

OUT: ref(ARRAY) - clone of user_error_web

Return array of web authorisation reject

IN: -

OUT: ref(ARRAY) - clone of auth_reject_web

Return array of web notice

IN: -

OUT: ref(ARRAY) - clone of notice_web

Concerning reject reports of web commands, there are many uses cases:

1. internal server error:
   • reject_report_web('intern',$error,$data,$action,$list,$user,$robot)
   • reject_report_web('intern_quiet',$error,$data,$action,$list): the listmaster won't be noticied
2. user error:
   reject_report_web('user',$error,$data,$action, $list)
3. non authorization:
   reject_report_web('auth',$error,$data,$action, $list)

IN:

1. type(+): 'intern'|'intern_quiet'|'user'|'auth'
2. error(+): SCALAR - depends on $type:
   • 'intern': $error in listmaster_notification.tt2 and possibly $i_err.msg in error.tt2
   • 'intern_quiet': possibly $i_err.msg in error.tt2
   • 'user': $u_err.msg in error.tt2
   • 'auth': $reason in authorization_reject.tt2
3. data: ref(HASH) - for variable instantiation in notice.tt2
4. action(+): SCALAR - the rejected actin, $xx.action in error.tt2, $action in listmaster_notification.tt2
5. list: '' ref(List)
6. user: SCALAR - the user for listmaster notification
7. robot: SCALAR - robot for listmaster notification

OUT: 1 undef

Concerns positive notices of web commands.

IN:

1. msg: $notice.msg in notice.tt2
2. data: ref(HASH) - for variable instantiation in notice.tt2
3. action: SCALAR - the noticed command, $notice.cmd in notice.tt2

OUT: 1 undef