MIME Engine

From ESM Wiki
Jump to: navigation, search

Contents


Introduction

MIME engine is a generic engine that encapsulates different methods for working with MIME formated email messages. MIME engine node is <mime>:

<mppd>
    <engines>
        <mime id="mime_engine">
            ...
        </mime>
    </engines>
</mppd>


Generate method

Generate method performs generation of MIME formated body parts from provided options and exports generated body part string as method result. Subsequent engines and postprocessors in a pipeline may use this result to do their jobs (for example replacing of existing body parts with the one generated). Generate method consists of one or more enclosed generators. Each generator corresponds to a specific type of MIME body part. By using different types of generators and their combinations administrator has a great flexibility in configuring any kind of MIME body part for his/her needs. The following generators are available:

  • Multipart generator -- generates multipart body part that is a container for other body parts.
  • Body part generator -- generates data (or "leaf") body part that contains some useful data and do not contains other body parts inside.
  • Exteranl body part generator -- generates message/external-body links to a data that is not embeded into body part itself.

Generate method is defined with <generate> node under <mime> node. The method must have one root generator. If root generator is of container type (for example multipart) then it may contain another generators inside. As ordinary generic engine generate method may have preconditions and explicit results. Example of generate method:

<mppd>
    <engines>
        <mime>
            <generate id="generate_replacement">
                <precondition>$engines.select_body_part.is_match $EQ yes</precondition>
                <multipart>
                    ...
                </multipart>
                <result id="data"><result>$action.result</result></result>
            </generate>
        </mime>
    </engines>
</mppd>

In this example generate method with ID generate_replacement is defined. Root generator is defined with <multipart> (internal structure will be described further). The method has a precondition and explicit result with ID data.


Multipart generator

Multipart generator generates a body part that actually serves as a container for one or more another body parts. It corresponds to a multipart MIME type. Generator consists of options and one or more another generators. Multipart generator is defined with <multipart> node under <generate> node or under another container-type generator. Multipart subtype is defined with subtype attribute for <multipart> node that may have the following values:

  • mixed -- multipart/mixed content that presents a list of not related body parts; mail user agents will display all parts to a user;
  • alternative (default) -- multipart/alternative content that presents a list of different representation of logically the same body part; mail user agents will display one representation depending on user preferences.

Example:

<multipart subtype="alternative">
    <headers>$body_part.headers</headers>

    <body_part>
        ...
    </body_part>

    <body_part>
        ...
    </body_part>

    <multipart subtype="mixed">
        ...
    </multipart>
</multipart>

In this example multipart/alternative body part consists of two data body parts and one multipart/mixed body part. Additional headers for the body part are copied from existing body part headers.

Multipart generator options and their properties are described in the following table:

OptionProperties
<headers> Description: Additional body part headers that will be added besides those that are mandatory for this type of body part. Headers must be as single string formatted according to MIME standard. One of usage variants is to copy headers from existing body part:
<headers>$body_part.headers</headers>
Type: Template. Spaces are collapsed.
Default: If not specified additional headers are not added.
<multipart>
<body_part>
<external_body_part>
Description: Generators for contained body parts. One or more different generators can be specified.
Type: Generator.
Default: At least on generator must be specified.


Body part generator

Body part generator generates data (or "leaf") body part that contains some useful data and do not contains other body parts inside. The generator makes compliant MIME body part from provided options. Example:

<body_part>
    <headers>X-Custom-Header: my custom header</headers>
    <mime_type>text/html</mime_type>
    <charset>UTF-8</charset>
    <encoding>quoted-printable</encoding>
    <data>
        <![CDATA[
        <html>
            <body>
                Body part of type $body_part.mime_type was stripped by MPP.<br />
                It can be found at <a href="http://qreview.domain.com:20001/attachments.cgi?id=$engines.mysql.save_metadata.insert_id">here</a>.
            </body>
        </html>
        ]]>
    </data>
</body_part>

In this example body part of MIME type text/html is generated with data defined by <data> option. Note that data is enclosed between <![CDATA[ and ]]> character sequences to pass it through XML parsing without been interpreted as markup.

Body part generator options and their properties are described in the following table:

OptionProperties
<headers> Description: Additional body part headers that will be added besides those that are mandatory for this type of body part. Headers must be as single string formatted according to MIME standard. One of usage variants is to copy headers from existing body part:
<headers>$body_part.headers</headers>
Type: Template. Spaces are collapsed.
Default: If not specified additional headers are not added.
<mime_type> Description: Full MIME type (type and subtype separated with "/") of the data for this body part.
Type: Template. Spaces are removed.
Default: text/plain
<mime_type> Description: Full MIME type (type and subtype separated with "/") of the data for this body part. This will be put into Content-Type header.
Type: Template. Spaces are removed.
Default: text/plain
<charset> Description: Charset for the data for this body part. This will be put into Content-Type header as charset attribute. For text data this should be UTF-8 because the data is specified in XML as UTF-8.
Type: Template. Spaces are removed.
Default: UTF-8
<encoding> Description: MIME content transfer encoding with which data will be encoded before inserting into body part. This will be also put into Content-Transfer-Encoding. Option template must evaluate to one of the following values:
  • quoted-printable (default) -- should be used for text data with international characters;
  • 7bit -- should be used for text data with only ASCII characters;
  • 8bit -- should be used for text data with international characters; unlike quoted-printable encoding this is relatively new standard so may be incompatible with some old mail systems;
  • base64 -- should be used for binary data;
Type: Template. Spaces are removed.
Default: quoted-printable
<disposition> Description: Specifies content handling options. Option template must evaluate to one of the following values:
  • inline -- content will be displayed in message inline;
  • attachment -- content will be displayed as attachment (file that may be saved);

