Recipient address

The document function "Recipient address" must be attached to a template if the recipient dialog is to be displayed. In the configuration window, the recipient dialog can be tailored to the solution in various ways. In the configuration, several links refer to the Global Configurations, where the configuration of the different salutation and greeting formulas are stored. The exact wording and translations of the formulas can be customized in the Global Translations.

Example:

<?xml version="1.0"?>
<RecipientAddressesConfiguration>

  <!-- Determines whether the document is a multibrief or not -->
  <IsMultiLetter>true</IsMultiLetter>
  <!-- Maximum allowed number of recipients (0 = no restriction) -->
  <MaxContacts>0</MaxContacts>
  <!-- Determines whether the recipient dialog is opened in the detailed view. -->
  <FullDetailMode>true</FullDetailMode>
  
  <!-- Address types (e.g. To;Cc;Bcc) -->
  <AddressingTypes>{D[Recipients.AddressingType.To]};{D[Recipients.AddressingType.Cc]};{D[Recipients.AddressingType.Bcc]}</AddressingTypes>
  
  <!-- General recipient configuration -->
  {[Recipients.GeneralRecipientsConfiguration]}
  
  <!-- AddressProvider configuration -->
  {[Recipients.ProviderConfiguration]}
  
  <!-- Salutation configuration -->
  {[Recipients.SalutationConfiguration]}
  
  <!-- Letter salutation configuration -->
  {[Recipients.LetterSalutationConfiguration]}
  
  <!-- Greeting formula configuration -->
  {[Recipients.GreetingFormulaConfiguration]}
  
  <!-- Shipping method configuration -->
  {[Recipients.ShippingMethodConfiguration]}
  
  <!-- Simple view configuration -->
  {[Recipients.SimpleViewConfiguration]}
  
</RecipientAddressesConfiguration>

Configurations in the document function

Since these configurations are template-specific, they are each written directly to the "Recipient address" document function. The configuration looks like this:

• IsMultiLetter
  Can contain trueor false and determines whether the template is a multi letter or not.
  Specific to multi letter: Only one recipient is displayed at a time and it is possible to switch back and forth between recipients.
  Typical Non-multi letter: A protocol where all recipients of a type are listed in list form in "present".
• MaxContacts
  Determines the maximum number of recipients that can be added.
  0 means that there is no upper limit.
• FullDetailMode
  Can contain trueor false and determines whether the following details are displayed in the dialog.
  
• AddressingTypes
  Here display names for the 3 address types can be configured, e.g. To;Cc;Bcc or Present;Absent;Mailing list, depending on the purpose of the address types.

General configurations

The general configurations are swapped out to the Global Configurations. Therefore, the configuration in the document function looks like this:

  <!-- General recipients configuration -->
  {[Recipients.GeneralRecipientsConfiguration]}

The configuration in the Global Configurations looks like this:

• UseEnglishCountryNames
  Can contain true or false and determines whether country names are always English (true) or whether they are output in the language of the current machine's .NET Framework installation (usually corresponds to the system language) (false).
• PreferredRecipientId
  If the template is called via Connect and if recipients are defined in the Connect file: Here the id is used to determine which recipient should be selected.
• CapitalizedCities
  Can contain true or false or be empty or nonexistent. Determines whether the city names in the address block are written in CAPITAL LETTERS (true) or not (false). If the element is empty or nonexistent, this option is determined by the respective address provider. For manually created contacts, lowercase letters are used by default (false).
• SalutationOnSeparateLine
  Can contain true or false or be empty or nonexistent. Determines whether the salutation in the address block is on a separate line (true) or on the same line as the name (false). If the element is empty or nonexistent, this option is determined by the respective address provider. For manually created contacts, the salutation is on its own line by default (true).
• DefaultLanguageCode
  Currently has no effect.
• DefaultCountryCode
  Here the country code of the default country can be set. The default country is always selected at the beginning.
• CustomCountries
  Here countries can be added with the following pattern, which are nonexistent in the dialog by default:
  <CustomCountry Name="American Virgin Islands" EnglishName="United States Virgin Islands" ISO="VI" />

Address Provider

The configuration of the address providers is outsourced to the Global Configurations. Therefore, the configuration in the document function looks like this:

  <!-- AddressProvider configuration -->
  {[Recipients.ProviderConfiguration]}

For more information about how to configure the address providers, see Address Interfaces.

Salutations, letter salutations, greetings, shipping methods

The configuration of salutations, letter salutations, greetings and shipping methods is outsourced to the Global Configurations. The configuration in the document function looks like this:

  <!-- Salutation configuration -->
  {[Recipients.SalutationConfiguration]}
  
  <!-- Letter salutation configuration -->
  {[Recipients.LetterSalutationConfiguration]}
  
  <!-- Greeting formula configuration -->
  {[Recipients.GreetingFormulaConfiguration]}
  
  <!-- Shipping method configuration -->
  {[Recipients.ShippingMethodConfiguration]}

