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 "Developer" and "Service provider" PageSeeder licenses.

Configuration files

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

template/[project]/organization
woconfig/[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

If customFolder in template.properties is set to a project then it's customizations will be the default for the whole server, otherwise they will only be used for emails 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="http://example.org/email" />
  <images prefix="http://example.org/images/email" logo-filename="email-logo.png" />
  <application name="My app" homepage="http://example.org" helppage="http://example.org/help"/>
  <footer text="My company pty. ltd., 123 My address, NSW 2000, Australia" />
  <style>
    <text font-family="'Helvetica Neue', 'Droid Sans', Helvetica, 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 your own DKIM  signature which may stop your emails being treated as SPAM. If you don't configure your own the pageseeder.com DKIM will be used which may not be as effective.

If you don't already have DKIM private and public keys they can be created on Linux using:

$ 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

The email-private-key.der must be uploaded to the PageSeeder project files with this name under the template/[project]/organization folder.

DKIM also requires the following TXT DNS record under your email domain matching the @domain and @selector in the <dkim> element:

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

Note

If you add the attribute disabled="true" on the <dkim> element there will be no DKIM signing of emails.

<emails>

Requires @domain which is the email domain that will be on all from, reply to and other email addresses (this is overridden by <sender> below for certain emails) .

If this element is used an email server or MX record will need to be configured to forward messages sent to this domain to the PageSeeder server. For example if 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

<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. For instance in the example above the following URLs would all need to be supported by the application with it's own implementation 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 @logo-filename which is the filename of the organization logo. It should be 256 wide x 60 high pixels in size and can be placed in the woconfig/[project]/organization folder. If the image does not have a transparent background then you may need to match the header/@background-colour to it, see <style> below.

The @prefix attribute is optional and if used then all images will be prefixed by this and all images under the weborganic/email folder will need to be hosted by the application under the prefix URL.

<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. It would usually include the organizations address and any other contact details.

<style>

This element controls the styling of the emails and can contain any of the following optional elements in the order below.

  • <text> requires @font-family which is 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 @background-color and @text-color which are the background and text colors used for the header area. They must be in hex color format  (e.g. background-color ="#f7f7f7" ).
  • <banner> requires @type, @background-color and @text-color which are the background and text colors used for the banner areas. There can be multiple banner elements and the colors must be in hex color format  (e.g. background-color ="#f7f7f7" ). The allowed values for @type are shown below together with the email templates they relate to:
    • 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 without banners: new-comment (non-task), new-uri, new-version
  • <footer> requires @background-color and @text-color which are the background and text colors used for the footer area. They must be in hex color format  (e.g. background-color ="#f7f7f7" ).

User interface

Allows the PageSeeder user interface to be customized as follows:

  • Visuals (logo, color-scheme)
  • Organization specific legal document. For example:
    • 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 which is the filename of the organization logo. It should be 1400 wide x 73 high pixels in size and can be placed in the woconfig/[project]/organization folder.

<legal>

This element defines organization specific documents for the footer, get started and login pages and can contain one or more <document> elements.

  • <document> requires @name and @title and optionally @agree-on which be one of all, login, signup. A link to each documents will appear in the user interface footer. If agree-on is set then a link to that document will also appear on the get started (signup) page, login page or both with a check box users need to tick to agree before activating their account or logging in.

Each document must be created/uploaded to the PageSeeder project files with the filename [name].md under the template/[project]/organization folder and must be in markdown format (e.g. terms.md, privacy.md, cookies.md) .

Security

Allows PageSeeder security to be customized as follows:

  • Login to UI restricted to certain groups
  • Restrict email domains of members
  • Token expiry times

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="*.example.org" />
    <email domain="example.org" />
    <email domain="example.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>

Optional @groups is a comma separated list of full group names. Only members of those groups will be able to login to the user interface. A project can be listed here but will only allow members of that project, NOT groups under the project.

Optional @projects is a comma separated list of full project names. Only members of those projects and any projects/groups under them will be able to login to the user interface.

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

<token>

Requires @type and @expiration which will change the default expiration time for that token (shown in the table below). There can be multiple token elements, type must be one of activate-member, change-email, remember-me, reset-password and the expiration must be in ISO 8601 duration  format using ONLY days, hours or minutes  (e.g. expiration ="P2DT12H" which means 2 days and 12 hours).

<members>

This element can be used to restricts member's email domains to those listed and can contain one or more <email> elements.

  • <email> requires @domain which is an allowed email domain for a member. The domain can be prefixed by *. to allow all sub-domains of that domain.

If a member tries to sign up or change their email to a domain that is not allowed an error message will be returned.

Administrators can always login to the user interface and can have any email domain.

Created on , last edited on