This will be put into Content-Disposition header. The option is ignored if <file_name> is specified.

Type: Template. Spaces are removed.
Default: If not specified then disposition is not put into headers.
<file_name> Description: File name for the data. If the option is specified body part will be interpretted as attachment by MUA's. Option template must evaluates to UTF-8 string. This will be put into Content-Disposition as well as Content-Type.
Type: Template. Spaces are removed.
Default: If not specified then body part is not interpretted as attachment.
<data> Description: Body part data template. Data will be appropriatively encoded before putting it to body part. For text body parts strings in template should be of UTF-8 charset. To prevent data from being interpretted as part of XML markup it should be enclosed with <![CDATA[ and ]]> character sequences.
Type: Template. Spaces are collapsed.
Default: No default -- this option is mandatory.


External body part generator

External body part generator generates message/external-body links to a data that is not embeded into body part itself. This is relatively new standard and may be not supported by some MUA's. External body part is defined with <external_body_part> node. For example:

<external_body_part>
    <uri>http://qreview.domain.com:20001/attachments.cgi?id=$engines.mysql.save_metadata.insert_id</uri>
    <content_id>$time6$pid$counter16@$gethostname</content_id>
    <size>$body_part.size</size>
    <body_part_headers>$body_part.headers</body_part_headers>
</external_body_part>

External body part generator options and their properties are described in the following table:

OptionProperties
<headers> Description: Additional body part headers that will be added besides those that are mandatory for this type of body part. Headers must be as single string formatted according to MIME standard. This should be rarely used because all needed headers are added according to other options.
Type: Template. Spaces are collapsed.
Default: If not specified additional headers are not added.
<body_part_headers> Description: Headers for body part to which external body part links. Headers generally should contain Content-Type specifying the type of content and Content-Disposition specifying attachment disposition and file name. Note that headers must be already formated according to MIME standard. One of usage variants is to copy headers from existing body part:
<body_part_headers>$body_part.headers</body_part_headers>
Type: Template. Spaces are collapsed.
Default: If not specified headers will be empty.
<uri> Description: URI for external content that this external body part will be linked to.
Type: Template. Spaces are removed.
Default: None.
<content_id> Description: Standard requires Content-ID header to be present in external body part. This should be a world-wide unique ID for the content and should contain local and domain parts separated with "@" character (like emails). Content ID may be generated as following:
<content_id>$time6$pid$counter16@$gethostname</content_id>
Type: Template. Spaces are removed.
Default: None.
<size> Description: External content size that will be put into headers. This is for informational purposes.
Type: Template. Spaces are removed.
Default: None.


Macros of generate method

The following engine specific macros are available for generate method:

MacroProperties
$counter8
$counter16
$counter32
$counter64
Description: 8-, 16-, 32- and 64-bit counters respectively. Each counters starts from 1 and increments at each evaluation of a macro. A counter wraps around to zero when it reaches maximum value and then starts incrementing again. A counter is not persistent - it is destroyed when MPP stops. Main purpose of counters is to be used in generation of unique file names and ID's. For example the following template is used to generate unique content ID:
<content_id>$time6$pid$counter16@$gethostname</content_id>
Scope: any
Dimensions: none
Stages: all
Arguments: none
$action.result Description: Referes to a generated body part. Can be used in results as following:
    <result id="link">
        <result>$action.result</result>
    </result>
Scope: results
Dimensions: same as action dimensions
Stages: all
Arguments: none


Implicit results of generate method

The following implicit results are calculated by save method:

ResultProperties
result Description: Generated body part.
Dimensions: same as action dimensions


Examples of generate method

In the following example link to external content is generated. Link has three variants: text, html and external body. Depending on user preferences and MUA capabilities one variant will be displayed to a user by a MUA when message will be delivered to user. Other engine results are used in example though this engines are not presented here.

<mppd>
    <engines>
        <mime>
            <generate>
                <multipart subtype="alternative">
                    <headers>$body_part.headers</headers>

                    <body_part>
                        <mime_type>text/plain</mime_type>
                        <charset>UTF-8</charset>
                        <encoding>8bit</encoding>
                        <disposition>inline</disposition>
                        <file_name>file_strip_location.txt</file_name>
                        <data>
                            Body part of type $body_part.mime_type was stripped by MPP.
                            It can be found at http://qreview.domain.com:20001/attachments.cgi?id=$engines.mysql.save_metadata.insert_id
		        </data>
                    </body_part>

                    <body_part>
                        <mime_type>text/html</mime_type>
                        <charset>UTF-8</charset>
                        <encoding>8bit</encoding>
                        <disposition>inline</disposition>
                        <file_name>file_strip_location.html</file_name>
                        <data>
                            <![CDATA[
                                <html>
                                    <body>
                                        Body part of type $body_part.mime_type was stripped by MPP.<br />
                                        It can be found at <a href="http://qreview.domain.com:20001/attachments.cgi?id=$engines.mysql.save_metadata.insert_id">here</a>.
                                    </body>
                                </html>
                            ]]>
                        </data>
                     </body_part>

                     <external_body_part>
                         <uri>http://qreview.domain.com:20001/attachments.cgi?id=$engines.mysql.save_metadata.insert_id</uri>
                         <content_id>$time6$pid$counter16@$gethostname</content_id>
                         <size>$body_part.size</size>
                         <body_part_headers>$body_part.headers</body_part_headers>
                     </external_body_part>

                </multipart>

                <result id="link"><result>$action.result</result></result>
            </generate>
        </mime>
    </engines>
</mppd>

See also

Personal tools