@@ -685,26 +685,65 @@ behaviour:
685685 (like, e.g., product codes). For these roundup needs to match the
686686 numeric name and should never match an ID. In this case you can set
687687 ``try_id_parsing='no'``.
688- - The ``msg_header_property`` is used in the mail gateway when sending
689- out messages: By default roundup creates headers of the form::
688+ - The ``msg_header_property`` is used by the mail gateway when sending
689+ out messages. When a link or multilink property of an issue changes,
690+ roundup creates email headers of the form::
690691
691692 X-Roundup-issue-prop: value
692693
693- for all properties prop of issue that have a ``name`` property. This
694- definition allows to override the name of the property used for
695- generating headers. A common use-case is adding a mail-header with
696- the ``assigned_to`` property to allow user mail-filtering of
697- issue-emails for which they're responsible. In that case setting::
694+ where ``value`` is the ``name`` property for the linked item(s).
695+ For example, if you have a multilink for attached_files in your
696+ issue, you will see a header::
697+
698+ X-Roundup-issue-attached_files: MySpecialFile.doc, HisResume.txt
699+
700+ when the class for attached files is defined as::
701+
702+ file = FileClass(db, "file",
703+ name=String())
704+
705+ ``MySpecialFile.doc`` is the name for the file object.
706+
707+ If you have an ``assigned_to`` property in your issue class that
708+ links to the user class and you want to add a header::
709+
710+ X-Roundup-issue-assigned_to: ...
711+
712+ so that the mail recipients can filter emails where
713+ ``X-Roundup-issue-assigned_to: name`` that contains their
714+ username. The user class is defined as::
715+
716+ user = Class(db, "user",
717+ username=String(),
718+ password=Password(),
719+ address=String(),
720+ realname=String(),
721+ phone=String(),
722+ organisation=String(),
723+ alternate_addresses=String(),
724+ queries=Multilink('query'),
725+ roles=String(), # comma-separated string of Role names
726+ timezone=String())
727+
728+ Because there is no ``name`` parameter for the user class, there
729+ will be no header. However setting::
730+
731+ assigned_to=Link("user", msg_header_property="username")
732+
733+ will make the mail gateway generate an ``X-Roundup-issue-assigned_to``
734+ using the username property of the linked user.
735+
736+ Assume assigned_to for an issue is linked to the user with
737+ username=joe_user, setting::
698738
699739 msg_header_property="username"
700740
701741 for the assigned_to property will generated message headers of the
702742 form::
703-
743+
704744 X-Roundup-issue-assigned_to: joe_user
705745
706- for issues where joe_user is the username of the person
707- responsible for this issue.
746+ for emails sent on issues where joe_user has been assigned to the issue.
708747
709748 If this property is set to the empty string "", it will prevent
710749 the header from being generated on outgoing mail.
0 commit comments