The configuration in the Global Configurations looks like this:

Note

Generally, especially for multilingual solutions, the text is translated into the respective target language via the Global Translations.

Salutation

All available salutations of the recipient are defined here, for example "Mr.", "Mrs.", "Family", etc.

Note

In "ContactMapping", this is referred to as "SalutationShort".

Depending on the gender and number of persons, the most suitable salutation is loaded from the configuration.

Example configuration

• Global Configurations entries – English
• Entries Global Configurations – Translated
• Global Translations entries

<!-- SalutationConfiguration -->
<SalutationConfiguration>
  <ArrayOfSalutation>
    <Salutation>
      <DisplayName>[Salutation]</DisplayName>
      <IsDefault>true</IsDefault>
      <Qualification>
        <Id>Label</Id>
        <IsDefault>false</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Mr</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Mr</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Mrs</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Mrs</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Family</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Family</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Company</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Company</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Mr and Mrs</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>MrAndMrs</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Mrs. and Mr.</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>MrsAndMr</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Sirs</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Sirs</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Ladies</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Ladies</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
  </ArrayOfSalutation>
</SalutationConfiguration>

Elements inside <Salutation>...</Salutation>:

• DisplayName: Text of the salutation, e.g. "Mr." or "Ms." (for multilingual solutions the Global Translations are used).
• IsDefault determines whether this salutation should be the placeholder salutation.
  The English DisplayName as placeholder salutation usually is "[Salutation]". By means of square brackets, the user is made aware that this is only a placeholder.
  As soon as a qualification (see next point) applies, the salutation with the corresponding qualification is automatically selected, in order for the placeholder to not be selected anymore. Thus, the user normally does not have to worry about replacing the placeholder with the meaningful salutation.
• Qualification: Within <Qualification>...</Qualification> properties can be specified by which the salutation should become active automatically if necessary (see subitems).
  • Qualification/Id: Contains one of the following values:
    • Label: Will be set as value at the placeholder salutation (normally "[Salutation]") respectively. This has the effect that this salutation is never automatically selected.
    • Mr: If exactly one male person is recognized in the first name.
    • Mrs: If exactly one female person is recognized in the first name.
    • Family: If a family is recognized in the first name. A family is recognized if more than two first names are recognized or if one or more of these strings are included: "," (comma), " mit ", " avec ", " con ", " with "
    • Company: If the recipient is passed from an Address Provider with CompanyData as AddressType.
    • MrAndMrs: If exactly two persons are recognized in the first name: first a male person, then a female person.
    • MrsAndMr: If exactly two persons are recognized in the first name: first a female person, then a male person.
      If there is no salutation with MrsAndMr, a salutation with MrAndMrs is selected instead.
    • Sirs: If exactly two male persons are recognized in the first name.
    • Ladies: If exactly two female persons are recognized in the first name.
  • Qualification/IsDefault: Determines whether this salutation should be selected automatically. true: This salutation is preferred if the Qualification/Id applies. If Qualification/IsDefault is set to false for all salutations where Qualification/Id applies, the first salutation where Qualification/Id applies will be selected.

Letter salutation

Here you can define all available salutations of the recipient, e.g. "Dear Sir", "Good day Mrs.", etc.

Note

Im "ContactMapping" wird dies als "Salutation" bezeichnet.

Depending on the gender and number of people, the most appropriate salutation is loaded from the configuration. Placeholders can be used in the letter salutation, which are replaced with the following attributes of the selected recipient:

• {FirstName}
• {LastName}
• {Title}
• {Profession}
• {Position}: Function/Job description
• {SecondName}

For example, if the letter salutation is to include the title and last name, the following text must be configured:

Dear Mr {Title} {LastName}

If a placeholder is not found in the recipient, it is removed and it is ensured that there are not two consecutive spaces in the salutation.

Example configuration

• Global Configurations entries – English
• Global Configurations entries – Translated
• Global Translations entries

