Configuration

Configuration manual for PageSeeder

Organization customization

The organization config makes customization easier by supporting:

  • The acceptance of a legal agreement at login.
  • Branded pages and email templates.
  • Restricting membership and login to email accounts on specific domains.

Note

Organization customization is only enabled for users with a “Developer” or “Service provider”  license.

Configuration files

Customizations are stored as a collection of configuration files in the following folder under PageSeeder:

template/[project]/organization

To make the customizations server-wide, add the following to the template.properties:

customFolder=[project]

The main XML file is:

template/[project]/organization/organization-config.xml

It uses structure detailed below:

<organization-config>
  <email>...</email>
  <ui>...</ui>
  <security>...</security>
</organization-config>

Email

Allows emails to be customized as follows:

  • Visuals (logo, color-scheme)
  • Legal (footer)
  • DKIM domain email key
  • Endpoints/links in email

Note

If customFolder in template.properties is set to a project, those customizations will become the default server settings, otherwise they will only apply to email messages specific to that project.

Example <email> config element:

<email>
      <dkim                  domain="example.org"
                                  selector="mail" />

     <emails                 domain="example.org" />
 
     <sender                        name="My app"
                        email="myapp@example.org" />
 
    <links     prefix="https://example.org/email" />

    <images
        prefix="https://example.org/images/email"
                   logo-filename="email-logo.png" />

   <application                     name="My app"
                   homepage="https://example.org"
              helppage="https://example.org/help" />

   <footer          text="My company name inc,
                        123 My street address,
                            NSW 2000, Australia" />
   <style>
         <text  font-family="'Helvetica Neue',
                         'Droid Sans',sans-serif" />

        <header        background-color="#f7f7f7"
                             text-color="#1179D2" />

        <banner                   type="security"
                       background-color="#f70000"
                             text-color="#1179D2" />

        <banner                      type="alert"
                       background-color="#f70000"
                             text-color="#1179D2" />

       <footer         background-color="#f7f7f7"
                                text-color="#999" />
  </style>
</email>

Email elements

All elements are optional but must be in the order below. All attributes are required except for dkim/@* and images/@prefix.

<dkim>

Use this element to configure a DKIM  signature which will reduce the chances of messages being treated as SPAM. Without a specific configuration, the system will default to the pageseeder.com DKIM. This will not be as effective.

To create DKIM private and public keys, use the following on Linux:

$ openssl genrsa -out email-private-key 2048
$ openssl rsa -in email-private-key -out email-public-key -pubout -outform PEM
$ openssl pkcs8 -topk8 -nocrypt -in email-private-key -out
           email-private-key.der -outform der

Using this file name, the email-private-key.der file must be uploaded to the following folder:

template/[project]/organization

DKIM will also require the following TXT DNS record under the email domain that matches the @domain and @selector in the <dkim> element:

   name: [selector]._domainkey
   value: v=DKIM1;k=rsa;p=[public key]

Note

Adding the attribute disabled="true" on the <dkim> element will ensure there is no DKIM signing of emails.

<emails>

Requires @domain which is the email domain on all “from”, “reply to” and other email addresses. On certain message this will be overridden by <sender>.

Use of this element requires configuring an email server or MX record so messages sent to this domain are sent forward to the PageSeeder server.

For example if the domain="myapp.example.org" and the PageSeeder server is ps.example.org then the MX record could be:

name: myapp.example.org
value: ps.example.org
priority: 10
TTL: 3600

Note

After modifying @domain PageSeeder must be restarted to allow incoming emails with that domain to be accepted.

<sender>

Requires @name and @email which will be used in the Sender header and some of the From headers for all emails.

<links>

Requires @prefix which is the prefix used on all permalinks in the email. In the example above, the following URLs must be supported by the application directly, or by redirecting to the PageSeeder equivalent URL, see Email permalinks.

  • http://example.org/email/changeemail
  • http://example.org/email/changepassword
  • http://example.org/email/comment
  • http://example.org/email/comments
  • http://example.org/email/download
  • http://example.org/email/getstarted
  • http://example.org/email/home
  • http://example.org/email/members
  • http://example.org/email/moderatecommment
  • http://example.org/email/moderatemember
  • http://example.org/email/mydetails
  • http://example.org/email/mygroups
  • http://example.org/email/myinvitation
  • http://example.org/email/myoptions
  • http://example.org/email/unsubscribe
  • http://example.org/email/uri
  • http://example.org/email/unsubscribe
  • http://example.org/email/workflow

<images>

Requires the @logo-filename to reference a 256 wide x 60 high pixels logo to be placed in the organization/style folder. If the image does not have a transparent background, the background must match the header/@background-colour. See <style> below.

The @prefix attribute is optional but if used, the prefix value applies to all images and the application under the prefix URL must serve all images under the weborganic/email folder.

