Organization customization
The organization config modifies a server to meet common organizational use cases such as:
- Presenting users with a legal agreement for acceptance when logging in.
- Displaying a corporate logo in the user interface and on generated email messages.
- Restricting user accounts to specified internet domains.
Configuration files
Customizations are determined by the configuration files under the following folder:
pageseeder/webapp/WEB-INF/config/template/[project]/organization
To make the customizations server-wide, add the following to the global.properties
:
globalTemplate=[project]
The main XML file is:
template/[project]/organization/organization-config.xml
It uses the following structure:
<organization-config> <email>...</email> <ui>...</ui> <security>...</security> </organization-config>
Messages can be customized as follows:
- The message formatting (logo, color-scheme).
- Legal boilerplate text (message footer).
- DKIM domain email key.
- The location of message endpoints (links) such as “unsubscribe”.
Set globalTemplate
in global.properties
to a project to customize the default server settings. Otherwise, customizations are applied only 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 following order. All attributes are required except for the following:
dkim/@*
and
images/@prefix
<dkim>
Use this element to configure a DKIM signature which reduces the chances of messages being treated as SPAM. Without a specific configuration, the system defaults to the pageseeder.com
DKIM. Using a DKIM signature that matches the domain of the message is more likely to ensure the delivery of messages.
@domain
– the domain of the sender email address for the emails.@selector
– can be any text as long as it is a unique TXT record in your DNS (for examplemail
). Required if@domain
is specified.@disabled
– iftrue
, messages are not signed with DKIM.
To use a specific DKIM signature, an email-private-key.der
must be uploaded to PageSeeder and a TXT record created in the DNS as described following.
Create a DKIM signature
To create DKIM private and public keys, use the following commands on a Linux system:
$ 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
Use the generated filename – email-private-key.der
– to upload it using the PageSeeder user interface in the following folder:
config/template/[project]/organization
If you copy the file to this location using Linux make it readable to PageSeeder using the following command:
$ chown pageseeder:pageseeder email-private-key.der
DKIM also requires a TXT record in the DNS for the email domain that matches the @domain
and @selector
in the <dkim>
element. The content of the TXT record must be as follows:
name: [selector]._domainkey value: v=DKIM1;k=rsa;p=[public key]
If the email domain is a subdomain you can create the TXT record on the main domain and add .[subdomain]
to the name. For example with email domain acme.example.org
create the following TXT record on the example.org
domain:
name: [selector]._domainkey.acme value: v=DKIM1;k=rsa;p=[public key]
<emails>
This element requires @domain
which is the email domain on all “from”, “reply to” and other email addresses. On certain messages, this is 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
<sender>
Requires @name
and @email
which are 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 app 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-color
. See <style>
below.
The @prefix
attribute is optional, but if used, the prefix value applies to all images and the app under the prefix URL must serve all images under the weborganic/email
folder.
<application>
Requires @name
which replaces the name “PageSeeder” in the text of all emails and @homepage
, which is the home URL of the app.
<footer>
Requires @text
which appears 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. (for example:font-family="'Helvetica Neue', 'Droid Sans', Helvetica, sans-serif"
).<header>
– requires the expression of@background-color
and@text-color
in hex color format (for example:background-color ="#f7f7f7"
).<banner>
– requires the expression of@background-color
and@text-color
in hex color format (for example:background-color ="#f7f7f7"
). The@type
attribute applies to the following email templates:security
– change-email-confirm, change-password, reset-password-confirmmoderation
– accept-comment, membership-acceptalert
– auto-responder, out-of-office-change, out-of-office-warning, reject-commenttask
– new-comment (task)membership
– membership-complete, membership-confirm, membership-new-member, new-memberdigest
– 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 (for example: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> <account-home> <link href="https://example.org" title="Example org"/> <link href="https://example.com" title="Example com" /> <widget name="tasks"> <parameters max-items="6"/> </widget> <widget name="workflows"> <parameters max-items="6"/> </widget> <widget name="recent"> <parameters group-by="group" max-items="10"/> </widget> <widget name="groups" size="large"/> </account-home> </ui>
User interface elements
All elements are optional but must be in the following order. All attributes are required except document/@agree-on
, widget/@size
and parameters/@*
.
<style>
Requires @theme
which must be one of the valid theme colors, and if not any
, locks the user interface to that theme. The valid theme colors are any
, blue
, teal
, green
, yellow
, red
, purple
, steel
, contrast
. The values brick
and lime
are obsolete as of PageSeeder v6.
<images>
Requires @logo-filename
for the organization logo that must be uploaded to the organization/style
folder. The image is displayed on the sign in/out pages and on the top left corner of the account pages. Using 1400 x 73 pixel images is obsolete as of PageSeeder v6.
An @icon-filename
can also be provided to be displayed on the top left corner of the project, group, admin pages. It must fit within a square and be uploaded to the organization/style
folder.
For best results, the recommended file format for these images is SVG. They must have a transparent background and use white or light colors as they are displayed against a dark background.
<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 toall
,login
,signup
. Links to each document appear in the page footer. Where@agree-on
is set, a link to that document also appears on the get started (signup) page or login page or both. On these pages, the document is displayed with a checkbox for users to indicate acceptance before they can activate their account or sign in.
The creation and upload of each document to the following folder must follow the convention of filename [name].md
and use the same markdown format as terms.md
, privacy.md
, or cookies.md
.
config/template/[project]/organization
<account-home>
This element add links and overrides the widgets that appear on the PageSeeder home page for all user accounts. It can contain zero or more <link>
or <widget>
elements in the order you want these displayed on the homepage. If there are no <widget>
elements then the default widgets are displayed. It requires PageSeeder v6 or higher.
<link>
– requires@href
and@title
. It displays a link to the URL in@href
with the label@title
.<widget>
– requires@name
and optionally@size
. The@size
can besmall
,medium
orlarge
depending on the width you want the widget to be.<parameters>
– can appear zero or more times inside<widget>
and can have any supported attributes.
For supported widget/@name
and <parameter>
attributes see Widgets in the PageSeeder Help .
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 following order. 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 are able to sign in. A project can also be listed, but that only permits members of the project to sign in, 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 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 are able to sign in.
<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 receives an error returned. Any existing member that tries to change their address to a domain that is not on the list also generates an error.
Member accounts with a role of Administrator are not restricted by the constraints set in the security elements.