<!-- LetterSalutationConfiguration -->
<LetterSalutationConfiguration>
  <ArrayOfSalutation>
    <Salutation>
      <DisplayName>[Letter salutation]</DisplayName>
      <IsDefault>true</IsDefault>
      <Qualification>
        <Id>Label</Id>
        <IsDefault>false</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Dear Sir</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Mr</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Good day Mr. {LastName}</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Mr</Id>
        <IsDefault>false</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Dear Mr. {LastName}</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Mr</Id>
        <IsDefault>false</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Dear {FirstName}</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Mr</Id>
        <IsDefault>false</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Dear Mrs. {LastName}</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Mrs</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Good day Mrs. {LastName}</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Mrs</Id>
        <IsDefault>false</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Dear {FirstName}</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Mrs</Id>
        <IsDefault>false</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Dear Mr. and Ms. {LastName}</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>MrAndMrs</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Dear Ms. and Mr. {LastName}</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>MrsAndMr</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Ladies, Gentlemen</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>MrAndMrs</Id>
        <IsDefault>false</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Dear Madam, dear Sir</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>MrAndMrs</Id>
        <IsDefault>false</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Ladies and Gentlemen</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Company</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Dear Sirs</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Sirs</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Dear Ladies</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Ladies</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
    <Salutation>
      <DisplayName>Dear family {LastName}</DisplayName>
      <IsDefault>false</IsDefault>
      <Qualification>
        <Id>Family</Id>
        <IsDefault>true</IsDefault>
      </Qualification>
    </Salutation>
  </ArrayOfSalutation>
</LetterSalutationConfiguration>

Elements inside <Salutation>...</Salutation>:

• DisplayName: text of the letter salutation, e.g. "Dear Mr. {FirstName}" or "Good day Mrs. {FirstName}" (for multilingual solutions the Global Translations are used).
• IsDefault determines whether this letter salutation should be the placeholder letter salutation.
  The English DisplayName as placeholder salutation usually is "[Letter salutation]". By means of square brackets, the user is made aware that this is only a placeholder.
  As soon as a qualification (see next point) applies, the letter salutation with the corresponding qualification is automatically selected, in order for the placeholder to not be selected anymore. Thus, the user normally does not have to worry about replacing the placeholder with the meaningful letter salutation.
  • Qualification: Within <Qualification>...</Qualification> properties can be specified by which the letter salutation should become active automatically if necessary (see subitems).
  • Qualification/Id: Contains one of the following values:
    • Label: Will be set as value at the placeholder salutation (normally "[Letter salutation]"). This has the effect that this letter salutation is never automatically selected.
    • Mr: If exactly one male Person is recognized in the first name.
    • Mrs: If exactly one female Person is recognized in the first name.
    • Family: If a family is recognized in the first name. A family is recognized if more than two first names are recognized or if one or more of these strings are included: "," (comma), " with ", " avec ", " con ", " with "
    • Company: If the recipient is passed from an Address Provider with CompanyData as AddressType. Special logic, only for backward compatibility:
      If no letter address with Company is found, a following letter address is searched for: Qualification/Id = MrAndMrs, Qualification/IsPlural = true, Qualification/Gender = Both, Qualification/IsDefault doesn`t matter
      
    • MrAndMrs: If exactly two persons are recognized in the first name: first a male person, then a female person.
      See also "Special logic, for backward compatibility only" in the Company item.
    • MrsAndMr: If exactly two persons are recognized in the first name: first a female person, then a male person.
      If there is no salutation with MrsAndMr, a salutation with MrAndMrs is selected instead.
    • Sirs: If exactly two male persons are recognized in the first name.
    • Ladies: If exactly two female persons are recognized in the first name.
  • Qualification/IsDefault: Determines whether this salutation should be selected automatically. true: This letter salutation is preferred if the Qualification/Id is true. If Qualification/IsDefault is set to false for all letter salutations where Qualification/Id applies, the first salutation where Qualification/Id applies will be selected.

Greeting formula

All available greeting formulas are defined here, e.g. "Kind regards", "Affectionate greetings", etc.

Example configuration

• Global Configurations entries – English
• Global Configurations entries – Translated
• Global Translations entries

        <!-- GreetingFormulaConfiguration -->
        <GreetingFormulaConfiguration>
          <ArrayOfGreetingFormula>
            <GreetingFormula>
              <DisplayName>[Greeting]</DisplayName>
              <IsDefault>true</IsDefault>
              <Qualification>
                <IsDefault>false</IsDefault>
              </Qualification>
            </GreetingFormula>
            <GreetingFormula>
              <DisplayName>Kind regards</DisplayName>
              <IsDefault>false</IsDefault>
              <Qualification>
                <IsDefault>true</IsDefault>
              </Qualification>
            </GreetingFormula>
            <GreetingFormula>
              <DisplayName>Kind regards</DisplayName>
              <IsDefault>false</IsDefault>
              <Qualification>
                <IsDefault>false</IsDefault>
              </Qualification>
            </GreetingFormula>
            <GreetingFormula>
              <DisplayName>Affectionate regards</DisplayName>
              <IsDefault>false</IsDefault>
              <Qualification>
                <IsDefault>false</IsDefault>
              </Qualification>
            </GreetingFormula>
            <GreetingFormula>
              <DisplayName>Affectionate regards</DisplayName>
              <IsDefault>false</IsDefault>
              <Qualification>
                <IsDefault>false</IsDefault>
              </Qualification>
            </GreetingFormula>
            <GreetingFormula>
              <DisplayName>Regards</DisplayName>
              <IsDefault>false</IsDefault>
              <Qualification>
                <IsDefault>false</IsDefault>
              </Qualification>
            </GreetingFormula>
          </ArrayOfGreetingFormula>
        </GreetingFormulaConfiguration>

Elements inside <GreetingFormula>...</GreetingFormula>:

• DisplayName: Text of the greeting, e.g. "Kind regards" or "Affectionate regards" (for multilingual solutions the Global Translations are used).
• IsDefault determines whether this greeting should be the placeholder greeting.
  The English DisplayName as placeholder greeting formula usually is "[Greeting formula]". By means of square brackets the user is made aware that this is only a placeholder.
  As soon as a qualification (see next point) applies, the greeting formula with the corresponding qualification is automatically selected, so that the placeholder is no longer selected. Thus, the user normally does not have to worry about replacing the placeholder with the meaningful greeting formula.
• Qualification:
  • Qualification/IsDefault determines whether this greeting formula should be selected automatically. If Qualification/IsDefault is set to false for all greeting formulas, the first greeting formula will be selected.

Shipping method

Here all available shipping methods (or Transmissions) of the recipient are defined, for example "A-Priority" or "Registered mail".

Example configuration

In this example configuration, the shipping method "Registered mail" is preselected in each case (see IsPreselected).

• Global Configurations entries – English
• Global Configurations entries – Translated
• Global Translations entries

        <ShippingMethodConfiguration>
          <ArrayOfShippingMethod>
            <ShippingMethod>
              <DisplayName>[Shipping method]</DisplayName>
              <TypeOfDistribution>DefaultText</TypeOfDistribution>
              <IsPreselected>false</IsPreselected>
            </ShippingMethod>
            <ShippingMethod>
              <DisplayName>A-Priority</DisplayName>
              <TypeOfDistribution>APost</TypeOfDistribution>
              <IsPreselected>false</IsPreselected>
            </ShippingMethod>
            <ShippingMethod>
              <DisplayName>Registered mail</DisplayName>
              <TypeOfDistribution>RegisteredMail</TypeOfDistribution>
              <IsPreselected>true</IsPreselected>
            </ShippingMethod>
            <ShippingMethod>
              <DisplayName>Express</DisplayName>
              <TypeOfDistribution>Express</TypeOfDistribution>
              <IsPreselected>false</IsPreselected>
            </ShippingMethod>
          </ArrayOfShippingMethod>
        </ShippingMethodConfiguration>

Elements inside <ShippingMethod>...</ShippingMethod>:

• DisplayName: Text of the shipping method, e.g. "registered mail" or "by e-mail" (for multilingual solutions the Global Translations are used).
• TypeOfDistribution: A unique identifier (e.g. "RegisteredMail") for the respective shipping method is defined here. It can be freely selected.
  For the placeholder shipping method, TypeOfDistribution must be set to DefaultText. The English DisplayName as placeholder shipping method usually is "[Shipping method]". It is not displayed in the document.
• IsPreselected: Determines the shipping method which is preselected for new recipients (true: should be preselected, false or not present: should not be preselected).
  This preselection is only valid for recipients that are applied in the recipient dialog by creating or by accepting from an address provider (e.g. it is not valid for recipients that are transferred via Connect).
  IsPreselected may only be set to true for one shipping method.
  If no preselected shipping method is configured, then the placeholder shipping method (see TypeOfDistribution) is preselected.

Recipient details window

Recipients can be entered and customized manually in the recipient details window.

The recipient details window performs automatic adjustments to the recipient data, with the aim of assisting the user in entering recipient data:

• Salutation, letter salutation:
  These are set once the first name field detects which salutation combination fits.
  When changing the salutation, the corresponding letter salutation is also automatically selected and vice versa.
• Greeting formula:
  is set as soon as something is entered in the first name field.
• CheckBoxes
  • Salutation on separate line:
    . Is disabled as soon as salutation is not displayed in address, if address contains company name or if address contains second person.
  • Person over company:
    
    • Is disabled when no company name is shown in the address or when no person is present.
    • Is disabled as soon as the address type is set to "Private".
  • Show company:
    Is activated as soon as the address type is set to "Business".
  • Show additional names:
    Is disabled as soon as none of the people have another name.
• Address type:
  
  • Is set to "Business" as soon as no private address data is available while business address data is available.
  • Is set to "Private" as soon as no business address data is available while private address data is available.
• Show function:
  Is disabled as soon as the address contains the second person.

If recipients that have not been entered manually (e.g. from address providers or via Connect) do not fulfill the above rules, this will cause the data to change as soon as the recipient details window is opened. It is therefore of advantage if recipients from external sources fulfill the above rules.