<application>

Requires @name which will replace the name "PageSeeder" in the text of all emails and @homepage which is the home URL of the application.

<footer>

Requires @text which will appear at the bottom of the footer in all emails. This usually includes the organizations address and contact details plus any statutory information.

<style>

This element controls email styling and can contain any of the optional elements in the following order:

  • <text> requires @font-family a comma-separated list of fonts to be used for all email text. (e.g. font-family="'Helvetica Neue', 'Droid Sans', Helvetica, sans-serif" ).
  • <header> requires the expression of @background-color and @text-color  in hex color format  (e.g. background-color ="#f7f7f7" ).
  • <banner> requires the expression of @background-color and @text-color in hex color format (e.g. background-color ="#f7f7f7" ).  The @type attribute applies to the following email templates:
    • security – change-email-confirm, change-password, reset-password-confirm
    • moderation – accept-comment, membership-accept
    • alert – auto-responder, out-of-office-change, out-of-office-warning, reject-comment
    • task – new-comment (task)
    • membership – membership-complete, membership-confirm, membership-new-member, new-member
    • digest – comment-digest
    • Email templates with no <banner> – new-comment (non-task), new-uri, new-version
  • <footer> requires the expression of @background-color and @text-color in hex color format  (e.g. background-color ="#f7f7f7" ).

User interface

Supports the following modifications to the interface:

  • Visual – changes to logo, color-scheme,
  • Legal – allows for the display of agreement documents such as:
    • Terms of use / User agreement / Terms and conditions / Terms of Service
    • Privacy policy / Data policy
    • Cookies policy

Example <ui> config element:

<ui>
 <style                 theme="lime" />
 <images logo-filename="ui-logo.png" />
  <legal>
    <document           name="terms"
                title="Terms of use"
                      agree-on="all" />
    <document         name="privacy"
              title="Privacy policy"
                   agree-on="signup" />
    <document         name="cookies"
               title="Cookie policy"
                    agree-on="login" />
     <document      name="copyright" 
            title="Copyright policy" />
  </legal>
</ui>

User interface elements

All elements are optional but must be in the order below. All attributes are required except document/@agree-on.

<style>

Requires @theme which must be one of any,blue,brick,lime,red and if not any will lock the user interface to that theme.

<images>

Requires @logo-filename for the organization logo. The image should be 1400 pixels wide x 73 pixels high and must be uploaded to the organization/style folder.

<legal>

This element can define multiple, organization-specific <document> elements for the footer, get started and login pages.

  • <document> requires @name and @title and optionally @agree-on. It can be set to all, login, signup. Links to each document will appear in the page footer. Where @agree-on is set, a link to that document will also appear on the get started (signup) page or login page or both. On these pages, the document will be displayed with a check box for users to indicate acceptance before they can activate their account or log in.

The creation and upload of each document to the folder below, must follow the convention of filename [name].md and use the same markdown format as terms.md, privacy.md, or cookies.md.

template/[project]/organization

Security

Allows PageSeeder security to be customized as follows:

  • Login is restricted to members of certain groups,
  • Restrict members to certain email domains,
  • Expire tokens after a certain amount of time.

Example <security> config element:

<security>
  <login groups="example-editors,example-config"
                               projects="config" />

  <token                  type="activate-member"
                               expiration="P90D" />

  <token                   type="reset-password"
                            expiration="P2DT12H" />
  <members>
    <email               domain="*.example1.org" />
    <email                 domain="example2.org" />
    <email                 domain="example3.net" />
  </members>
</security>

 

Security elements

All elements are optional but must be in the order below. All attributes are required except login/@groups and login/@projects.

<login>

An optional attribute, @groups is a comma separated list of full group names. Only members of the groups in the list is able to login. A project can also be listed but that will only permit members of the project to login, NOT members of the groups under the project.

Another optional attribute is @projects. It is also a comma separated list of full project names. Projects listed in this attribute will allow the login of both members of the projects and members of any groups under the listed projects.

If both are specified, then members from both will be able to login.

<token>

Requires @type and @expiration attributes to change the default expiration time for a token. There can be multiple token elements with one of the following values in the @type attribute:

  • activate-member
  • change-email
  • remember-me
  • reset-password 

The value of the @expiration attribute must be in ISO 8601 duration  format and use ONLY days, hours or minutes. For example, expiration="P2DT12H" which translates to 2 days and 12 hours.

<members>

This element can be used to list the allowable email domains for members and can contain one or more <email> elements.

  • <email> requires a @domain attribute which can be prefixed by *. to allow all sub-domains of that domain.

Anyone trying to create an account with a domain that is not in the list will have an error returned. Any existing member that tries to change their address to a domain that is not on the list will also generate an error.

Note

Member accounts with a role of Administrator are not restricted by the constraints set in the security elements.

Created on , last edited on